Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.
src/parse/parse.x
X2c declarations, parsed from source or constructed.
Functions
| Function | Summary |
|---|---|
Ast.declared_return | The declared result type of the function declaration, which its return statements convert to, or NULL. |
Compiler.bind_callable_body | Binds a callable’s outer block in its active parameter scope. |
Compiler.bind_catch_arm | Binds one catch arm’s body in a scope of its own, with declarations of the definite binders of pattern, read through handle, before it. |
Compiler.bind_match_arm | Binds one match arm’s body in a scope of its own, which defines the definite binders of pattern when the arm binds. |
Compiler.bind_parameter | Binds one constructed parameter in the current scope, including nested function modifiers and reference parameter facts. |
Compiler.bind_source_statement | Binds the source if, while, do, for, match, or try at the cursor through the same binders as constructed syntax. |
Compiler.bind_syntax | Binds parser-shaped syntax at context into current compiler state. |
Compiler.bind_template_local | Installs a definition-local template binding or typedef provisionally. |
Compiler.check_reference_placement | Rejects transparent references in object and function-result types. |
Compiler.close_placements | Gives the placements made since first the result of the expansion that made them. |
Compiler.defines_main | Reports whether the unit’s tokens define a function named main at file scope. |
Compiler.definition_doc | Returns the body of the doc comment that documents the definition starting at start, or NULL. |
Compiler.enclosing | Returns the innermost what around the parser, or around the function body the transform lowers, as captured code, or NULL when there is none: the declarator whose initializer is being parsed directly in the current block item, as its one-declarator declaration; the block item, or the one the transform lowers, as its origin anchor; the function, as a definition whose body is still the empty (seq); or the unit, as a String expression of its path. |
Compiler.enter | Enters row as the innermost syntax Compiler.enclosing answers. |
Compiler.enter_function | Enters the function definition declaration, whose body the transform lowers next, so a rule lowering that body places code at its entry. |
Compiler.exit_function | Leaves the function row at depth that Compiler.enter_function began. |
Compiler.finish_foreign_alias | Constructs a foreign alias from one direct function declaration and target. |
Compiler.finish_initializers | Lowers block declarations whose declarators placed code after themselves, or that an after-initialization rewrite follows, to declarations followed by that code in source order, preserving their installed bindings and the enclosing lifetime. |
Compiler.function_entry | Returns the code placed at the entry of the function row at depth since it was entered or last asked, in placement order, or NULL. |
Compiler.leave_item | Leaves the block item enter began and returns the code placed after it, bound in its block, or NULL. |
Compiler.meta_form_is_declaration | Reports whether the cursor begins a contextual top-level meta declaration: a function or an initialized file-static value. |
Compiler.package_alias_spelling | Returns the folded package-member spelling at the current token, or NULL. |
Compiler.parse_basic_identifier | Consumes one ident token and returns its spelling as a one-item List. |
Compiler.parse_complex_identifier | Parses the current identifier or dotted owner/member as a one-item name. |
Compiler.parse_declaration_argument | Parses one non-function, non-typedef Decl macro argument. |
Compiler.parse_declaration_row | Parses one x2c declaration row and leaves its terminator current. |
Compiler.parse_declarator_argument | Parses one declarator row for a macro argument without installing it. |
Compiler.parse_enumerator | Parses one enumerator for enum type context and returns its AST. |
Compiler.parse_enumerators | Parses comma-separated enumerators up to the current closing brace. |
Compiler.parse_field | Parses one field for aggregate type context and returns its AST. |
Compiler.parse_fields | Parses aggregate fields in source order up to the current closing brace. |
Compiler.parse_function_definition | Parses one function declaration and its required compound body. |
Compiler.parse_function_target | Parses one function decorator target and returns its resulting AST. |
Compiler.parse_import_declaration | Parses and registers one import declaration, including its semicolon. |
Compiler.parse_named_type | Captures a name followed by an ordinary complete type and semicolon. |
Compiler.parse_optional_identifier | Consumes and returns the current identifier, or NULL without consuming. |
Compiler.parse_parameter | Parses one parameter and returns (param TYPE DECLARATOR) or (...). |
Compiler.parse_parameter_list | Parses a nonempty comma-separated parameter List in source order. |
Compiler.parse_simple_declaration | Parses one declaration group and leaves its terminating token current. |
Compiler.parse_static_assert | Parses a C assertion declaration; native C owns constant-expression checks. |
Compiler.parse_submission | Parses one submission from the current token stream. |
Compiler.parse_top_level | Parses one full top-level form through the shared classifier. |
Compiler.parse_top_level_mode | Parses one top-level form and applies its source-ordered compiler effects. |
Compiler.parse_type_name | Parses a type specifier with qualifiers and pointer/reference modifiers. |
Compiler.parse_type_operand | Parses a declaration that sits inside an expression or a for header, such as a cast’s type name, and returns it as one (decl ...) node. |
Compiler.place_after | Records code to follow the innermost block item, or the initialized declarator whose initializer is being parsed directly in it. |
Compiler.place_entry | Records code for the entry of the innermost function definition, after its parameters bind and before its first statement. |
Compiler.protocol_form_starts | Reports whether the cursor begins a protocol declaration or adoption, including its meta and static markers. |
Compiler.script_statement_executes | Reports whether the top-level item at the cursor is a script statement that runs, rather than a declaration: an expression, control flow, a with block, or a statement macro. |
Compiler.script_statement_starts | Reports whether the top-level item at the cursor is one of a script unit’s statements, which become main’s body. |
Compiler.skip_linkage_brace | Consumes one brace of a C linkage specification at file scope and reports whether it did. |
Compiler.source_clause | The source clause kind, which the binder parses when it reaches it. |
Compiler.take_meta_marker | Consumes the meta marker at the cursor and the contextual native marker that may follow it, and returns the meta token. |
Compiler.test_declaration | Tests whether the current token can begin a declaration without consuming. |
Compiler.test_static_assert | Reports whether the current identifier starts a C static assertion. |
Ast
Ast.declared_return
Type Ast.declared_return(List declaration)
The declared result type of the function declaration, which its
return statements convert to, or NULL.
Source: src/parse/functions.x:102
Compiler
Compiler.bind_callable_body
List Compiler.bind_callable_body(Compiler c, List syntax, Type return_type)
Binds a callable’s outer block in its active parameter scope. Ordinary constructed blocks open their own scope before using this operation.
Source: src/parse/binding.x:591
Compiler.bind_catch_arm
List Compiler.bind_catch_arm( Compiler c, List pattern, Var body, Token start, List handle)
Binds one catch arm’s body in a scope of its own, with declarations of
the definite binders of pattern, read through handle, before it.
Binder diagnostics use start. A source arm’s body parses here, and a
template’s declares its binders where its expansion binds it. A parsed
arm’s body already begins with them, so it binds unchanged.
Source: src/parse/binding.x:446
Compiler.bind_match_arm
List Compiler.bind_match_arm( Compiler c, List pattern, Var body, Token start, int binds, List types)
Binds one match arm’s body in a scope of its own, which defines the
definite binders of pattern when the arm binds. Binder diagnostics
use start. A source arm’s body parses here with the typed captures
types that its pattern recorded.
Source: src/parse/binding.x:547
Compiler.bind_parameter
List Compiler.bind_parameter(Compiler c, List base, List declarator)
Binds one constructed parameter in the current scope, including nested function modifiers and reference parameter facts.
Source: src/parse/declarators.x:505
Compiler.bind_source_statement
List Compiler.bind_source_statement(Compiler c)
Binds the source if, while, do, for, match, or try at the
cursor through the same binders as constructed syntax.
Source: src/parse/binding.x:325
Compiler.bind_syntax
List Compiler.bind_syntax( Compiler c, Var syntax, Symbol context, Type return_type)
Binds parser-shaped syntax at context into current compiler state.
context is <unit>, <block>, <field>, <enumerator>, <map-entry>,
<statement>, or <expression>.
The input must evaluate to a nonempty AST List valid for the requested
position. Bindings, types, scopes, and expressions are resolved in source
order; return_type applies only while descendants are bound. This method
mutates Sym and does not open a semantic transaction.
Source: src/parse/binding.x:23
Compiler.bind_template_local
void Compiler.bind_template_local( Compiler c, List key, List type, List context)
Installs a definition-local template binding or typedef provisionally. Later template types name a local typedef by its identity, so each expansion refers to that expansion’s private typedef.
Source: src/parse/declarators.x:292
Compiler.check_reference_placement
void Compiler.check_reference_placement(Compiler c, Type type)
Rejects transparent references in object and function-result types. References inside a function’s parameter list remain supported.
Source: src/parse/declarations.x:291
Compiler.close_placements
void Compiler.close_placements(Compiler c, int first, List result)
Gives the placements made since first the result of the expansion
that made them.
Source: src/parse/placement.x:121
Compiler.defines_main
int Compiler.defines_main(Compiler c)
Reports whether the unit’s tokens define a function named main at file
scope. A script unit that does is an ordinary program: its declarations
stay at file scope and it may not have top-level statements. Both parse
passes read the same tokens, so they agree before either parses.
Source: src/parse/units.x:233
Compiler.definition_doc
String Compiler.definition_doc(Compiler c, Token start)
Returns the body of the doc comment that documents the definition
starting at start, or NULL. A doc comment opens with two asterisks and
ends on the line before start or on its line. Macro templates carry the
text until their selected body binds at the invocation.
Source: src/parse/units.x:591
Compiler.enclosing
List Compiler.enclosing(Compiler c, Symbol what)
Returns the innermost what around the parser, or around the function
body the transform lowers, as captured code, or NULL when there is none:
the declarator whose initializer is being parsed directly in the current
block item, as its one-declarator declaration; the block item, or the
one the transform lowers, as its origin anchor; the function, as a
definition whose body is still the empty (seq); or the unit, as a
String expression of its path.
Source: src/parse/placement.x:31
Compiler.enter
void Compiler.enter(Compiler c, Ancestor row)
Enters row as the innermost syntax Compiler.enclosing answers. Its
owner leaves it with Block.pop, or with Compiler.leave_item for a
block item.
Source: src/parse/placement.x:20
Compiler.enter_function
int Compiler.enter_function(Compiler c, List declaration, int callback)
Enters the function definition declaration, whose body the
transform lowers next, so a rule lowering that body places code at its
entry. Returns the row’s depth for Compiler.leave_function.
Source: src/parse/placement.x:60
Compiler.exit_function
void Compiler.exit_function(Compiler c, int depth)
Leaves the function row at depth that Compiler.enter_function
began.
Source: src/parse/placement.x:87
Compiler.finish_foreign_alias
List Compiler.finish_foreign_alias( Compiler c, List declaration, List native_syntax)
Constructs a foreign alias from one direct function declaration and target.
native_syntax must resolve to a different direct identifier and, when
typed, a function. Storage is limited to static or inline, when
present, and variadic parameters are rejected.
Source: src/parse/units.x:762
Compiler.finish_initializers
List Compiler.finish_initializers( Compiler c, List declaration, Token origin)
Lowers block declarations whose declarators placed code after themselves, or that an after-initialization rewrite follows, to declarations followed by that code in source order, preserving their installed bindings and the enclosing lifetime.
Source: src/parse/placement.x:169
Compiler.function_entry
List Compiler.function_entry(Compiler c, int depth)
Returns the code placed at the entry of the function row at depth
since it was entered or last asked, in placement order, or NULL. The
code binds in a scope of its own with the function’s result type; its
caller lowers it while the row is still entered, so a placement that
lowering makes lands at the entry too.
Source: src/parse/placement.x:74
Compiler.leave_item
List Compiler.leave_item(Compiler c)
Leaves the block item enter began and returns the code placed after
it, bound in its block, or NULL. A declarator in the item that placed
code is incomplete unless its block declaration took that code.
Source: src/parse/placement.x:131
Compiler.meta_form_is_declaration
int Compiler.meta_form_is_declaration(Compiler c)
Reports whether the cursor begins a contextual top-level meta
declaration: a function or an initialized file-static value.
Source: src/parse/units.x:308
Compiler.package_alias_spelling
String Compiler.package_alias_spelling(Compiler c)
Returns the folded package-member spelling at the current token, or NULL.
The token must be an unshadowed imported alias followed by . and an
identifier. This lookahead does not consume tokens.
Source: src/parse/declarators.x:606
Compiler.parse_basic_identifier
List Compiler.parse_basic_identifier(Compiler c)
Consumes one ident token and returns its spelling as a one-item List.
Source: src/parse/declarators.x:619
Compiler.parse_complex_identifier
List Compiler.parse_complex_identifier(Compiler c)
Parses the current identifier or dotted owner/member as a one-item name.
Package aliases and imported method spellings are folded through the
current Sym, and all accepted tokens are consumed.
Source: src/parse/declarators.x:544
Compiler.parse_declaration_argument
List Compiler.parse_declaration_argument(Compiler c)
Parses one non-function, non-typedef Decl macro argument.
Returns a single declaration without consuming the invocation delimiter;
flat destructuring may omit an initializer in this position.
Source: src/parse/declarations.x:110
Compiler.parse_declaration_row
List Compiler.parse_declaration_row(Compiler c)
Parses one x2c declaration row and leaves its terminator current.
A mixed-type comma row returns a seq of declarations in source order;
a single declaration returns directly.
Source: src/parse/declarations.x:15
Compiler.parse_declarator_argument
List Compiler.parse_declarator_argument(Compiler c)
Parses one declarator row for a macro argument without installing it. Its enclosing declaration supplies the base type when expanded.
Source: src/parse/declarators.x:210
Compiler.parse_enumerator
List Compiler.parse_enumerator(Compiler c, Type context)
Parses one enumerator for enum type context and returns its AST.
Outside macro-template parsing, its binding is published immediately so
later initializers and enumerators can resolve it.
Source: src/parse/types.x:489
Compiler.parse_enumerators
List Compiler.parse_enumerators(Compiler c, List context)
Parses comma-separated enumerators up to the current closing brace.
Returns their flat source-order List and leaves the brace unconsumed.
Source: src/parse/types.x:473
Compiler.parse_field
List Compiler.parse_field(Compiler c, List context)
Parses one field for aggregate type context and returns its AST.
Ordinary fields publish their binding in the aggregate’s field scope and
consume their terminating semicolon; macro forms follow their own syntax.
Source: src/parse/types.x:344
Compiler.parse_fields
List Compiler.parse_fields(Compiler c, List context)
Parses aggregate fields in source order up to the current closing brace.
Returns a flat field List, publishes delegate-field metadata, and leaves
the closing brace unconsumed.
Source: src/parse/types.x:329
Compiler.parse_function_definition
List Compiler.parse_function_definition(Compiler c)
Parses one function declaration and its required compound body. The parameter bindings are active while the body is parsed, and the first token after the closing brace remains current.
Source: src/parse/functions.x:12
Compiler.parse_function_target
List Compiler.parse_function_target(Compiler c)
Parses one function decorator target and returns its resulting AST. A compatible unit macro at the current token is expanded first; otherwise an ordinary function definition is required.
Source: src/parse/functions.x:28
Compiler.parse_import_declaration
List Compiler.parse_import_declaration(Compiler c)
Parses and registers one import declaration, including its semicolon.
The alias defaults to the package name; with members add source-ordered
local spellings. These spellings affect source resolution only; the package
name in the returned AST drives the generated header include.
Source: src/parse/units.x:342
Compiler.parse_named_type
List Compiler.parse_named_type(Compiler c)
Captures a name followed by an ordinary complete type and semicolon. The reserved typedef identity permits fields to refer to their enclosing named type before its pointer or value representation is complete.
Source: src/parse/types.x:412
Compiler.parse_optional_identifier
List Compiler.parse_optional_identifier(Compiler c)
Consumes and returns the current identifier, or NULL without consuming.
Source: src/parse/declarators.x:626
Compiler.parse_parameter
List Compiler.parse_parameter(Compiler c)
Parses one parameter and returns (param TYPE DECLARATOR) or (...).
Outside macro-template parsing, a named parameter is installed in the
current Sym scope. The following delimiter remains current.
Source: src/parse/declarators.x:493
Compiler.parse_parameter_list
List Compiler.parse_parameter_list(Compiler c)
Parses a nonempty comma-separated parameter List in source order.
The caller owns the parameter scope; the first non-comma delimiter remains
current.
Source: src/parse/declarators.x:476
Compiler.parse_simple_declaration
List Compiler.parse_simple_declaration(Compiler c)
Parses one declaration group and leaves its terminating token current.
Declared names are installed in Sym as their declarators are completed;
the result is one declare, typedef, or initialized dstrdecl AST.
Source: src/parse/declarations.x:35
Compiler.parse_static_assert
List Compiler.parse_static_assert(Compiler c)
Parses a C assertion declaration; native C owns constant-expression checks.
Source: src/parse/declarations.x:130
Compiler.parse_submission
List Compiler.parse_submission(Compiler c, int end_position)
Parses one submission from the current token stream. end_position is
the byte offset after supplied input, before any synthetic closing text.
Missing required syntax raises <incomplete>; trailing items are rejected.
Temporary parser scopes and captured parameters are restored on every exit.
The caller owns the semantic transaction and commits after execution.
Source: src/parse/units.x:208
Compiler.parse_top_level
List Compiler.parse_top_level(Compiler c)
Parses one full top-level form through the shared classifier.
Source: src/parse/units.x:200
Compiler.parse_top_level_mode
List Compiler.parse_top_level_mode(Compiler c, int skip_body)
Parses one top-level form and applies its source-ordered compiler effects.
Returns its AST, or NULL when a keyword definition, top-level Lisp form,
linkage brace, or compile-time-only meta function only updates compiler
state, with the first following token current. With skip_body,
collection uses the same classifier and bound declarations but skips
runtime bodies.
This continuation is independent of the compiler’s shallow-parse state.
Source: src/parse/units.x:16
Compiler.parse_type_name
Type Compiler.parse_type_name(Compiler c)
Parses a type specifier with qualifiers and pointer/reference modifiers.
Returns its flat Type AST and leaves the first following token current.
Source: src/parse/types.x:126
Compiler.parse_type_operand
List Compiler.parse_type_operand(Compiler c, Type *type)
Parses a declaration that sits inside an expression or a for header,
such as a cast’s type name, and returns it as one (decl ...) node.
When type is not null, it receives the declared Type.
Source: src/parse/declarations.x:41
Compiler.place_after
void Compiler.place_after(Compiler c, Var code)
Records code to follow the innermost block item, or the initialized
declarator whose initializer is being parsed directly in it. The
expansion that placed it gives it its result when it finishes.
Source: src/parse/placement.x:108
Compiler.place_entry
void Compiler.place_entry(Compiler c, Var code)
Records code for the entry of the innermost function definition,
after its parameters bind and before its first statement. While parsing,
a lambda body is inside the definition that holds it; while lowering, a
lambda body is the body of its own lifted function, and a finalizer the
kernel wrote as a callback has no entry a program can place at.
Source: src/parse/placement.x:96
Compiler.protocol_form_starts
int Compiler.protocol_form_starts(Compiler c)
Reports whether the cursor begins a protocol declaration or adoption,
including its meta and static markers. This query does not consume
tokens.
Source: src/parse/units.x:300
Compiler.script_statement_executes
int Compiler.script_statement_executes(Compiler c)
Reports whether the top-level item at the cursor is a script statement
that runs, rather than a declaration: an expression, control flow, a
with block, or a statement macro. This query does not consume tokens.
Source: src/parse/units.x:291
Compiler.script_statement_starts
int Compiler.script_statement_starts(Compiler c)
Reports whether the top-level item at the cursor is one of a script
unit’s statements, which become main’s body.
Preprocessor lines, imports, protocols, compile-time definitions and
Lisp, file-scope macro invocations, typedef, static, and extern
declarations, linkage braces, type definitions, and function prototypes
and definitions stay at file scope. This query does not consume tokens.
Source: src/parse/units.x:254
Compiler.skip_linkage_brace
int Compiler.skip_linkage_brace(Compiler c)
Consumes one brace of a C linkage specification at file scope and reports
whether it did. extern "C" { opens a group; a } at file scope closes
the innermost open group, because every other file-scope form consumes
its own braces. The declarations between them stay at file scope. The
#ifdef __cplusplus arm of the usual header guard is skipped, so only an
unguarded group reaches this operation.
Source: src/parse/units.x:109
Compiler.source_clause
Var Compiler.source_clause(Symbol kind)
The source clause kind, which the binder parses when it reaches it.
Source: src/parse/binding.x:307
Compiler.take_meta_marker
Token Compiler.take_meta_marker(Compiler c, int &?native)
Consumes the meta marker at the cursor and the contextual native
marker that may follow it, and returns the meta token. native binds
the definition after it the way a bodyless prototype would. *native,
when requested, reports whether that marker was present.
Source: src/parse/units.x:321
Compiler.test_declaration
int Compiler.test_declaration(Compiler c)
Tests whether the current token can begin a declaration without consuming. Typedefs, package aliases, and macro-hole kinds are resolved through the current compiler state.
Source: src/parse/declarations.x:157
Compiler.test_static_assert
int Compiler.test_static_assert(Compiler c)
Reports whether the current identifier starts a C static assertion.
Source: src/parse/declarations.x:125
Design notes
This module owns declarations and the top-level forms that hold them. One classifier reads each top-level form in collection and in the full parse. Each declarator installs its name in the current Sym before its initializer resolves, and syntax that macros and compile-time Lisp construct binds through the same declaration operations. Expressions, statements, and literals parse in their own modules.