parse

Documentation

Overview

Package parse turns positioned tokens into a widget document's block structure, and reports every structural finding of the catalogue's W0 group.

It is deliberately shallow: it knows the fourteen blocks, their canonical order and which declaration keyword opens a nested block inside each, and it knows nothing about clauses, enumerations or references. That split is what keeps a malformed document producing structural findings rather than a cascade of semantic ones — and it is what lets the validator resolve against a shape that is always well-formed, whatever the source did.

Recovery is explicit rather than accidental. A block name met inside an open block means the open block was never closed, so the parser closes it, reports W008 at its opening line, and re-dispatches at document scope. An unclosed group therefore never swallows the rest of the document.

Index

• Variables
• func BlockNames() []string
• func DroppedMermaidKeyword(keyword string) (string, bool)
• func IsStatementKeyword(keyword string) bool
• type Block
  • func (block Block) Span() diag.SourceSpan
• type BlockSpec
  • func BlockSpecs() []BlockSpec
  • func LookupBlock(name string) (BlockSpec, bool)
• type Declaration
  • func (declaration Declaration) Span() diag.SourceSpan
• type Document
  • func Parse(file string, source []byte) (Document, []diag.Finding)
  • func (document Document) FirstStatement() (Statement, bool)
  • func (document Document) LastPreamblePosition() diag.SourcePosition
• type Statement
  • func (statement Statement) At() diag.SourcePosition
  • func (statement Statement) Span() diag.SourceSpan

Variables

var PreambleKeywords = []string{"widget", "dialect", "region", "palette"}

PreambleKeywords are the four document-scope directives, in their required order.

Functions

func BlockNames

func BlockNames() []string

BlockNames returns the fourteen block names in canonical order, for a message that has to enumerate them.

func DroppedMermaidKeyword

func DroppedMermaidKeyword(keyword string) (string, bool)

DroppedMermaidKeyword reports whether a keyword is one of the mermaid keywords the dialect dropped, and names the construct that replaced it.

func IsStatementKeyword

func IsStatementKeyword(keyword string) bool

IsStatementKeyword reports whether a keyword begins a statement inside some block of the dialect.

Types

type Block

type Block struct {
	Spec         BlockSpec
	Header       Statement
	Statements   []Statement
	Declarations []Declaration
	EndAt        diag.SourcePosition
}

Block is one of the fourteen blocks, with its member lines and its nested declarations each in declaration order.

func (Block) Span

func (block Block) Span() diag.SourceSpan

Span covers the block from its header to its `end`.

type BlockSpec

type BlockSpec struct {
	// Name is the block keyword.
	Name string
	// Ordinal is the block's position in the canonical order, from 1.
	Ordinal int
	// Required is true for the six blocks every document declares.
	Required bool
	// Named is true for the one block whose header carries an identifier.
	Named bool
	// Openers are the declaration keywords that open a nested block here.
	Openers []string
}

BlockSpec describes one of the fourteen blocks.

func BlockSpecs

func BlockSpecs() []BlockSpec

BlockSpecs returns the fourteen blocks in canonical order.

func LookupBlock

func LookupBlock(name string) (BlockSpec, bool)

LookupBlock returns the spec for a block name.

type Declaration

type Declaration struct {
	Header     Statement
	Statements []Statement
	// EndAt anchors the `end` that closed the declaration, or the header when
	// the declaration was never closed.
	EndAt diag.SourcePosition
}

Declaration is a named block nested inside one of the fourteen blocks: a role, a node, an event and their nine siblings.

func (Declaration) Span

func (declaration Declaration) Span() diag.SourceSpan

Span covers the declaration from its header to its `end`.

type Document

type Document struct {
	File     string
	Preamble []Statement
	Blocks   []Block
}

Document is a parsed widget document: the preamble directives in source order, and the blocks in source order — which is not necessarily the canonical order, because reporting an out-of-order block is the validator's job rather than a reason to rearrange what the author wrote.

func Parse

func Parse(file string, source []byte) (Document, []diag.Finding)

Parse scans and structures a document, reporting every lexical and structural finding. The returned document is always usable: recovery is total.

func (Document) FirstStatement

func (document Document) FirstStatement() (Statement, bool)

FirstStatement is the document's first significant line, which is where W001 anchors.

func (Document) LastPreamblePosition

func (document Document) LastPreamblePosition() diag.SourcePosition

LastPreamblePosition anchors the findings that are about the preamble as a whole: a required block that is absent, or a directive that is missing.

type Statement

type Statement struct {
	Keyword   lex.Token
	Arguments []lex.Token
}

Statement is one significant line: its first token and the rest.

func (Statement) At

func (statement Statement) At() diag.SourcePosition

At is the statement's anchor, at its first token (A1).

func (Statement) Span

func (statement Statement) Span() diag.SourceSpan

Span covers the whole statement.