Frontend API

Frontend API for parsing CrossGL and registering translator extensions.

crosstl.translator.get_backend_spec(name)

Lookup a backend codegen spec.

crosstl.translator.parse(shader_code)

Parse shader code and return the AST.

Parameters:

shader_code (str) – The shader code to parse

Returns:

The abstract syntax tree

crosstl.translator.register_backend_spec(spec, *, overwrite=False)

Register a new backend codegen spec.

Return type:

BackendSpec

crosstl.translator.register_source(spec, *, overwrite=False)

Register a new backend source (lexer/parser) spec.

Return type:

SourceSpec

crosstl.translator.supported_backends()

Return registered backend codegens.

crosstl.translator.supported_sources()

Return registered source backends.

Lexer for tokenizing CrossGL source code.

class crosstl.translator.lexer.Lexer(code)

Bases: object

Tokenizer for CrossGL Universal IR.

debug_print()

Print token indexes, types, and text for grammar debugging.

get_tokens()

Return the token list produced by the lexer.

tokenize()

Scan source text into parser-ready tokens.

Parser that builds CrossGL AST nodes from lexer tokens.

class crosstl.translator.parser.Parser(tokens)

Bases: object

Recursive-descent parser for CrossGL Universal IR tokens.

advance_over_type()

Advance over a type expression during lookahead checks.

create_empty_shader()

Create an empty shader used by parser error recovery.

eat(token_type)

Consume one token of the expected type or raise SyntaxError.

finalize_shader(shader)

Run final validation hooks before returning a shader AST.

format_type_argument(type_node)

Format a parsed type node back into a compact type argument string.

in_parameter_context()

Check if we’re currently parsing function parameters.

is_cbuffer_declaration()

Return whether the current token begins a cbuffer declaration.

is_function_declaration()

Return whether the current token sequence looks like a function.

is_type_token()

Return whether the current token can start a type expression.

is_variable_declaration()

Lookahead check for variable declarations. Handles complex cases and distinguishes from function calls and member access.

next_token()

Advance to the next token without validating token type.

parse()

Parse a complete CrossGL translation unit into a ShaderNode.

parse_additive_expression()

Parse addition and subtraction expressions.

parse_array_literal()

Parse a braced array literal expression.

parse_assignment_expression()

Parse assignment and compound-assignment expressions.

parse_attributes()

Parse one or more @ attribute annotations.

parse_bitwise_and_expression()

Parse bitwise AND expressions.

parse_bitwise_or_expression()

Parse bitwise OR expressions.

parse_bitwise_xor_expression()

Parse bitwise XOR expressions.

parse_block()

Parse a braced statement block.

parse_case()

Parse one explicit switch case.

parse_cbuffer_as_struct()

Parse a constant/uniform buffer declaration as a struct node.

parse_constant()

Parse a constant declaration.

parse_default_case()

Parse the default switch case.

parse_enum()

Parse an enum declaration and its variants.

parse_enum_variant()

Parse one enum variant, including tuple or struct payloads.

parse_equality_expression()

Parse equality and inequality expressions.

parse_expression()

Parse an expression using the highest-precedence entry point.

parse_for_in_statement_after_for()

Parse a for pattern in iterable loop after for is consumed.

parse_for_loop_variable_declaration()

Parse variable declarations in for loops (without consuming semicolon).

parse_for_statement()

Parse a C-style for loop or dispatch to for-in parsing.

parse_function()

Parse a function declaration or definition.

parse_generic_arguments()

Parse generic type arguments after <.

parse_generic_declaration()

Parse legacy generic declarations that wrap structs/enums/functions.

parse_generic_parameters()

Parse generic parameter declarations after <.

parse_global()

Parse one top-level declaration or recover past unsupported input.

parse_if_statement()

Parse an if/else statement chain.

parse_import()

Parse an import or use declaration.

parse_integer_literal_parts(value)

Return integer digits and signedness for an integer literal.

parse_legacy_shader()

Return an empty legacy shader root.

parse_let_declaration()

Parse Rust-style let [mut] name [: type] = expr; declarations.

parse_literal()

Parse a scalar literal token into a typed literal node.

parse_logical_and_expression()

Parse logical AND expressions.

parse_logical_or_expression()

Parse logical OR expressions.

parse_loop_statement()

Parse an unconditional loop statement.

parse_match_arm()

Parse a single match arm.

parse_match_statement()

Parse a match statement and all of its arms.

parse_multiplicative_expression()

Parse multiplication, division, and modulo expressions.

parse_parameter()

Parse one function parameter declaration.

parse_parameter_list()

Parse a comma-separated function parameter list.

parse_pattern()

Parse a match pattern.

parse_postfix_expression()

Parse member, call, index, and postfix unary expressions.

parse_precision_statement()

