# core

URL: /kida/api/parser/core/
Section: parser
Description: Core parser implementation for Kida.

Combines all parsing mixins into a unified Parser class that transforms
a token stream into an immutable Kida AST (Template node).

Design:
The Parser uses mixin inheritance to separate concerns while maintaining
a single entry point. Each mixin handles one aspect of the grammar:

- `TokenNavigationMixin`: Token stream access, lookahead, expect/match
- `BlockParsingMixin`: Template structure (block, extends, include, def)
- `StatementParsingMixin`: Control flow (if, for, while), variables (set, let)
- `ExpressionParsingMixin`: Expressions, operators, filters, tests

Block Stack:
Uses a stack-based approach for unified `{% end %}` syntax. When any block
is opened, it's pushed onto the stack. `{% end %}` always closes the
innermost open block, like Go templates.

Thread-Safety:
Parser instances are single-use and not thread-safe. Create one parser
per template compilation. The resulting AST is immutable and thread-safe.

---

> For a complete page index, fetch /kida/llms.txt.

Open LLM text
(/kida/api/parser/core/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fparser%2Fcore%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fparser%2Fcore%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fparser%2Fcore%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fkida%2Fapi%2Fparser%2Fcore%2Findex.txt)

Module

#
`parser.core`

Core parser implementation for Kida.

Combines all parsing mixins into a unified Parser class that transforms
a token stream into an immutable Kida AST (Template node).

Design:

The Parser uses mixin inheritance to separate concerns while maintaining
a single entry point. Each mixin handles one aspect of the grammar:

- `TokenNavigationMixin`: Token stream access, lookahead, expect/match

- `BlockParsingMixin`: Template structure (block, extends, include, def)

- `StatementParsingMixin`: Control flow (if, for, while), variables (set, let)

- `ExpressionParsingMixin`: Expressions, operators, filters, tests

Block Stack:

Uses a stack-based approach for unified`{% end %}`syntax. When any block
is opened, it's pushed onto the stack.`{% end %}`always closes the
innermost open block, like Go templates.

Thread-Safety:
Parser instances are single-use and not thread-safe. Create one parser
per template compilation. The resulting AST is immutable and thread-safe.

1Class

## Classes

`Parser`

9

▼

Recursive descent parser transforming tokens into Kida AST.

The Parser consumes a token stream and…

Recursive descent parser transforming tokens into Kida AST.

The Parser consumes a token stream and produces an immutable Template node
representing the complete AST. All parsing state is instance-local, so
parsers are single-use (create one per template).

Block Stack Architecture:
Uses a stack to track open blocks, enabling Kida's unified`{% end %}`
syntax. When`{% end %}`is encountered, it closes the innermost block:

```
    ```jinja
    {% if condition %}
        {% for item in items %}
            {{ item }}
        {% end %}  {# closes for #}
    {% end %}  {# closes if #}
```

The stack stores `(block_type, lineno, col)` tuples for error reporting.
```

Error Handling:
Parse errors include source snippets with caret pointing to the error,
plus contextual suggestions for common mistakes:


```
```
    ParseError: Unclosed 'for' block - missing closing tag
      --> template.html:3:0
       |
     3 | {% for item in items %}
       | ^
    Suggestion: Add '{% end %}' or '{% endfor %}' to close the block
```
```






#### Attributes




        Name
        Type
        Description





        `_tokens`

  —




Sequence of Token objects from lexer






  `_pos`

  —




Current position in token stream






  `_name`

  —




Template name for error messages






  `_filename`

  —




Source file path for error messages






  `_source`

  —




Original source text for error context






  `_autoescape`

  —




Whether to auto-escape output expressions






  `_block_stack`

              `list[tuple[str, int, int]]`




Stack of open blocks for`{% end %}`matching











#### Methods

















        `parse`

0


          `Template`


▼


Parse tokens into Template AST.









      `def parse(self) -> Template`




##### Returns

      `Template`











      Internal Methods
      1

    ▼













        `__init__`

6

▼










      `def __init__(self, tokens: Sequence[Token], name: str | None = None, filename: str | None = None, source: str | None = None, autoescape: bool = True, extension_tags: dict | None = None)`




##### Parameters




        Name
        Type
        Description





        `tokens`
`—`






  `name`
`—`


  Default:`None`





  `filename`
`—`


  Default:`None`





  `source`
`—`


  Default:`None`





  `autoescape`
`—`


  Default:`True`





  `extension_tags`
`—`


  Default:`None`