edit

Documentation

Overview

Package edit rewrites the source a model was parsed from. An operation names an element the way symbols name it, the spans of the parse say which bytes carry that element's value or name, and only those bytes are replaced — so comments, blank lines and indentation come back byte-identical. The edited notation is re-parsed and re-analyzed before it is returned: an edit that would make the model unreadable is refused rather than written.

Index

• type Applied
• type Error
  • func (e *Error) Error() string
• type Failure
  • func (f Failure) String() string
• type Model
• type OpKind
• type Operation
  • func AddMember(owner, kind, name string) Operation
  • func Delete(target string, cascade bool) Operation
  • func Rename(target, newName string) Operation
  • func SetValue(target, value string) Operation
• type Result
  • func Apply(m Model, ops []Operation) (*Result, error)

Types

type Applied

type Applied struct {
	OperationIndex int
	Target         string
	// Span is the range replaced; Len is 0 for an insertion.
	Span    source.Span
	OldText string
	NewText string
}

Applied describes one replacement. Batch spans use the original source; sequential spans use the intermediate source seen by that operation.

type Error

type Error struct {
	Failure Failure
	Message string
	// OperationIndex is the operation refused, or -1 for a whole request.
	OperationIndex int
	// Diagnostics are the errors behind a refusal: those of an unreadable new
	// value, or those the edited notation was found to have.
	Diagnostics []passes.Diagnostic
	// Diagnosed is the source the Diagnostics' spans are offsets into: the new
	// value's text, or the edited notation. A refusal still returns no model.
	Diagnosed *source.SourceFile
	// Referring names the elements referring to a declaration whose rename was
	// refused.
	Referring []string
}

Error is a refused edit: which kind of refusal it is, and the evidence for it.

func (*Error) Error

func (e *Error) Error() string

type Failure

type Failure int

Failure is why edits were refused. Every refusal carries one: an edit is never silently dropped.

const (
	// FailureNone is no failure.
	FailureNone Failure = iota
	// FailureNoOperations is a request naming no edit.
	FailureNoOperations
	// FailureUnknownTarget is a target this model declares nothing under.
	FailureUnknownTarget
	// FailureAmbiguousTarget is a target several declarations answer to.
	FailureAmbiguousTarget
	// FailureNotValued is a target that can carry no value.
	FailureNotValued
	// FailureInvalidValue is a new value that does not parse as an expression.
	FailureInvalidValue
	// FailureInvalidName is a new name that does not lex as an identifier.
	FailureInvalidName
	// FailureNotNamed is a target declaring no name to rewrite.
	FailureNotNamed
	// FailureRenameReferenced is a rename that references to the element would
	// not survive.
	FailureRenameReferenced
	// FailureOverlappingEdits is two edits covering the same bytes.
	FailureOverlappingEdits
	// FailureResultInvalid is edited notation carrying errors the original had
	// not.
	FailureResultInvalid
	// FailureOwnerUnknown is an add-member owner that is not declared.
	FailureOwnerUnknown
	// FailureOwnerNotNamespace is an element that cannot contain members.
	FailureOwnerNotNamespace
	// FailureIllegalKind is a declaration kind invalid for the document language.
	FailureIllegalKind
	// FailureMemberNameTaken is a member name already declared by the owner.
	FailureMemberNameTaken
	// FailureDeleteReferenced is a non-cascade delete with live references.
	FailureDeleteReferenced
)

func (Failure) String

func (f Failure) String() string

String returns the lowercase name of the failure, or "unknown".

type Model

type Model struct {
	Source *source.SourceFile
	Root   *ast.RootNamespace
	Index  *symbols.Index
	// ParseDiags and SemDiags are what the original was found to have, so a
	// refusal reports the errors an edit introduced and not ones it inherited.
	ParseDiags []parser.Diagnostic
	SemDiags   []passes.Diagnostic
	// NewIndex hands out an index carrying the libraries the model was analyzed
	// against and no document of its own, for analyzing the edited notation.
	// Nil checks syntax alone.
	NewIndex func() *symbols.Index
	// contains filtered or unexported fields
}

Model is a parsed model to edit: the source that was read, its parse, and the index it was analyzed in.

type OpKind

type OpKind int

OpKind is which of the two source-preserving changes an Operation makes.

const (
	// OpSetValue sets the value of a feature that already exists.
	OpSetValue OpKind = iota
	// OpRename rewrites the name token of a declaration and the references to it.
	OpRename
	// OpAddMember inserts a declaration into a namespace.
	OpAddMember
	// OpDelete removes a declaration and its owned trivia.
	OpDelete
)

type Operation

type Operation struct {
	Kind OpKind
	// Target is the element to edit, by FQN, as symbols name it.
	Target string
	// Value is the new value in SysML notation, for OpSetValue.
	Value string
	// NewName is the new declared name, for OpRename.
	NewName string
	// Owner is the namespace receiving an OpAddMember; empty means the root.
	Owner string
	// Declaration details for OpAddMember.
	MemberKind   string
	MemberName   string
	Type         string
	Multiplicity string
	Specializes  []string
	Cascade      bool
}

Operation is one change to make to a model's source.

func AddMember

func AddMember(owner, kind, name string) Operation

AddMember creates an operation inserting a declaration into owner.

func Delete

func Delete(target string, cascade bool) Operation

Delete creates an operation removing target, optionally including referrers.

func Rename

func Rename(target, newName string) Operation

Rename is an operation rewriting target's declared name to newName.

func SetValue

func SetValue(target, value string) Operation

SetValue is an operation setting target's value to the expression value.

type Result

type Result struct {
	Content []byte
	Applied []Applied
}

Result is the edited notation and what each operation changed.

func Apply

func Apply(m Model, ops []Operation) (*Result, error)

Apply applies every operation to m's source, or none of them, and returns the edited notation. Every refusal is an *Error naming its kind.