Parse a GLSL-style precision statement as a preprocessor node.

parse_preprocessor_directive()

Parse a preprocessor token into a structured directive node.

parse_primary_expression()

Parse identifiers, literals, parenthesized expressions, and arrays.

parse_program()

Parse the explicit program form used by legacy callers.

parse_range_expression()

Parse range and inclusive-range expressions.

parse_relational_expression()

Parse relational comparison expressions.

parse_return_statement()

Parse a return statement with an optional value.

parse_shader_declaration()

Parse a named shader block and its contained declarations.

parse_shader_stage()

Parse a legacy stage block into a function node.

parse_shader_stage_block()

Parse a stage-qualified block into a StageNode.

parse_shift_expression()

Parse bit-shift expressions.

parse_statement()

Parse any statement form supported by CrossGL.

parse_struct()

Parse a struct declaration and its member list.

parse_struct_member()

Parse one struct member declaration.

parse_switch_statement()

Parse a switch statement and its case clauses.

parse_ternary_expression()

Parse a ternary conditional expression.

parse_trait()

Parse a trait-like declaration into the current AST shape.

parse_type()

Parse a CrossGL type expression into a TypeNode.

parse_unary_expression()

Parse prefix unary expressions.

parse_variable_declaration()

Parse a variable declaration, including qualifiers and attributes.

parse_while_statement()

Parse a while loop statement.

peek(offset=1)

Return a lookahead token without advancing the parser.

report_error(message)

Emit a parser warning.

skip_comments()

Consume single-line and multi-line comment tokens.

skip_unknown_token()

Consume one token when recovering from unsupported syntax.

vector_element_type_from_generic(type_node)

Resolve a vector generic argument to a primitive element type.

Canonical CrossGL abstract syntax tree node definitions.

class crosstl.translator.ast.ASTNode(source_location=None, annotations=None)

Bases: object

Base class for all AST nodes with common functionality.

accept(visitor)

Dispatch this node to a visitor method named for its class.

add_annotation(key, value)

Attach backend or analysis metadata to this node.

get_annotation(key, default=None)

Return an annotation value, or a default when it is absent.

class crosstl.translator.ast.ArrayAccessNode(array_expr, index_expr, **kwargs)

Bases: ExpressionNode

Array indexing.

class crosstl.translator.ast.ArrayLiteralNode(elements, **kwargs)

Bases: ExpressionNode

Array literal expression such as {1, 2, 3}.

class crosstl.translator.ast.ArrayNode(element_type, name, size=None, semantic=None, **kwargs)

Bases: VariableNode

Legacy array node for backward compatibility.

class crosstl.translator.ast.ArrayType(element_type, size=None, **kwargs)

Bases: TypeNode

Array types with static or dynamic sizing.

class crosstl.translator.ast.AssignmentNode(target, value, operator='=', **kwargs)

Bases: StatementNode

Assignment operations.

class crosstl.translator.ast.AtomicOpNode(operation, target, arguments, **kwargs)

Bases: ExpressionNode

Atomic operations for GPU computing.

class crosstl.translator.ast.AttributeNode(name, arguments=None, **kwargs)

Bases: ASTNode

Attributes/annotations/decorators.

class crosstl.translator.ast.BinaryOpNode(left, operator, right, **kwargs)

Bases: ExpressionNode

Binary operations.

class crosstl.translator.ast.BlockNode(statements, **kwargs)

Bases: StatementNode

Block of statements.

class crosstl.translator.ast.BreakNode(label=None, **kwargs)

Bases: StatementNode

Break statements.

class crosstl.translator.ast.BufferNode(name, buffer_type, binding=None, set_=None, access='read_write', **kwargs)

Bases: ASTNode

Buffer resource declarations.

class crosstl.translator.ast.BufferOpNode(operation, buffer_expr, arguments, **kwargs)

Bases: ExpressionNode

Buffer operations like Load/Store/Append/Consume.

class crosstl.translator.ast.BuiltinVariableNode(builtin_name, component=None, **kwargs)

Bases: ExpressionNode

Built-in variables (gl_Position, threadIdx, etc.).

class crosstl.translator.ast.CaseNode(value, statements, **kwargs)

Bases: ASTNode

Switch case.

class crosstl.translator.ast.CastNode(expression, target_type, **kwargs)

Bases: ExpressionNode

Type casting.

crosstl.translator.ast.CbufferNode

alias of StructNode

class crosstl.translator.ast.ConstantNode(name, const_type, value, visibility='public', **kwargs)

Bases: ASTNode

Compile-time constants.

class crosstl.translator.ast.ConstructorNode(constructor_type, arguments, named_arguments=None, **kwargs)

Bases: ExpressionNode

Type constructors (vec3(1,2,3), MyStruct{field: value}).

class crosstl.translator.ast.ContinueNode(label=None, **kwargs)

