# special_blocks URL: /api/compiler/statements/special_blocks/ Section: statements -------------------------------------------------------------------------------- special_blocks - Kida window.BENGAL_THEME_DEFAULTS = { appearance: 'light', palette: 'brown-bengal' }; window.Bengal = window.Bengal || {}; window.Bengal.enhanceBaseUrl = '/kida/assets/js/enhancements'; window.Bengal.watchDom = true; window.Bengal.debug = false; window.Bengal.enhanceUrls = { 'toc': '/kida/assets/js/enhancements/toc.632a9783.js', 'docs-nav': '/kida/assets/js/enhancements/docs-nav.57e4b129.js', 'tabs': '/kida/assets/js/enhancements/tabs.aac9e817.js', 'lightbox': '/kida/assets/js/enhancements/lightbox.1ca22aa1.js', 'interactive': '/kida/assets/js/enhancements/interactive.fc077855.js', 'mobile-nav': '/kida/assets/js/enhancements/mobile-nav.d991657f.js', 'action-bar': '/kida/assets/js/enhancements/action-bar.d62417f4.js', 'copy-link': '/kida/assets/js/enhancements/copy-link.7d9a5c29.js', 'data-table': '/kida/assets/js/enhancements/data-table.1f5bc1eb.js', 'lazy-loaders': '/kida/assets/js/enhancements/lazy-loaders.a5c38245.js', 'holo': '/kida/assets/js/enhancements/holo.ee13c841.js', 'link-previews': '/kida/assets/js/enhancements/link-previews.8d906535.js' }; (function () { try { var defaults = window.BENGAL_THEME_DEFAULTS || { appearance: 'system', palette: '' }; var defaultAppearance = defaults.appearance; if (defaultAppearance === 'system') { defaultAppearance = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light'; } var storedTheme = localStorage.getItem('bengal-theme'); var storedPalette = localStorage.getItem('bengal-palette'); var theme = storedTheme ? (storedTheme === 'system' ? defaultAppearance : storedTheme) : defaultAppearance; var palette = storedPalette ?? defaults.palette; document.documentElement.setAttribute('data-theme', theme); if (palette) { document.documentElement.setAttribute('data-palette', palette); } } catch (e) { document.documentElement.setAttribute('data-theme', 'light'); } })(); { "prerender": [ { "where": { "and": [ { "href_matches": "/docs/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ], "prefetch": [ { "where": { "and": [ { "href_matches": "/*" }, { "not": { "selector_matches": "[data-external], [target=_blank], .external" } } ] }, "eagerness": "conservative" } ] } Skip to main content Magnifying Glass ESC Recent Clear Magnifying Glass No results for "" Start typing to search... ↑↓ Navigate ↵ Open ESC Close Powered by Lunr )彡 DocumentationInfoAboutArrow ClockwiseGet StartedCodeSyntaxTerminalUsageNoteTutorialsStarburstExtendingBookmarkReferenceTroubleshootingReleasesDevGitHubKida API Reference Magnifying Glass Search ⌘K Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal List )彡 Magnifying Glass Search X Close Documentation Caret Down Info About Arrow Clockwise Get Started Code Syntax Terminal Usage Note Tutorials Starburst Extending Bookmark Reference Troubleshooting Releases Dev Caret Down GitHub Kida API Reference Palette Appearance Chevron Down Mode Monitor System Sun Light Moon Dark Palette Snow Lynx Brown Bengal Silver Bengal Charcoal Bengal Blue Bengal Kida API Reference Caret Right Analysis analyzer cache config dependencies landmarks metadata purity roles Caret Right Compiler Caret Right Statements basic control_flow functions special_blocks template_structure variables _protocols coalescing core expressions utils Caret Right Environment core exceptions filters loaders protocols registry tests Caret Right Parser Caret Right Blocks control_flow core functions special_blocks template_structure variables _protocols core errors expressions statements tokens Caret Right Utils html lru_cache workers _types bytecode_cache kida lexer nodes template tstring CompilerStatements ᗢ Caret Down Link Copy URL External Open LLM text Copy Copy LLM text Share with AI Ask Claude Ask ChatGPT Ask Gemini Ask Copilot Module compiler.statements.special_blocks Special block statement compilation for Kida compiler. Provides mixin for compiling special block statements (with, raw, capture, cache, filter_block). 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_with 1 list[ast.stmt] ▼ Compile {% with var=value, ... %}...{% endwith %. Creates temporary variable b… def _compile_with(self, node: Any) -> list[ast.stmt] Compile {% with var=value, ... %}...{% endwith %. Creates temporary variable bindings scoped to the with block. We store old values and restore them after the block. Parameters Name Type Description node — Returns list[ast.stmt] _compile_with_conditional 1 list[ast.stmt] ▼ Compile {% with expr as target %}...{% end %} (conditional form). Renders body… def _compile_with_conditional(self, node: Any) -> list[ast.stmt] Compile {% with expr as target %}...{% end %} (conditional form). Renders body only if expr is truthy. Binds expr result to target. Supports multiple bindings and structural unpacking. Provides nil-resilience: block is silently skipped when expr is falsy. Generates: _with_val_N = expr if _with_val_N: # [save old values] # [bind new values] ... body ... # [restore old values] 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: Any) -> 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: Any) -> list[ast.stmt] Compile {% capture x %}...{% end %} (Kida) or {% set x %}...{% endset %} (Jinja). Captures rendered block content into a variable. Parameters Name Type Description node — Returns list[ast.stmt] _compile_cache 1 list[ast.stmt] ▼ Compile {% cache key %}...{% endcache %. Fragment caching for expensive templa… def _compile_cache(self, node: Any) -> list[ast.stmt] Compile {% cache key %}...{% endcache %. Fragment caching for expensive template sections. Generates: _cache_key = str(key) _cached = _cache_get(_cache_key) if _cached is not None: _append(_cached) else: _cache_buf = [] _cache_append = _cache_buf.append _save_append = _append _append = _cache_append ... body ... _append = _save_append _cached = ''.join(_cache_buf) _cache_set(_cache_key, _cached, ttl) _append(_cached) Parameters Name Type Description node — Returns list[ast.stmt] _compile_filter_block 1 list[ast.stmt] ▼ Compile {% filter name %}...{% endfilter %. Apply a filter to an entire block … def _compile_filter_block(self, node: Any) -> list[ast.stmt] Compile {% filter name %}...{% endfilter %. Apply a filter to an entire block of content. Uses unique variable names to support nesting. Generates: _filter_buf_N = [] _filter_append_N = _filter_buf_N.append _save_append_N = _append _append = _filter_append_N ... body ... _append = _save_append_N _append(_filters['name'](''.join(_filter_buf_N), *args, **kwargs)) Parameters Name Type Description node — Returns list[ast.stmt] _compile_spaceless 1 list[ast.stmt] ▼ Compile {% spaceless %}...{% end %}. Removes whitespace between HTML tags. Par… def _compile_spaceless(self, node: Any) -> list[ast.stmt] Compile {% spaceless %}...{% end %}. Removes whitespace between HTML tags. Part of RFC: kida-modern-syntax-features. Generates: _spaceless_buf_N = [] _spaceless_append_N = _spaceless_buf_N.append _save_append_N = _append _append = _spaceless_append_N ... body ... _append = _save_append_N _append(_spaceless(''.join(_spaceless_buf_N))) 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: Any) -> 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] ← Previous functions Next → statements List © 2026 Kida built in ᓚᘏᗢ { "linkPreviews": { "enabled": true, "hoverDelay": 200, "hideDelay": 150, "showSection": true, "showReadingTime": true, "showWordCount": true, "showDate": true, "showTags": true, "maxTags": 3, "includeSelectors": [".prose"], "excludeSelectors": ["nav", ".toc", ".breadcrumb", ".pagination", ".card", "[class*='-card']", ".tab-nav", "[class*='-widget']", ".child-items", ".content-tiles"], "allowedHosts": [], "allowedSchemes": ["https"], "hostFailureThreshold": 3 } } window.BENGAL_LAZY_ASSETS = { tabulator: '/kida/assets/js/tabulator.min.js', dataTable: '/kida/assets/js/data-table.js', mermaidToolbar: '/kida/assets/js/mermaid-toolbar.9de5abba.js', mermaidTheme: '/kida/assets/js/mermaid-theme.344822c5.js', graphMinimap: '/kida/assets/js/graph-minimap.ff04e939.js', graphContextual: '/kida/assets/js/graph-contextual.355458ba.js' }; window.BENGAL_ICONS = { close: '/kida/assets/icons/close.911d4fe1.svg', enlarge: '/kida/assets/icons/enlarge.652035e5.svg', copy: '/kida/assets/icons/copy.3d56e945.svg', 'download-svg': '/kida/assets/icons/download.04f07e1b.svg', 'download-png': '/kida/assets/icons/image.c34dfd40.svg', 'zoom-in': '/kida/assets/icons/zoom-in.237b4a83.svg', 'zoom-out': '/kida/assets/icons/zoom-out.38857c77.svg', reset: '/kida/assets/icons/reset.d26dba29.svg' }; Arrow Up -------------------------------------------------------------------------------- Metadata: - Word Count: 1112 - Reading Time: 6 minutes