Module

parser.blocks.special_blocks

Special block parsing for Kida parser.

Provides mixin for parsing special blocks (with, raw, capture, cache, filter_block).

Uses inline TYPE_CHECKING declarations for host attributes. See: plan/rfc-mixin-protocol-typing.md

1Class

Classes

SpecialBlockParsingMixin 14 ▼
Mixin for parsing special blocks. Host attributes and cross-mixin dependencies are declared via in…

Mixin for parsing special blocks.

Host attributes and cross-mixin dependencies are declared via inline TYPE_CHECKING blocks. Inherits block stack management from BlockStackMixin.

Methods

Internal Methods 14 ▼
_parse_with 0 Node ▼
Parse {% with %} in two forms: 1. Conditional: {% with expr %} or {% with expr…
def _parse_with(self) -> Node

Parse {% with %} in two forms:

  1. Conditional: {% with expr %} or {% with expr as name %}

    • Binds expr to 'it' or 'name'
    • Skips body if expr is falsy (nil-resilient)

  2. Assignment: {% with name = expr, ... %}

    • Creates variable bindings
    • Always renders body

    Detection: If first token after 'with' is a NAME followed by '=', it's assignment style. Otherwise it's conditional (expression followed by 'as' or '%' }).

Returns
Node
_is_assignment_style_with 0 bool ▼
Detect assignment-style: {% with name = expr %}. Returns True if current token…
def _is_assignment_style_with(self) -> bool

Detect assignment-style: {% with name = expr %}.

Returns True if current token is NAME and next token is ASSIGN.

Returns
bool
_parse_assignment_with 1 With ▼
Parse assignment-style: {% with x = expr, y = expr2 %}...{% end %}. Always ren…
def _parse_assignment_with(self, start: Token) -> With

Parse assignment-style: {% with x = expr, y = expr2 %}...{% end %}.

Always renders body with the specified variable bindings.

Parameters
Name Type Description
start —
Returns
With
_parse_conditional_with 1 WithConditional ▼
Parse conditional: {% with expr %} or {% with expr as name %}...{% end %}. Ren…
def _parse_conditional_with(self, start: Token) -> WithConditional

Parse conditional: {% with expr %} or {% with expr as name %}...{% end %}.

Renders body only if expr is truthy. Binds expr to 'name' or 'it'. Supports multiple expressions and bindings: {% with a, b as x, y %}. Also supports {% else %} or {% empty %} for falsy cases.

Parameters
Name Type Description
start —
Returns
WithConditional
_parse_flush 0 Flush ▼
Parse {% flush %} — streaming flush boundary. Creates an explicit yield bounda…
def _parse_flush(self) -> Flush

Parse {% flush %} — streaming flush boundary.

Creates an explicit yield boundary in streaming mode. No-op in non-streaming (render) mode.

Returns
Flush
_parse_raw 0 Raw ▼
Parse {% raw %}...{% endraw %. Raw block that prevents template processing of …
def _parse_raw(self) -> Raw

Parse {% raw %}...{% endraw %.

Raw block that prevents template processing of its content.

Returns
Raw
_parse_capture 0 Capture ▼
Parse {% capture name %}...{% end %} or {% endcapture %. Capture rendered cont…
def _parse_capture(self) -> Capture

Parse {% capture name %}...{% end %} or {% endcapture %.

Capture rendered content into a variable.

Returns
Capture
_parse_cache 0 Cache ▼
Parse {% cache key %}...{% end %} or {% endcache %. Fragment caching with opti…
def _parse_cache(self) -> Cache

Parse {% cache key %}...{% end %} or {% endcache %.

Fragment caching with optional TTL.

Returns
Cache
_parse_filter_block 0 FilterBlock ▼
Parse {% filter name %}...{% end %} or {% endfilter %. Apply a filter to an en…
def _parse_filter_block(self) -> FilterBlock

Parse {% filter name %}...{% end %} or {% endfilter %.

Apply a filter to an entire block of content.

Returns
FilterBlock
_parse_spaceless 0 Spaceless ▼
Parse {% spaceless %}...{% end %} or {% endspaceless %}. Removes whitespace be…
def _parse_spaceless(self) -> Spaceless

Parse {% spaceless %}...{% end %} or {% endspaceless %}.

Removes whitespace between HTML tags. Part of RFC: kida-modern-syntax-features.

Returns
Spaceless
_parse_embed 0 Embed ▼
Parse {% embed 'template.html' %}...{% end %} or {% endembed %}. Embed is like…
def _parse_embed(self) -> Embed

Parse {% embed 'template.html' %}...{% end %} or {% endembed %}.

Embed is like include but allows block overrides. Part of RFC: kida-modern-syntax-features.

Returns
Embed
_parse_push 0 Push ▼
Parse {% push "stack_name" %}...{% end %}. Push rendered content onto a named …
def _parse_push(self) -> Push

Parse {% push "stack_name" %}...{% end %}.

Push rendered content onto a named stack for deferred output.

Example::

{% push "scripts" %}
    <script src="widget.js"></script>
{% end %}
Returns
Push
_parse_stack 0 Stack ▼
Parse {% stack "stack_name" %}. Emit all content previously pushed to the name…
def _parse_stack(self) -> Stack

Parse {% stack "stack_name" %}.

Emit all content previously pushed to the named stack.

Example::

{% stack "scripts" %}
Returns
Stack
_parse_provide 0 Provide ▼
Parse {% provide key = expr %}...{% endprovide %}. Provide a value to descenda…
def _parse_provide(self) -> Provide

Parse {% provide key = expr %}...{% endprovide %}.

Provide a value to descendant consumers via render context. Consumers read it withconsume("key").

Example::

{% provide table_align = ["left", "center", "right"] %}
    {{ row("Alice", "Active", "42") }}
{% end %}
Returns
Provide