Bases: StatementNode

Continue statements.

class crosstl.translator.ast.EnumNode(name, variants, underlying_type=None, attributes=None, **kwargs)

Bases: ASTNode

Enumeration declarations.

class crosstl.translator.ast.EnumVariantNode(name, value=None, fields=None, **kwargs)

Bases: ASTNode

Individual enum variant.

class crosstl.translator.ast.ExecutionModel(value)

Bases: Enum

Different execution models supported.

class crosstl.translator.ast.ExpressionNode(expression_type=None, **kwargs)

Bases: ASTNode

Base class for all expressions.

class crosstl.translator.ast.ExpressionStatementNode(expression, **kwargs)

Bases: StatementNode

Expression used as a statement.

class crosstl.translator.ast.ForInNode(pattern, iterable, body, **kwargs)

Bases: StatementNode

For-in loop (Rust, Python style).

class crosstl.translator.ast.ForNode(init, condition, update, body, **kwargs)

Bases: StatementNode

For loop statements.

class crosstl.translator.ast.FunctionCallNode(function, arguments, generic_args=None, **kwargs)

Bases: ExpressionNode

Function calls.

class crosstl.translator.ast.FunctionNode(name, return_type, parameters, body=None, generic_params=None, attributes=None, visibility='public', qualifiers=None, is_unsafe=False, is_async=False, **kwargs)

Bases: ASTNode

Function declarations.

class crosstl.translator.ast.FunctionType(return_type, param_types, **kwargs)

Bases: TypeNode

Function pointer/reference types.

class crosstl.translator.ast.GenericParameterNode(name, constraints=None, default_type=None, **kwargs)

Bases: ASTNode

Generic/template parameter.

class crosstl.translator.ast.GenericType(name, constraints=None, **kwargs)

Bases: TypeNode

Generic/template type parameters.

class crosstl.translator.ast.IdentifierNode(name, **kwargs)

Bases: ExpressionNode

Variable/function identifiers.

class crosstl.translator.ast.IdentifierPatternNode(name, **kwargs)

Bases: PatternNode

Identifier pattern (variable binding).

class crosstl.translator.ast.IfNode(condition, then_branch, else_branch=None, **kwargs)

Bases: StatementNode

Conditional statements.

class crosstl.translator.ast.ImportNode(path, alias=None, items=None, **kwargs)

Bases: ASTNode

Import/include statements.

class crosstl.translator.ast.LambdaNode(parameters, body, captures=None, **kwargs)

Bases: ExpressionNode

Lambda/closure expressions.

class crosstl.translator.ast.LiteralNode(value, literal_type, **kwargs)

Bases: ExpressionNode

Literal values.

class crosstl.translator.ast.LiteralPatternNode(literal, **kwargs)

Bases: PatternNode

Literal pattern.

class crosstl.translator.ast.LoopNode(body, label=None, **kwargs)

Bases: StatementNode

Infinite loop (Rust style).

class crosstl.translator.ast.MatchArmNode(pattern, guard, body, **kwargs)

Bases: ASTNode

Pattern matching arm.

class crosstl.translator.ast.MatchNode(expression, arms, **kwargs)

Bases: StatementNode

Pattern matching (Rust, functional languages).

class crosstl.translator.ast.MatrixType(element_type, rows, cols, **kwargs)

Bases: TypeNode

Matrix types (mat4, float4x4, etc.).

class crosstl.translator.ast.MemberAccessNode(object_expr, member, **kwargs)

Bases: ExpressionNode

Member access (dot operator).

class crosstl.translator.ast.MeshOpNode(operation, arguments, **kwargs)

Bases: ExpressionNode

Mesh/task shader intrinsics (SetMeshOutputCounts, DispatchMesh).

class crosstl.translator.ast.NamedType(name, generic_args=None, **kwargs)

Bases: TypeNode

User-defined types (structs, enums, etc.).

class crosstl.translator.ast.ParameterNode(name, param_type, default_value=None, attributes=None, is_mutable=False, **kwargs)

Bases: ASTNode

Function parameter.

class crosstl.translator.ast.PatternNode(source_location=None, annotations=None)

Bases: ASTNode

Base class for patterns in pattern matching.

class crosstl.translator.ast.PointerAccessNode(pointer_expr, member, **kwargs)

Bases: ExpressionNode

Pointer member access (arrow operator).

class crosstl.translator.ast.PointerType(pointee_type, is_mutable=True, **kwargs)

Bases: TypeNode

Pointer types for languages that support them.

class crosstl.translator.ast.PreprocessorNode(directive, content='', **kwargs)

Bases: ASTNode

