# special_blocks URL: /kida/api/compiler/statements/special_blocks/ Section: statements Description: Special block statement compilation for Kida compiler. Provides mixin for compiling special block statements (raw, capture, spaceless, embed). With-blocks are in with_blocks.py; cache/filter_block are in caching.py. Uses inline TYPE_CHECKING declarations for host attributes. See: plan/rfc-mixin-protocol-typing.md --- > For a complete page index, fetch /kida/llms.txt. Open LLM text (/kida/api/compiler/statements/special_blocks/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcompiler%2Fstatements%2Fspecial_blocks%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcompiler%2Fstatements%2Fspecial_blocks%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcompiler%2Fstatements%2Fspecial_blocks%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fcompiler%2Fstatements%2Fspecial_blocks%2Findex.txt) Module # `compiler.statements.special_blocks` Special block statement compilation for Kida compiler. Provides mixin for compiling special block statements (raw, capture, spaceless, embed). With-blocks are in with_blocks.py; cache/filter_block are in caching.py. Uses inline TYPE_CHECKING declarations for host attributes. See: plan/rfc-mixin-protocol-typing.md 1Class ## Classes `SpecialBlockMixin` 8 ▼ Mixin for compiling special block statements. Host attributes and cross-mixin dependencies are dec… Mixin for compiling special block statements. Host attributes and cross-mixin dependencies are declared via inline TYPE_CHECKING blocks. #### Methods Internal Methods 8 ▼ `_compile_flush` 1 `list[ast.stmt]` ▼ Compile {% flush %} — streaming flush boundary. In streaming mode: yield "" to… `def _compile_flush(self, node: Flush) -> list[ast.stmt]` Compile {% flush %} — streaming flush boundary. In streaming mode: yield "" to create a chunk boundary. In non-streaming mode: no-op. ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_raw` 1 `list[ast.stmt]` ▼ Compile {% raw %}...{% endraw %. Raw block content is output as literal text. `def _compile_raw(self, node: Raw) -> list[ast.stmt]` Compile {% raw %}...{% endraw %. Raw block content is output as literal text. ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_capture` 1 `list[ast.stmt]` ▼ Compile {% capture x %}...{% end %} (Kida) or {% set x %}...{% endset %} (Jinja… `def _compile_capture(self, node: Capture) -> list[ast.stmt]` Compile {% capture x %}...{% end %} (Kida) or {% set x %}...{% endset %} (Jinja). Captures rendered block content into a variable. In streaming mode, body is compiled in StringBuilder mode (captures into a buffer, not the output stream), then result is assigned to ctx. ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_spaceless` 1 `list[ast.stmt]` ▼ Compile {% spaceless %}...{% end %}. Removes whitespace between HTML tags. In … `def _compile_spaceless(self, node: Spaceless) -> list[ast.stmt]` Compile {% spaceless %}...{% end %}. Removes whitespace between HTML tags. In streaming mode: collect into buffer, transform, yield result. ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_push` 1 `list[ast.stmt]` ▼ Compile {% push "name" %}...{% end %}. Captures body content into a buffer, th… `def _compile_push(self, node: Push) -> list[ast.stmt]` Compile {% push "name" %}...{% end %}. Captures body content into a buffer, then appends the result to the named stack on the RenderContext. Generates: ``` _push_buf_N = [] _push_append_N = _push_buf_N.append _rc._stacks.setdefault("name", []).append("".join(_push_buf_N)) ``` ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_stack` 1 `list[ast.stmt]` ▼ Compile {% stack "name" %}. Emits all content pushed to the named stack. Gene… `def _compile_stack(self, node: Stack) -> list[ast.stmt]` Compile {% stack "name" %}. Emits all content pushed to the named stack. Generates: ``` for _stack_item_N in _rc._stacks.get("name", ()): _append(_stack_item_N) ``` ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_provide` 1 `list[ast.stmt]` ▼ Compile {% provide key = expr %}...{% endprovide %}. Pushes a value onto the R… `def _compile_provide(self, node: Provide) -> list[ast.stmt]` Compile {% provide key = expr %}...{% endprovide %}. Pushes a value onto the RenderContext provider stack, compiles the body, then pops in a finally block to guarantee cleanup. Generates: ``` _rc.provide("key", ) try: finally: _rc.unprovide("key") ``` ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]` `_compile_embed` 1 `list[ast.stmt]` ▼ Compile {% embed 'template.html' %}...{% end %}. Embed is like include but all… `def _compile_embed(self, node: Embed) -> list[ast.stmt]` Compile {% embed 'template.html' %}...{% end %}. Embed is like include but allows block overrides. Part of RFC: kida-modern-syntax-features. Generates: ``` _saved_blocks_N = _blocks.copy() def _block_name(ctx, _blocks): ... # For each override _blocks['name'] = _block_name _append(_include(template, ctx, _blocks)) _blocks = _saved_blocks_N ``` ##### Parameters Name Type Description `node` `—` ##### Returns `list[ast.stmt]`