syntax

Documentation

Overview

Package syntax is the leaf lexer + recursive-descent parser for .gwdk source. It owns the shared tokenizer (ADR 0010) and the typed declaration parser that produces real gwdkast nodes, and it imports neither internal/lang (the tooling layer) nor internal/parser (the compiler parser). That one-directional dependency — tooling and the compiler parser both sit above syntax — lets internal/parser consume the shared tokenizer without an import cycle.

Index

• Variables
• func IsMetadataKeyword(value string) bool
• func Lex(source string) ([]Token, []LexError)
• func LineExtent(tokens []Token, from int) (int, bool)
• func MatchBrace(tokens []Token, from int) int
• func SpanOf(first, last Token) source.SourceSpan
• func Unquote(lexeme string) string
• type LexError
• type Position
• type Range
  • func SourceRange(start, end Position) *Range
• type Token
• type TokenKind
• type TopLevel
  • func ParseTopLevel(src string) TopLevel

Variables

var MetadataKeywords = []string{
	"page",
	"route",
	"title",
	"description",
	"canonical",
	"image",
	"layout",
	"cache",
	"revalidate",
	"error",
	"guard",
	"css",
	"component",
	"wasm",
	"asset",
}

MetadataKeywords is the canonical, ordered set of top-level metadata keywords the current parser recognizes. It is the single source of truth for metadata classification (the lexer and the formatter both consume it) and is cross-checked against the published stability table in docs/language/stability.md by TestStabilityTableCoversConstructs.

Functions

func IsMetadataKeyword

func IsMetadataKeyword(value string) bool

IsMetadataKeyword reports whether value is a top-level metadata keyword.

func Lex

func Lex(source string) ([]Token, []LexError)

Lex tokenizes .gwdk source for the parser, editor, and CLI tooling.

func LineExtent

func LineExtent(tokens []Token, from int) (int, bool)

LineExtent returns the index that ends the logical line starting at from (the next newline or EOF) and whether the line contains a block-opening brace.

func MatchBrace

func MatchBrace(tokens []Token, from int) int

MatchBrace returns the index of the close brace that balances the first open brace at or after from. An unbalanced block recovers to the last token before EOF so the scan still terminates.

func SpanOf

func SpanOf(first, last Token) source.SourceSpan

SpanOf builds the source span covering first through last, inclusive.

func Unquote

func Unquote(lexeme string) string

Unquote trims surrounding double quotes from a string-literal lexeme.

Types

type LexError

type LexError struct {
	Pos     Position
	Range   *Range
	Code    string
	Message string
}

LexError is a lexer-level finding (currently only unterminated string literals). It carries the position substrate the tooling layer needs; the richer Diagnostic type — severity, fixes, redaction, JSON — lives in internal/lang, which maps each LexError into a lang.Diagnostic in its Lex wrapper. Keeping the lexer free of that machinery is what keeps this package a leaf.

type Position

type Position struct {
	Line   int `json:"line"`
	Column int `json:"column"`
}

Position is a 1-based source location. The tooling layer (internal/lang) re-exports it as lang.Position so editor diagnostics and the lexer share one position type.

type Range

type Range struct {
	Start Position `json:"start"`
	End   Position `json:"end"`
}

Range is a 1-based source range. End is exclusive.

func SourceRange

func SourceRange(start, end Position) *Range

SourceRange builds a 1-based, end-exclusive Range from start to end, clamping a degenerate or empty range to a single column so diagnostics always cover at least one character. It returns nil for an unpositioned start.

type Token

type Token struct {
	Kind   TokenKind
	Lexeme string
	Pos    Position
	Offset int
}

Token is a lexical token with source location. Offset is the 0-based byte offset of the token start in the source, the exact substrate the recursive-descent parser (ADR 0010) uses to build spans without re-deriving positions from line/column.

type TokenKind

type TokenKind string

TokenKind identifies one lexical token.

const (
	TokenIllegal    TokenKind = "illegal"
	TokenEOF        TokenKind = "eof"
	TokenNewline    TokenKind = "newline"
	TokenMetadata   TokenKind = "metadata"
	TokenIdentifier TokenKind = "identifier"
	TokenString     TokenKind = "string"
	TokenLBrace     TokenKind = "lbrace"
	TokenRBrace     TokenKind = "rbrace"
	TokenComma      TokenKind = "comma"
	TokenColon      TokenKind = "colon"
	TokenAssign     TokenKind = "assign"
	TokenQuestion   TokenKind = "question"
	TokenArrow      TokenKind = "arrow"
	TokenText       TokenKind = "text"
)

type TopLevel

type TopLevel struct {
	Package   *gwdkast.Package
	Imports   []gwdkast.Import
	Uses      []gwdkast.Use
	Metadata  []gwdkast.MetadataDecl
	Page      *gwdkast.PageDecl
	Component *gwdkast.ComponentDecl
	Cache     *gwdkast.CacheDecl
	Stores    []gwdkast.Store
	PropsType *gwdkast.GoTypeRef
	State     *gwdkast.StateContract
	WASM      *gwdkast.WASMContract
	Actions   []gwdkast.Endpoint
	APIs      []gwdkast.Endpoint
}

TopLevel holds the top-level declaration nodes a recursive-descent parse recovers from .gwdk source. It is the ADR 0010 declaration parser producing real gwdkast nodes (rather than the tooling outline), built behind an equivalence test against internal/parser.ParseSyntax. It currently recovers:

• the package declaration, Go imports, and GOWDK uses;
• the top-level metadata declarations, both as the raw list (Metadata, mirroring SyntaxFile.Metadata) and routed into validation-free typed fields (Page, Component, Cache, WASM);
• the Go-typed contracts (Stores, PropsType, State), whose pkg.Type and pkg.NewFn() references are parsed by go/parser per ADR 0010's split — custom grammar for .gwdk, the real Go parser for embedded Go — then constrained to the shapes the compiler parser accepts;
• the exact act/api endpoint declarations (Actions, APIs), with the compiler parser's post-match validation (exported handler name, allowed method, resolvable error page).

Metadata that needs validation to reach a typed field (route, revalidate, error, layout, guard, css, asset), block bodies, view markup, and the block-bodied fragment endpoint are recovered by internal/parser.ParseSyntax.

func ParseTopLevel

func ParseTopLevel(src string) TopLevel

ParseTopLevel parses the package, import, and use declarations of .gwdk source with a recursive-descent pass over the shared tokenizer. It accepts only the exact shapes ParseSyntax accepts (so an equivalence-anchored cutover never turns malformed source into valid nodes) and recovers from any other line by skipping to the next line, skipping block bodies by brace matching, so one bad declaration never hides the rest.