Documentation
¶
Overview ¶
Package view renders a SysML view: it turns the elements a view exposes into a rendering artifact, in the form the view's `render` member states.
SysML v2 §10.2 states which rendering a view uses and leaves how a tool carries it out to the tool, so everything this package produces — the text form and the Mermaid form alike — is tool-defined output rather than a notation the specification defines. What is read from the model is not: the exposed set comes from semantics.Model.ExposedElements, connections from the model's own connector information, and states and actions from the lowered graphs in internal/core/lower, never from the source text of a declaration.
Index ¶
- Constants
- Variables
- type Data
- type Edge
- type EdgeData
- type EdgeKind
- type Form
- type Kind
- type Node
- type NodeData
- type Origin
- type Renderer
- type Rendering
- func (r *Rendering) Data() Data
- func (r *Rendering) Empty() bool
- func (r *Rendering) Markdown() string
- func (r *Rendering) Mermaid() string
- func (r *Rendering) Text() string
- func (r *Rendering) TextWidth(width int) string
- func (r *Rendering) Write(form Form) (string, error)
- func (r *Rendering) WriteWidth(form Form, width int) (string, error)
- type RowData
- type SourceText
- type UnsupportedKindError
- type WrongFormError
Constants ¶
const ( // WidthUnbounded writes every column as wide as its widest cell, which is // what a form written to a file or a pipe rather than a terminal is. WidthUnbounded = 0 )
The widths the text form is written to.
Variables ¶
var ErrUnsupportedKind = errors.New("unsupported rendering kind")
ErrUnsupportedKind is the rendering kind a view states that this package does not produce. UnsupportedKindError wraps it, so a caller can test for it without knowing which kind was asked for.
var ErrWrongForm = errors.New("rendering is not written in that form")
ErrWrongForm is a form asked for that renderings of the kind are not written in. WrongFormError wraps it.
Functions ¶
This section is empty.
Types ¶
type Data ¶ added in v0.1.2
type Data struct {
// View is the rendered view by qualified name, "" for a rendering of exposed
// elements alone (RenderExposed).
View string
// Kind is the rendering produced, and Stated how the kind was decided.
Kind Kind
Stated string
// Nodes are every node of the rendering, parents before children, each
// naming its parent.
Nodes []NodeData
// Edges join nodes by ID.
Edges []EdgeData
// Columns and Rows are the tabular rendering, empty for every other kind.
Columns []string
Rows []RowData
// Notices are what the rendering could not represent.
Notices []string
}
Data is the machine-consumable shape of a Rendering: the nodes flattened out of the containment tree, the edges between them, the rows of a tabular rendering and what the rendering could not represent. It carries no protocol or wire concern — a caller speaking one converts it.
type Edge ¶
type Edge struct {
// From and To are node IDs.
From string
To string
// Label is what the edge carries: a connector's name, a transition's
// trigger, guard and effect, a succession's guard. It may be empty.
Label string
Kind EdgeKind
// Origin is where the connection, transition, succession or flow was
// declared, the zero Origin for one with no locatable declaration.
Origin Origin
}
Edge joins two nodes of a rendering.
type Form ¶
type Form string
Form is a written form of a rendering: the human-readable text every kind has, and the machine-readable form of the kind — a Mermaid diagram for the graph-shaped kinds, a Markdown table for the tabular one.
type Kind ¶
type Kind string
Kind is a rendering a view can state. The kinds this package produces are tree, interconnection, state, action and table; the rest are recognized so that a view stating one is told it is unsupported rather than rendered as something else. A rendering the standard library does not declare is carried as the name the model gives it, so an error about it names what the view asked for.
const ( // KindTree renders the exposed elements as a containment tree. KindTree Kind = "tree" // KindInterconnection renders exposed features as nodes and the connections // between them as edges. KindInterconnection Kind = "interconnection" // KindState renders the states and transitions of exposed behaviors. KindState Kind = "state" // KindAction renders the nodes and successions of exposed behaviors. KindAction Kind = "action" // KindTextual is Views::asTextualNotation, which writes the model back as // notation: `sysml -convert sysml` does that, so no rendering is produced. KindTextual Kind = "textual" // KindTable renders the exposed elements as rows of a table, which is // Views::asElementTable and StandardViewDefinitions::GridView. KindTable Kind = "table" // KindSequence is StandardViewDefinitions::SequenceView. KindSequence Kind = "sequence" // KindGeometry is StandardViewDefinitions::GeometryView. KindGeometry Kind = "geometry" )
func (Kind) MachineForm ¶
MachineForm is the machine-readable form of renderings of this kind.
type Node ¶
type Node struct {
// ID identifies the node within its rendering, and is what an edge names.
ID string
// Kind is what the notation calls the element — "part def", "state",
// "fork" — never a Go type name.
Kind string
// Name is the element's name: qualified for a node the view exposes, simple
// for one nested in it. It is empty for an anonymous element.
Name string
// Detail is what else the kind carries, such as a state's "initial" or the
// type of a usage. It is empty when there is nothing to add.
Detail string
// Children are the nodes nested in this one.
Children []*Node
// Origin is where the element was declared, the zero Origin for one with no
// locatable declaration.
Origin Origin
}
Node is one element of a rendering: an exposed element, a feature nested in one, a state or an action node. Children are the nodes nested in it, which is how a rendering carries containment.
type NodeData ¶ added in v0.1.2
type NodeData struct {
ID string
Kind string
Name string
Detail string
// Parent is the ID of the node this one is nested in, "" for a root.
Parent string
Origin Origin
}
NodeData is one node of a rendering, with the node it is nested in.
type Origin ¶ added in v0.1.2
type Origin struct {
// Doc is the name of the document the declaration is in, "" when unknown.
Doc string
// Span is the span of the declaration within that document.
Span source.Span
// Name is the span of the declared identifier alone, which is where a reader
// is taken to. It is the zero span for a declaration with no identifier.
Name source.Span
}
Origin is where a node or an edge was declared: the document it was declared in and the span of the declaration. It is a core location, not a protocol one: a caller speaking a protocol converts it.
An element with no locatable declaration — a cached standard-library symbol, a step a lowering sequenced without a declaration of its own — carries the zero Origin rather than a fabricated one.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer renders views over one semantic model.
func NewRenderer ¶
NewRenderer returns a renderer over the model and resolver of a loaded document. text may be nil.
func (*Renderer) KindOf ¶
KindOf reports the rendering kind a view states and how it states it: the rendering its body names, else the standard view definition it specializes, else the tree every view defaults to. A recognized kind this package does not produce is an *UnsupportedKindError.
func (*Renderer) Render ¶
Render renders view in the kind it states, defaulting to a tree when it states none. A view that is no view is semantics.ErrNotAView, and a recognized kind this package does not produce is an *UnsupportedKindError — never another kind's rendering.
func (*Renderer) RenderExposed ¶ added in v0.1.2
func (r *Renderer) RenderExposed(exposed []*symbols.Symbol, kind Kind, stated string) (*Rendering, error)
RenderExposed renders elements in the kind asked for, as a view exposing just them would: a document with no view declared is rendered this way. Nothing is added to the model or to the symbol index, so the rendering carries no view name; stated says how the kind was decided. An unsupported kind is an *UnsupportedKindError.
type Rendering ¶
type Rendering struct {
// View is the rendered view, by qualified name as the notation writes it.
View string
// Kind is the rendering produced.
Kind Kind
// Stated is how the kind was decided: the rendering member the view states,
// the standard view definition it specializes, or "" when the view states
// nothing and the default was used.
Stated string
// Roots are the top-level nodes, in the order the view exposes them.
Roots []*Node
// Edges join nodes, in the order the model and the lowered graphs give them.
Edges []Edge
// Columns are the headings of a tabular rendering, empty for every other
// kind.
Columns []string
// Rows are the rows of a tabular rendering, each holding one cell per
// column, in the order the view exposes the elements.
Rows [][]string
// RowOrigins is where each row's element was declared, one entry per row.
RowOrigins []Origin
// Notices are what the rendering could not represent, reported rather than
// dropped: an exposed element with no place in this kind of rendering, a
// connection to something the view does not expose, a behavior that does not
// lower.
Notices []string
}
Rendering is what a view renders to: the nodes and edges of one artifact, which Text and Mermaid write out. It is a value, not a live view of the model: nothing in it points back into the AST.
func (*Rendering) Markdown ¶
Markdown is the machine-readable form of a tabular rendering: a GitHub-flavored Markdown table, which is what a table is read as where the models are — in documentation and in an editor — since Mermaid has no table grammar. What the rendering could not represent is written as Markdown comments, so no notice is lost.
func (*Rendering) Mermaid ¶
Mermaid is the machine-readable form of a rendering. Mermaid was chosen over DOT because a Mermaid diagram renders where the models are read — in Markdown documentation, in the repository's own docs, and in the editors that host the language server — without a Graphviz installation, and because it has a state-diagram grammar the state rendering maps onto directly.
A graph-shaped rendering is a `flowchart`; a state rendering is a `stateDiagram-v2`. What the rendering could not represent is written as comments, so no notice is lost in the machine-readable form either.
func (*Rendering) Text ¶
Text is the human-readable form of a rendering, written to no particular width. It is ASCII throughout, so it reads the same on any terminal.
func (*Rendering) TextWidth ¶ added in v0.1.1
TextWidth is the human-readable form of a rendering: a header saying what was rendered and how, the nodes as an indented tree, the edges beneath it, and what the rendering could not represent. It is what the REPL prints. A table's columns are written to fit width, wrapping their cells; WidthUnbounded writes each column as wide as its widest cell.
type RowData ¶ added in v0.1.2
RowData is one row of a tabular rendering: its cells, one per column, and where the element it reports was declared.
type SourceText ¶
SourceText answers the notation a span of a document was written in, so that a label a rendering takes verbatim — a transition guard, a trigger expression — reads as it was written. It may be nil, and returns "" for a document it does not hold, in which case such a label is described structurally instead.
type UnsupportedKindError ¶
type UnsupportedKindError struct {
// Kind is the rendering kind asked for.
Kind Kind
// View is the view stating it, by qualified name.
View string
// Stated is what the model says the kind through — a rendering member, or
// the standard view definition the view specializes.
Stated string
// Remedy is what to do instead, empty when there is nothing to suggest.
Remedy string
}
UnsupportedKindError is a view stating a rendering kind that is recognized but not produced. It names both the kind and the view, and never falls back to another kind.
func (*UnsupportedKindError) Error ¶
func (e *UnsupportedKindError) Error() string
func (*UnsupportedKindError) Unwrap ¶
func (e *UnsupportedKindError) Unwrap() error
type WrongFormError ¶
type WrongFormError struct {
// Form is the form asked for, Kind the rendering's kind, and View the view
// rendered, by qualified name.
Form Form
Kind Kind
View string
}
WrongFormError is a form asked for that does not fit the rendering's kind: a Mermaid diagram of a table, or a Markdown table of a diagram. It names the form the kind is written in instead, and never writes another form silently.
func (*WrongFormError) Error ¶
func (e *WrongFormError) Error() string
func (*WrongFormError) Unwrap ¶
func (e *WrongFormError) Unwrap() error
Source Files