Frontend API Reference

Generated from the /// XML doc comments in src/Ashes.Frontend/. See the Compilation Pipeline for how this project fits into the compiler. This page is regenerated by tools/docs-api-gen on every docs build — edit the doc comments in the source, not this file.

Types

Type	Kind	Summary	Source
AstSpans	class	A side table mapping AST nodes to their originating source spans.	source
CallArgumentListLayout	enum	Preserved source layout for one parenthesized function-argument group.	source
CapabilityDecl	record	A capability declaration: capability Clock = | now : Unit -> Int.	source
CapabilityOperation	record	One operation of a capability declaration: | now : Unit -> Int or a bare | log.	source
CapabilityRefSyntax	record	A single capability reference inside a needs row: Clock or State(Int).	source
CompileDiagnosticException	class	Thrown to abort compilation when one or more diagnostics have been collected.	source
CompilePhaseTiming	class	Reports how long each compile phase takes, on stderr, when the ASHES_TIMING environment variable is set.	source
DiagnosticCodes	class	The stable ASHnnn string codes attached to compiler diagnostics, used for cross-referencing with the diagnostics reference and for machine-readable filtering.	source
DiagnosticEntry	record	A single compiler diagnostic: a source Span, a human-readable Message, and an optional Code from DiagnosticCodes.	source
DiagnosticSerialization	class	Serializes a program parse's public diagnostic corpus into the versioned, implementation-neutral parity format used by bootstrap tests.	source
DiagnosticTextRenderer	class	Renders structured compiler diagnostics into human-readable, rustc-style text with a path:line:column header and, when the source is available, a caret-underlined snippet of the offending line.	source
Diagnostics	class	A collecting sink for compiler diagnostics.	source
ExportConstructors	record	Constructor visibility for an exported type.	source
ExportConstructors.All	record	Every constructor declared by the type is exported.	source
ExportConstructors.Hidden	record	The type is abstract and none of its constructors are exported.	source
ExportConstructors.Selected	record	Only the named constructors are exported.	source
ExportDecl	record	A module's explicit public interface.	source
ExportItem	record	One entry in an explicit module export interface.	source
ExportItem.Module	record	Exports one direct nested module.	source
ExportItem.Type	record	Exports a type with the requested constructor visibility.	source
ExportItem.Value	record	Exports one top-level value binding.	source
Expr	record	Base of the expression AST.	source
Expr.Add	record	Integer/float addition, Left + Right.	source
Expr.Await	record	An await expression that suspends until a task completes.	source
Expr.BigIntLit	record	An arbitrary-precision integer literal (an N-suffixed number).	source
Expr.BitwiseAnd	record	Bitwise and, Left & Right.	source
Expr.BitwiseNot	record	Bitwise complement, ~Operand.	source
Expr.BitwiseOr	record	Bitwise or, Left | Right.	source
Expr.BitwiseXor	record	Bitwise xor, Left ^ Right.	source
Expr.BoolLit	record	A boolean literal.	source
Expr.Call	record	Function application, f(x) or f x.	source
Expr.Cons	record	A cons cell, Head :: Tail, prepending an element onto a list.	source
Expr.Divide	record	Division, Left / Right.	source
Expr.Equal	record	Equality comparison, Left == Right.	source
Expr.FloatLit	record	A floating-point literal, carrying both its numeric value and the source text so the formatter can round-trip the exact written form.	source
Expr.GreaterOrEqual	record	Greater-or-equal comparison, Left >= Right.	source
Expr.GreaterThan	record	Greater-than comparison, Left > Right.	source
Expr.Handle	record	Handler installation: handle body with | Capability.op(args) -> arm | return(r) -> arm.	source
Expr.If	record	A conditional, if Cond then Then else Else.	source
Expr.IntLit	record	A signed integer literal.	source
Expr.Lambda	record	A single-parameter lambda, given (x) -> expr.	source
Expr.LessOrEqual	record	Less-or-equal comparison, Left <= Right.	source
Expr.LessThan	record	Less-than comparison, Left < Right.	source
Expr.Let	record	A non-recursive binding, let Name = Value in Body.	source
Expr.LetRecursive	record	A self-recursive binding, let recursive Name = Value in Body, where Name is in scope within its own Value.	source
Expr.LetResult	record	A result-unwrapping binding, let? Name = Value in Body: binds the ok value of Value, short-circuiting the whole expression on error.	source
Expr.ListLit	record	A list literal, [a, b, ...].	source
Expr.LogicalAnd	record	Short-circuit logical and, Left && Right: Right is evaluated only when Left is true.	source
Expr.LogicalNot	record	Boolean logical negation, !Operand.	source
Expr.LogicalOr	record	Short-circuit logical or, Left || Right: Right is evaluated only when Left is false.	source
Expr.Match	record	A pattern match, `match Value with | ...	source
Expr.Modulo	record	Modulo, Left % Right.	source
Expr.Multiply	record	Multiplication, Left * Right.	source
Expr.NotEqual	record	Inequality comparison, Left != Right.	source
Expr.Perform	record	Explicit capability-operation marker: perform Clock.now(x).	source
Expr.QualifiedVar	record	A module-qualified name reference, Module.Name.	source
Expr.RecordLit	record	Record construction: TypeName(field1 = e1, field2 = e2).	source
Expr.RecordUpdate	record	Record update: { expr with field1 = e1, field2 = e2 }.	source
Expr.ResultMapErrorPipe	record	Result-map-error pipe, Left |!> Right: maps the error value of Left through Right, passing ok values through.	source
Expr.ResultPipe	record	Result-pipe, Left |?> Right: threads the ok value of Left into Right, short-circuiting on error.	source
Expr.RuneLit	record	A Unicode scalar literal.	source
Expr.ShiftLeft	record	Left shift, Left << Right.	source
Expr.ShiftRight	record	Right shift, Left >> Right.	source
Expr.StrLit	record	A string literal.	source
Expr.Subtract	record	Subtraction, Left - Right (also the desugared form of unary minus).	source
Expr.TupleLit	record	A tuple literal, (a, b, ...).	source
Expr.UIntLit	record	An unsigned fixed-width integer literal (e.g.	source
Expr.Var	record	A reference to an unqualified name.	source
ExternalDecl	record	An external declaration: a foreign function or opaque type imported from native code via the FFI surface.	source
ExternalDecl.Function	record	An external function binding, external name(params) -> ret [= "symbol"].	source
ExternalDecl.OpaqueType	record	An opaque external type whose representation is unknown to the compiler, external type Name.	source
ExternalParameterOwnership	enum	Ownership declared at an external FFI parameter boundary.	source
FfiStringOwnership	enum	Ownership contract for a native UTF-8 string pointer.	source
HandlerArm	record	One arm of a `handle ...	source
Lexer	class	Forward-only tokenizer that turns source text into a stream of Token values, one per Next call.	source
MatchCase	record struct	One arm of a Match: a pattern, its result expression, and an optional when guard.	source
NeedsRowSyntax	record	A written needs row: needs {A, B} (closed), needs {A, B | e} (open), or needs e (open, no required capabilities).	source
ParsedType	record	A type as written in an external FFI signature.	source
ParsedType.Buffer	record	A call-scoped contiguous input buffer, written FfiBuffer(T).	source
ParsedType.Named	record	A named FFI type, e.g.	source
ParsedType.NativeString	record	A borrowed or owned native UTF-8 string pointer copied at the call boundary.	source
ParsedType.Out	record	A compiler-owned nullable output slot, written out T.	source
ParsedType.Pointer	record	A pointer to another FFI type, written *T.	source
Parser	class	Recursive-descent parser that turns a source string into an AST.	source
Pattern	record	Base of the pattern AST used in match arms and irrefutable let bindings.	source
Pattern.As	record	An as-pattern, pattern as name, binding the complete matched value.	source
Pattern.BoolLit	record	A boolean-literal pattern.	source
Pattern.Cons	record	A cons pattern, Head :: Tail, matching a non-empty list.	source
Pattern.Constructor	record	A constructor pattern, Name(p1, ...), matching an ADT variant.	source
Pattern.EmptyList	record	The empty-list pattern, [].	source
Pattern.IntLit	record	An integer-literal pattern.	source
Pattern.Or	record	An or-pattern, left | right, sharing one arm body and guard.	source
Pattern.Record	record	A named record pattern, `Type { field = pattern, ...	source
Pattern.RuneLit	record	A Unicode scalar literal pattern.	source
Pattern.StrLit	record	A string-literal pattern.	source
Pattern.Tuple	record	A tuple pattern, (p1, p2, ...).	source
Pattern.Var	record	A variable pattern that always matches and binds the value to a name.	source
Pattern.Wildcard	record	The wildcard pattern, _, that matches anything without binding.	source
Program	record	A whole compilation unit: an ordered sequence of top-level items followed by an optional trailing expression.	source
ProvideBinding	record	One operation implementation in a provide: | compare = Ashes.Text.compare.	source
ProvideDecl	record	A static provider: provide Ord(Str) = | compare = ....	source
SourcePositionEncoding	enum	The coordinate encoding used for a line-relative character value.	source
SourceTextIndex	class	Immutable index over valid Unicode source text.	source
TextSpan	record struct	A half-open range of UTF-8 byte offsets into source text, used to locate diagnostics and AST nodes.	source
Token	record struct	A single lexical token: its Kind, the exact source Text it spanned, decoded numeric payloads, and the source position it occupied.	source
TokenKind	enum	The lexical category of a Token: keywords, operators, punctuation, literal kinds, and the end-of-input and error sentinels.	source
TokenSerialization	class	Serializes the public token stream into the versioned, implementation-neutral parity format used by bootstrap tests.	source
TopLevelItem	record	A single top-level item, kept in source order.	source
TopLevelItem.Capability	record	A top-level capability declaration.	source
TopLevelItem.Export	record	A leading module export interface.	source
TopLevelItem.External	record	A top-level external declaration.	source
TopLevelItem.Implementation	record	A top-level coherent trait implementation declaration.	source
TopLevelItem.LetDecl	record	A top-level value binding: let Name = Value, or let recursive when IsRecursive.	source
TopLevelItem.Provide	record	A top-level provide declaration (static capability satisfaction).	source
TopLevelItem.RecursiveGroup	record	A mutual-recursion group: `let recursive A = ...	source
TopLevelItem.Trait	record	A top-level static trait declaration.	source
TopLevelItem.Type	record	A top-level type declaration.	source
TopLevelItem.TypeAlias	record	A transparent type-alias declaration.	source
TopLevelItem.ZeroCostType	record	A zero-cost nominal type declaration.	source
TraitConstraintSyntax	record	A written static trait requirement such as Eq(a).	source
TraitDecl	record	A top-level trait declaration.	source
TraitImplementationDecl	record	A top-level coherent trait implementation declaration.	source
TraitImplementationMethodBinding	record	One method implementation or default override in a trait implementation declaration.	source
TraitMethodDecl	record	One method declared by a trait, with an optional ordinary-expression default.	source
TypeAliasDecl	record	A transparent type alias declaration.	source
TypeConstructor	record	One constructor of a type declaration (also the single synthetic constructor of a record type).	source
TypeDecl	record	A type declaration: an algebraic data type or (when IsRecord) a record type.	source
TypeExpr	record	A type expression written by the user in an annotation, e.g.	source
TypeExpr.Applied	record	A parameterised type application: List(Int), Result(Str, Int).	source
TypeExpr.Arrow	record	A function type: Int -> Str, optionally carrying a capability row: Str -> Int uses {Prices}.	source
TypeExpr.Named	record	A simple named type or type parameter: Int, Str, T.	source
TypeExpr.TupleType	record	A tuple type: (Int, Str).	source
TypeExpr.UnitType	record	Unit written as an empty tuple: ().	source
TypeExprExtensions	class	Helpers over TypeExpr trees.	source
TypeParameter	record	A declared type parameter, e.g.	source
ZeroCostTypeDecl	record	A zero-cost nominal type declaration.	source

