source

Documentation

Overview

Package source holds the neutral leaf value types shared across the GOWDK compiler packages: source spans, route params, inline scripts, and backend binding metadata. These types carry no behavior and depend on nothing else in the module, so every layer (parser, AST, IR, manifest, generated output) can reference them without creating import cycles or coupling to the manifest page/component model.

Historically these lived in internal/manifest, which forced packages that only needed a SourceSpan to depend on the whole manifest model (and made internal/gwdkir depend on manifest). They were extracted here so the manifest model and the IR can both reference shared leaf types from a neutral home. manifest re-exports them as aliases for backward compatibility.

Index

• func BackendRouteMethod(value string) string
• func BackendRoutePath(value string) string
• func ErrorPagePath(value string) (string, error)
• func ExportedIdentifier(value string, fallback string) string
• func InlineScriptName(index int) string
• func OffsetOf(src []byte, pos SourcePosition) int
• func ValidateBackendRoutePath(value string) error
• type BackendBinding
• type BackendBindingStatus
• type BackendInputField
• type BackendSignatureKind
• type InlineScript
• type NamedSpan
• type RelatedSpan
• type RouteParam
• type SourcePosition
  • func PositionAt(src []byte, offset int) SourcePosition
• type SourceSpan

Functions

func BackendRouteMethod

func BackendRouteMethod(value string) string

BackendRouteMethod returns the normalized HTTP method spelling used by generated backend route metadata.

func BackendRoutePath

func BackendRoutePath(value string) string

BackendRoutePath returns the normalized path key used by generated backend routers after ValidateBackendRoutePath has accepted the source value.

func ErrorPagePath

func ErrorPagePath(value string) (string, error)

ErrorPagePath returns a clean generated-output-relative error page path.

func ExportedIdentifier

func ExportedIdentifier(value string, fallback string) string

ExportedIdentifier returns a PascalCase Go identifier fragment derived from value. Underscores are preserved because they are valid Go identifier characters and can distinguish otherwise identical generated names. fallback is returned when value contains no identifier characters.

func InlineScriptName

func InlineScriptName(index int) string

InlineScriptName returns the deterministic generated filename for the zero-based inline browser script declaration index in one source owner.

func OffsetOf

func OffsetOf(src []byte, pos SourcePosition) int

OffsetOf returns the 0-based byte offset into src for a 1-based line/column position (column counted in runes). An unset position (non-positive line or column) maps to 0, and a position past the end of src is clamped to len(src). It is the inverse of PositionAt for in-bounds, rune-aligned positions.

func ValidateBackendRoutePath

func ValidateBackendRoutePath(value string) error

ValidateBackendRoutePath rejects paths that would be unsafe or ambiguous when registered as generated backend routes.

Types

type BackendBinding

type BackendBinding struct {
	Kind         string
	PageID       string
	Source       string
	BlockName    string
	Method       string
	Route        string
	ImportPath   string
	PackageName  string
	FunctionName string
	Signature    BackendSignatureKind
	InputType    string
	InputPointer bool
	InputFields  []BackendInputField
	Status       BackendBindingStatus
	Message      string
}

BackendBinding describes the Go handler selected for a backend block (a page load, act, api, or fragment block, or a standalone Go endpoint).

type BackendBindingStatus

type BackendBindingStatus string

BackendBindingStatus describes whether a .gwdk backend block has a matching same-package Go handler.

const (
	BackendBindingBound                BackendBindingStatus = "bound"
	BackendBindingMissing              BackendBindingStatus = "missing"
	BackendBindingUnsupportedSignature BackendBindingStatus = "unsupported_signature"
)

type BackendInputField

type BackendInputField struct {
	FieldName string
	FormName  string
	Type      string
}

BackendInputField describes one form field decoded into a Go action input struct from compile-time Go AST metadata.

type BackendSignatureKind

type BackendSignatureKind string

BackendSignatureKind describes the supported Go handler shape.

const (
	BackendSignatureAction0       BackendSignatureKind = "action0"
	BackendSignatureActionValues  BackendSignatureKind = "action_values"
	BackendSignatureActionForm    BackendSignatureKind = "action_form"
	BackendSignatureActionFormPtr BackendSignatureKind = "action_form_ptr"
	BackendSignatureAPI           BackendSignatureKind = "api"
	BackendSignatureFragment      BackendSignatureKind = "fragment"
	BackendSignatureLoad          BackendSignatureKind = "load"
	BackendSignatureLoadError     BackendSignatureKind = "load_error"
)

type InlineScript

type InlineScript struct {
	Name string
	Body string
	Span SourceSpan
}

InlineScript records browser module code declared directly inside a .gwdk source file. Path-based script declarations should remain preferred.

type NamedSpan

type NamedSpan struct {
	Name string
	Span SourceSpan
}

NamedSpan records the source range for a named declaration or reference.

type RelatedSpan

type RelatedSpan struct {
	Source  string
	Span    SourceSpan
	Message string
}

RelatedSpan is a secondary source location attached to a diagnostic, such as the first declaration that a conflict diagnostic also points at. Source is the owning file label (matching a diagnostic's primary Source) and may be empty for a same-file relation. Message is a short note shown alongside the location (for example "first declared here").

type RouteParam

type RouteParam struct {
	Name string
	Type string
	Span SourceSpan
}

RouteParam describes one dynamic route parameter and its declared scalar type. Empty Type means string for compatibility with legacy {name} syntax.

type SourcePosition

type SourcePosition struct {
	Line   int
	Column int
	Offset int
}

SourcePosition is a 1-based source location in a parsed .gwdk file.

Offset is the 0-based byte offset of the position into the source buffer. It is the exact substrate for AST-backed formatting, precise LSP edits, and exact diagnostic ranges, none of which should re-derive offsets from line/column. Offset is best-effort: some parser spans are still line-derived and leave Offset at its zero value while Line/Column are set. Use PositionAt/OffsetOf to convert against a source buffer when an exact offset is required. Set-ness of a position is determined by Line/Column being positive, not by Offset, because byte offset 0 is a valid first-byte position.

func PositionAt

func PositionAt(src []byte, offset int) SourcePosition

PositionAt returns the 1-based line/column (column counted in runes, matching the parser's rune-column spans) for a 0-based byte offset into src, with Offset set to that byte offset. The offset is clamped to the buffer bounds.

type SourceSpan

type SourceSpan struct {
	Start SourcePosition
	End   SourcePosition
}

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