Preprocessor directives (e.g. #version, #include).

class crosstl.translator.ast.PrimitiveType(name, size_bits=None, **kwargs)

Bases: TypeNode

Primitive types (int, float, bool, etc.).

class crosstl.translator.ast.RangeNode(start, end, inclusive=False, **kwargs)

Bases: ExpressionNode

Integer range expression.

class crosstl.translator.ast.RayQueryOpNode(operation, query_expr, arguments, **kwargs)

Bases: ExpressionNode

RayQuery method calls.

class crosstl.translator.ast.RayTracingOpNode(operation, arguments, **kwargs)

Bases: ExpressionNode

Raytracing intrinsics like TraceRay, ReportHit, etc.

class crosstl.translator.ast.ReferenceType(referenced_type, is_mutable=False, **kwargs)

Bases: TypeNode

Reference types for languages like Rust.

class crosstl.translator.ast.ReturnNode(value=None, **kwargs)

Bases: StatementNode

Return statements.

class crosstl.translator.ast.SamplerNode(name, filter_mode='linear', address_mode='clamp', binding=None, **kwargs)

Bases: ASTNode

Sampler resource declarations.

class crosstl.translator.ast.ShaderNode(name, execution_model, stages=None, structs=None, functions=None, global_variables=None, constants=None, cbuffers=None, imports=None, preprocessors=None, **kwargs)

Bases: ASTNode

Root node representing a complete shader program.

class crosstl.translator.ast.ShaderStage(value)

Bases: Enum

Shader pipeline stages.

class crosstl.translator.ast.StageNode(stage, entry_point, local_variables=None, local_functions=None, execution_config=None, **kwargs)

Bases: ASTNode

Individual shader stage (vertex, fragment, compute, etc.).

class crosstl.translator.ast.StatementNode(source_location=None, annotations=None)

Bases: ASTNode

Base class for all statements.

class crosstl.translator.ast.StructMemberNode(name, member_type, default_value=None, attributes=None, visibility='public', **kwargs)

Bases: ASTNode

Individual struct member.

class crosstl.translator.ast.StructNode(name, members, generic_params=None, attributes=None, inheritance=None, visibility='public', **kwargs)

Bases: ASTNode

Struct/class declarations.

class crosstl.translator.ast.StructPatternNode(type_name, field_patterns, **kwargs)

Bases: PatternNode

Struct destructuring pattern.

class crosstl.translator.ast.SwitchNode(expression, cases, default_case=None, **kwargs)

Bases: StatementNode

Switch statements.

class crosstl.translator.ast.SwizzleNode(vector_expr, components, **kwargs)

Bases: ExpressionNode

Vector swizzling (vec.xyz, vec.xxyy, etc.).

class crosstl.translator.ast.SyncNode(sync_type, arguments=None, **kwargs)

Bases: StatementNode

Synchronization operations.

class crosstl.translator.ast.TernaryOpNode(condition, true_expr, false_expr, **kwargs)

Bases: ExpressionNode

Ternary conditional operator.

class crosstl.translator.ast.TextureNode(texture_expr, sampler_expr, coordinates, level=None, offset=None, **kwargs)

Bases: ExpressionNode

Texture sampling operations.

class crosstl.translator.ast.TextureOpNode(operation, texture_expr, arguments, sampler_expr=None, **kwargs)

Bases: ExpressionNode

Extended texture operations (Sample, Load, Gather, etc.).

class crosstl.translator.ast.TextureResourceNode(name, texture_type, format=None, binding=None, set_=None, **kwargs)

Bases: ASTNode

Texture resource declarations.

class crosstl.translator.ast.TypeNode(source_location=None, annotations=None)

Bases: ASTNode

Base class for all type representations.

class crosstl.translator.ast.UnaryOpNode(operator, operand, is_postfix=False, **kwargs)

Bases: ExpressionNode

Unary operations.

class crosstl.translator.ast.VariableNode(name, var_type, initial_value=None, attributes=None, qualifiers=None, is_mutable=True, visibility='private', **kwargs)

Bases: ASTNode

Variable declarations.

get_semantic_from_attributes()

Return the legacy semantic name derived from variable attributes.

crosstl.translator.ast.VectorConstructorNode

alias of ConstructorNode

class crosstl.translator.ast.VectorType(element_type, size, **kwargs)

Bases: TypeNode

Vector types (vec2, vec3, vec4, float3, etc.).

class crosstl.translator.ast.WaveOpNode(operation, arguments, **kwargs)

Bases: ExpressionNode

Wave/subgroup operations.

class crosstl.translator.ast.WhileNode(condition, body, **kwargs)

Bases: StatementNode

While loop statements.

class crosstl.translator.ast.WildcardPatternNode(source_location=None, annotations=None)

Bases: PatternNode

Wildcard pattern (_).

crosstl.translator.ast.create_legacy_shader_node(structs, functions, global_variables, cbuffers)

Create a root shader node for legacy tests and backend adapters.