Parser

Recursive-descent parser that turns a source string into an AST. It drives a forward-only Lexer, reports recoverable errors into a Diagnostics sink rather than throwing, and produces either a full Program (ParseProgram) or a single Expr (ParseExpression).

Member	Signature	Summary
ParseExpression	Expr ParseExpression()	Parses the input as a single expression and verifies that no tokens remain afterward. Used for contexts that expect one expression rather than a whole compilation unit (e.g. the REPL).
ParseProgram	Program ParseProgram()	Parses a whole compilation unit — an ordered sequence of top-level declarations followed by an optional trailing expression (declaration* expr?) — into a Program. Imports are assumed stripped upstream. A file with no declarations must be a single expression.

Lexer

Forward-only tokenizer that turns source text into a stream of Token values, one per Next call. It skips whitespace and // line comments, recognizes keywords, operators, and literals (integer, unsigned-suffixed, float, big-int, string), and reports lexical errors into a Diagnostics sink. SavePosition / RestorePosition give the parser bounded backtracking.

Member	Signature	Summary
Next	Token Next()	Scans and returns the next token, advancing past it. Whitespace and // line comments are skipped first; at end of input a EOF token is returned.
RestorePosition	void RestorePosition(int pos)	Rewinds the lexer to a position previously returned by SavePosition.
SavePosition	int SavePosition()	Captures the current byte offset so it can later be handed back to RestorePosition for bounded lookahead/backtracking.