Syntax transformers

koskari.syntax

Syntax dispatch scaffolding

class koskari.syntax.BareTransform(slot, template)

Bases: SyntaxTransform

Bare arm: template expansion for the syntax name used as a lone atom rather than at the head of a call form. The called-by symbol is the only capture, bound to slot, so the arm has no pattern and no matcher

expand_bare(compiler, sym, position=None)

Expand template with sym bound to the called-by slot

The capture carries the caller-threaded enclosing position: the atom itself is interned and positionless, so the enclosing form’s position is the best available location for diagnostics

Parameters:

  • compiler – active compiler instance

  • sym – lone atom that triggered this expansion

  • position – enclosing source position threaded by the caller

Returns:

expanded form after finalize

class koskari.syntax.MacroTransform(pattern, handler, matcher=None, repeat_variables=None)

Bases: Transform

Procedural arm: invoke handler, then mark and finalize its output

handle_expand(compiler, source, captures)

Run handler, then mark and finalize the result

Parameters:

  • compiler – active compiler

  • source – full special form (proper list spine)

  • captures – the captures of self.matcher

Returns:

expanded form after finalize

class koskari.syntax.SpecialTransform(pattern, handler, matcher=None, repeat_variables=None)

Bases: Transform

Special arm: handler return is the compile result (no marking)

handle_expand(compiler, source, captures)

Return handler result unchanged

Parameters:

  • compiler – active compiler

  • source – full special form (proper list spine)

  • captures – the captures of self.matcher

Returns:

compile product from the handler

class koskari.syntax.Syntax(name, transforms=(), bare=None)

Bases: Compiled

Ordered dispatcher over Transform clauses (compiled form). Try order follows transforms tuple order; use __add__ to prepend clauses

A syntax may also carry one BareTransform in its bare slot, outside the ordered transforms. That arm expands the syntax name when it appears as a lone atom rather than at the head of a call form

Parameters:

  • name – primary compile-time symbol for this form

  • transforms – ordered transforms tried on each expansion

  • bare – lone-atom arm, or None

append_doc(doc)

Append an extension’s documentation to what this syntax already carries. Used by extend-syntax so an extension describes what it adds rather than replacing the original text

Parameters:

doc – documentation text contributed by the extension

Returns:

self

compile_impl(compiler, source_obj)

Try each transform in order; the first arm whose pattern matches expands, and its result is returned as it is

A non-pair source is a lone-atom use, which bypasses the matchers entirely and goes straight to the bare arm

A bare-only syntax (no call arms at all) used in form position is an alias: the head expands through the bare arm and the tail rides along for recompilation. A syntax that has call arms never falls back to its bare arm – a form no call arm matches is a malformed use, and the bare arm stands in for the lone atom, not for a call

Parameters:

  • compiler – active compiler instance

  • source_obj – full special form being compiled

Raises:

SyntaxMatchError – when no arm matches

Returns:

compile product from the winning transform

match_transformer(form)

Match form against each arm’s matcher in order through FIRST_MATCH; the first that matches selects its arm

Parameters:

form – special form pair spine

Returns:

(transform, captures) where transform is the matching transform and captures its captures, or (None, None)

property patterns
class koskari.syntax.SyntaxTransform(pattern, template, pattern_src=nil, matcher=None, repeat_variables=None)

Bases: Transform

Template arm: template expansion with a fresh mark, then finalize

handle_expand(compiler, source, captures)

expand template with the captures

Parameters:

  • compiler – active compiler

  • source – full special form (proper list spine)

  • captures – the captures of self.matcher

Returns:

expanded form after finalize

class koskari.syntax.Transform(pattern, matcher=None, repeat_variables=None)

Bases: ABC

One clause of a Syntax dispatcher: its matcher function, and try_expand through it

abstractmethod handle_expand(compiler, source, captures)

When the pattern matches, handle the expansion.

matcher: Any
pattern: Any
try_expand(compiler, source_obj)

Try this arm on source_obj; return compile result or None

Parameters:

  • compiler – active compiler instance

  • source_obj – full special form as a proper list (pair spine)

Returns:

fragment or form for compile_special, or None when the pattern does not match

koskari.syntax.build_bare_syntax(name, slot, template)

Koskari runtime: (build-bare-syntax NAME SLOT TMPL), producing a Syntax carrying only a bare arm. SLOT names the called-by capture that TMPL refers to. Combine with + to attach the arm to an existing syntax

koskari.syntax.build_macro(name, *pattern_and_lambdas)

Koskari runtime: (build-macro NAME PAT LAMBDA ...)

koskari.syntax.build_special(name, *pattern_and_lambdas)

Koskari runtime: (build-special NAME PAT LAMBDA ...)

koskari.syntax.build_syntax(name, *pattern_template_pairs)

Koskari runtime: (build-syntax NAME ROW ...), each row a matcher function, its repeat variables, its pattern source and a template datum, as compile/syntax-rules and compile/syntax-match emit

koskari.syntax.parse_syntax_rules_pattern(pattern_expr, literals, source_ctx, variables=None)

Lower a syntax-rules RULE pattern (cons tree) to a matcher.Pattern.

RULE dialect only; does not implement the MATCH dialect’s registry heads. parse_rule_pattern() calls this when lowering pattern source.

Parameters:

  • pattern_expr – koskari pattern datum

  • literals – set, frozenset, list, or tuple of literal symbols

  • source_ctx – value recorded in error messages

  • variables – a dict that, when given, receives each pattern variable’s name mapped to its source symbol, in the order the variables are bound

Return type:

Pattern

koskari.syntax.special(form_symbol, *, patterns, unpack=None)

Build a Syntax dispatcher whose arms are SpecialTransform instances wrapping the decorated function. unpack selects one of three fixed invoke shapes at decoration time (no per-call unpack dispatch)

Parameters:

  • form_symbol – primary compile-time head symbol for this form

  • patterns – one matcher.Pattern or an iterable (try-order)

  • unpack – only for this decorator: None (receive compiler, source_obj), match (receive compiler, captures_dict), or kwargs (captures merged after compiler). For match and kwargs, captures_dict includes only slots the matcher bound; values are matcher outputs (Datum wrappers may be present). Not available on build_* rule rows.