quantum-framework 0.9.0__py3-none-any.whl

quantum/core/parsers/base.py

@@ -0,0 +1,322 @@
+"""
+Base Tag Parser - Abstract base class for all tag parsers
+
+All parsers inherit from BaseTagParser and implement the parse() method.
+The ParserRegistry uses the 'tag_names' property to dispatch parsing to the correct parser.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional, TYPE_CHECKING
+from xml.etree import ElementTree as ET
+
+if TYPE_CHECKING:
+    from quantum.core.ast_nodes import QuantumNode
+
+
+class ParserError(Exception):
+    """Base exception for parser errors"""
+    pass
+
+
+class BaseTagParser(ABC):
+    """
+    Abstract base class for tag-specific parsers.
+
+    Each parser handles one or more XML tags and implements
+    the parse() method to convert them to AST nodes.
+
+    Example:
+        class LoopParser(BaseTagParser):
+            @property
+            def tag_names(self) -> List[str]:
+                return ['loop']
+
+            def parse(self, element: ET.Element) -> LoopNode:
+                # Parse loop element
+                pass
+    """
+
+    def __init__(self, main_parser: 'QuantumParser'):
+        """
+        Initialize parser with reference to main parser.
+
+        Args:
+            main_parser: The QuantumParser instance (provides helpers and registry)
+        """
+        self._parser = main_parser
+
+    @property
+    def parser(self) -> 'QuantumParser':
+        """Access to the main parser"""
+        return self._parser
+
+    @property
+    @abstractmethod
+    def tag_names(self) -> List[str]:
+        """
+        List of tag names this parser handles (without q: prefix).
+
+        Returns:
+            List of tag names (e.g., ['loop', 'for', 'while'])
+        """
+        pass
+
+    @abstractmethod
+    def parse(self, element: ET.Element) -> 'QuantumNode':
+        """
+        Parse the element and return AST node.
+
+        Args:
+            element: XML element to parse
+
+        Returns:
+            AST node representing the element
+        """
+        pass
+
+    # ==========================================================================
+    # Helper methods - Common utilities available to all parsers
+    # ==========================================================================
+
+    def get_element_name(self, element: ET.Element) -> str:
+        """
+        Get element name without namespace prefix.
+
+        Args:
+            element: XML element
+
+        Returns:
+            Tag name without namespace
+        """
+        return self._parser._get_element_name(element)
+
+    def find_element(self, parent: ET.Element, tag: str) -> Optional[ET.Element]:
+        """
+        Find a child element by tag name.
+
+        Args:
+            parent: Parent element
+            tag: Tag name to find
+
+        Returns:
+            Element or None
+        """
+        return self._parser._find_element(parent, tag)
+
+    def find_all_elements(self, parent: ET.Element, tag: str) -> List[ET.Element]:
+        """
+        Find all child elements by tag name.
+
+        Args:
+            parent: Parent element
+            tag: Tag name to find
+
+        Returns:
+            List of elements
+        """
+        return self._parser._find_all_elements(parent, tag)
+
+    def parse_statement(self, element: ET.Element) -> Optional['QuantumNode']:
+        """
+        Parse a child statement using the registry.
+
+        Args:
+            element: Child element to parse
+
+        Returns:
+            AST node or None
+        """
+        return self._parser._parse_statement(element)
+
+    def parse_statements(self, parent: ET.Element) -> List['QuantumNode']:
+        """
+        Parse all direct children as statements.
+
+        Args:
+            parent: Parent element
+
+        Returns:
+            List of AST nodes
+        """
+        from quantum.core.features.conditionals.src.ast_node import IfNode
+
+        statements = []
+        for child in parent:
+            nome = self.get_element_name(child)
+
+            # `<q:else>` / `<q:elseif>` como IRMAO de `<q:if>`.
+            #
+            # A forma que funcionava era so a ANINHADA (o else dentro do if);
+            # a irma — `</q:if>` e depois `<q:else>` — nao tinha parser
+            # registrado (IfParser.tag_names = ['if']), caia no fallback e
+            # era DESCARTADA sem uma palavra. A documentacao ensinava a forma
+            # irma em dezenas de exemplos (inclusive o passo 3 do quick-start)
+            # e 7 arquivos .q entregues a usavam, entao o else simplesmente
+            # nao acontecia e ninguem era avisado.
+            #
+            # Agora um else/elseif que segue um q:if e anexado a ele — as duas
+            # formas passam a significar a mesma coisa. Um else/elseif SEM um
+            # if antes e um erro de verdade, e agora e dito em voz alta.
+            if nome in ('else', 'elseif'):
+                anterior = statements[-1] if statements else None
+                if isinstance(anterior, IfNode):
+                    self._attach_else_branch(anterior, nome, child)
+                    continue
+                from quantum.core.parser import QuantumParseError
+                raise QuantumParseError(
+                    f"<q:{nome}> has no matching <q:if> before it. "
+                    f"Put it inside the if, or right after it: "
+                    f"<q:if ...>...</q:if> <q:{nome}>...</q:{nome}>"
+                )
+
+            node = self.parse_statement(child)
+            if node is not None:
+                statements.append(node)
+        return statements
+
+    def _attach_else_branch(self, if_node, kind: str, element: 'ET.Element'):
+        """Anexa um else/elseif IRMAO ao IfNode anterior — mesmo resultado do
+        aninhado, que o IfParser ja monta com estes mesmos metodos."""
+        if kind == 'elseif':
+            condicao = self.get_attr(element, 'condition', '')
+            corpo = []
+            for filho in element:
+                stmt = self.parse_statement(filho)
+                if stmt:
+                    corpo.append(stmt)
+            if_node.add_elseif_block(condicao, corpo)
+        else:
+            for filho in element:
+                stmt = self.parse_statement(filho)
+                if stmt:
+                    if_node.add_else_statement(stmt)
+
+    def get_attr(self, element: ET.Element, name: str, default: str = None) -> Optional[str]:
+        """
+        Get element attribute with optional default.
+
+        Args:
+            element: XML element
+            name: Attribute name
+            default: Default value
+
+        Returns:
+            Attribute value or default
+        """
+        return element.get(name, default)
+
+    def get_bool_attr(self, element: ET.Element, name: str, default: bool = False) -> bool:
+        """
+        Get boolean attribute.
+
+        Args:
+            element: XML element
+            name: Attribute name
+            default: Default value
+
+        Returns:
+            Boolean value
+        """
+        value = element.get(name, '').lower()
+        if value in ('true', '1', 'yes'):
+            return True
+        if value in ('false', '0', 'no'):
+            return False
+        return default
+
+    def get_int_attr(self, element: ET.Element, name: str, default: int = 0) -> int:
+        """
+        Get integer attribute.
+
+        Args:
+            element: XML element
+            name: Attribute name
+            default: Default value
+
+        Returns:
+            Integer value
+        """
+        try:
+            return int(element.get(name, default))
+        except (ValueError, TypeError):
+            return default
+
+    def get_text(self, element: ET.Element) -> str:
+        """
+        Get element text content.
+
+        Args:
+            element: XML element
+
+        Returns:
+            Text content (empty string if None)
+        """
+        return element.text or ''
+
+    def require_attr(self, element: ET.Element, name: str) -> str:
+        """
+        Get required attribute, raise error if missing.
+
+        Args:
+            element: XML element
+            name: Attribute name
+
+        Returns:
+            Attribute value
+
+        Raises:
+            ParserError: If attribute is missing
+        """
+        value = element.get(name)
+        if value is None:
+            tag = self.get_element_name(element)
+            raise ParserError(f"<q:{tag}> requires '{name}' attribute")
+        return value
+
+    def is_html_element(self, element: ET.Element) -> bool:
+        """
+        Check if element is an HTML element.
+
+        Args:
+            element: XML element
+
+        Returns:
+            True if HTML element
+        """
+        return self._parser._is_html_element(element)
+
+    def parse_param(self, element: ET.Element) -> 'QuantumParam':
+        """
+        Parse a q:param element.
+
+        Args:
+            element: Param element
+
+        Returns:
+            QuantumParam node
+        """
+        return self._parser._parse_param(element)
+
+    def parse_child(self, element: ET.Element) -> Optional['QuantumNode']:
+        """
+        Alias for parse_statement. Parse a child element using the registry.
+
+        Args:
+            element: Child element to parse
+
+        Returns:
+            AST node or None
+        """
+        return self.parse_statement(element)
+
+    def _get_element_name(self, element: ET.Element) -> str:
+        """
+        Alias for get_element_name. Get element name without namespace prefix.
+
+        Args:
+            element: XML element
+
+        Returns:
+            Tag name without namespace
+        """
+        return self.get_element_name(element)

quantum/core/parsers/composition/__init__.py

@@ -0,0 +1,10 @@
+"""
+Component Composition Parsers
+
+Parsers for component composition tags: import, slot
+"""
+
+from .import_parser import ImportParser
+from .slot_parser import SlotParser
+
+__all__ = ['ImportParser', 'SlotParser']

quantum/core/parsers/composition/import_parser.py

@@ -0,0 +1,50 @@
+"""
+Import Parser - Parse q:import statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import ImportNode
+
+
+class ImportParser(BaseTagParser):
+    """
+    Parser for q:import statements.
+
+    Examples:
+        <q:import component="Header" />
+        <q:import component="Button" from="./ui" />
+        <q:import component="AdminLayout" as="Layout" />
+
+    Game Engine Imports:
+        <q:import behavior="PlayerBehavior" from="./behaviors" />
+        <q:import prefab="KoopaGreen" from="./prefabs" />
+        <q:import tilemap="yi1" from="./levels" />
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['import']
+
+    def parse(self, element: ET.Element) -> ImportNode:
+        """Parse q:import element"""
+        component = element.get('component')
+        behavior = element.get('behavior')
+        prefab = element.get('prefab')
+        tilemap = element.get('tilemap')
+        from_path = element.get('from')
+        alias = element.get('as')
+
+        if not component and not behavior and not prefab and not tilemap:
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError("q:import requires one of 'component', 'behavior', 'prefab', or 'tilemap' attribute")
+
+        return ImportNode(
+            component=component,
+            from_path=from_path,
+            alias=alias,
+            behavior=behavior,
+            prefab=prefab,
+            tilemap=tilemap
+        )

quantum/core/parsers/composition/slot_parser.py

@@ -0,0 +1,48 @@
+"""
+Slot Parser - Parse q:slot statements
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.ast_nodes import SlotNode, TextNode
+
+
+class SlotParser(BaseTagParser):
+    """
+    Parser for q:slot statements.
+
+    Examples:
+        <q:slot />  <!-- Default slot -->
+        <q:slot name="header" />
+        <q:slot name="footer">
+            <p>Default footer content</p>
+        </q:slot>
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['slot']
+
+    def parse(self, element: ET.Element) -> SlotNode:
+        """Parse q:slot element"""
+        name = element.get('name', 'default')
+
+        # Parse default content (children of slot)
+        default_content = []
+
+        if element.text and element.text.strip():
+            default_content.append(TextNode(element.text))
+
+        for child in element:
+            child_node = self.parse_child(child)
+            if child_node:
+                default_content.append(child_node)
+
+            if child.tail and child.tail.strip():
+                default_content.append(TextNode(child.tail))
+
+        return SlotNode(
+            name=name,
+            default_content=default_content
+        )

quantum/core/parsers/control_flow/__init__.py

@@ -0,0 +1,11 @@
+"""
+Control Flow Parsers
+
+Parsers for control flow statements: if, loop, set.
+"""
+
+from .if_parser import IfParser
+from .loop_parser import LoopParser
+from .set_parser import SetParser
+
+__all__ = ['IfParser', 'LoopParser', 'SetParser']

quantum/core/parsers/control_flow/if_parser.py

@@ -0,0 +1,68 @@
+"""
+If Parser - Parse q:if statements
+
+Handles conditional statements with elseif and else blocks.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser
+from quantum.core.features.conditionals.src.ast_node import IfNode
+
+
+class IfParser(BaseTagParser):
+    """
+    Parser for q:if statements.
+
+    Supports:
+    - Simple if conditions
+    - Multiple elseif blocks
+    - Optional else block
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['if']
+
+    def parse(self, element: ET.Element) -> IfNode:
+        """
+        Parse q:if statement with elseif and else blocks.
+
+        Args:
+            element: XML element for q:if
+
+        Returns:
+            IfNode AST node
+        """
+        condition = self.get_attr(element, 'condition', '')
+        if_node = IfNode(condition)
+
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'elseif':
+                # Parse elseif block
+                elseif_condition = self.get_attr(child, 'condition', '')
+                elseif_body = []
+
+                for elseif_child in child:
+                    statement = self.parse_statement(elseif_child)
+                    if statement:
+                        elseif_body.append(statement)
+
+                if_node.add_elseif_block(elseif_condition, elseif_body)
+
+            elif child_type == 'else':
+                # Parse else block
+                for else_child in child:
+                    statement = self.parse_statement(else_child)
+                    if statement:
+                        if_node.add_else_statement(statement)
+
+            else:
+                # Main if block statement
+                statement = self.parse_statement(child)
+                if statement:
+                    if_node.add_if_statement(statement)
+
+        return if_node

quantum/core/parsers/control_flow/loop_parser.py

@@ -0,0 +1,105 @@
+"""
+Loop Parser - Parse q:loop statements
+
+Handles various loop types: range, array, list, query.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.loops.src.ast_node import LoopNode
+from quantum.core.ast_nodes import TextNode
+
+
+class LoopParser(BaseTagParser):
+    """
+    Parser for q:loop statements.
+
+    Supports:
+    - Range loops (from/to)
+    - Array iteration
+    - List iteration (with delimiter)
+    - Query result iteration
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['loop']
+
+    def parse(self, element: ET.Element) -> LoopNode:
+        """
+        Parse q:loop statement with various types.
+
+        Args:
+            element: XML element for q:loop
+
+        Returns:
+            LoopNode AST node
+        """
+        # Check for query attribute (shorthand syntax)
+        query_attr = self.get_attr(element, 'query')
+
+        if query_attr:
+            # <q:loop query="users"> shorthand: the query name doubles as the
+            # row variable, so the body reads {users.name}.
+            #
+            # `var=` is honoured here when given. It used to be read only in
+            # the branch below, so <q:loop query="projects" var="p"> silently
+            # discarded the name and {p.name} rendered as literal text with no
+            # error anywhere — found by writing a real screen against it
+            # (FRAMEWORK_PLAN.md Fase 4). Omitting var= keeps the old
+            # behaviour exactly.
+            loop_type = 'query'
+            var_name = self.get_attr(element, 'var') or query_attr
+            loop_node = LoopNode(loop_type, var_name)
+            loop_node.query_name = query_attr
+        else:
+            # Traditional syntax
+            loop_type = self.get_attr(element, 'type')
+            if not loop_type:
+                # No explicit type: infer from attributes present instead of
+                # always defaulting to 'range'. A bare <q:loop items="..."
+                # var="..."> with no type= used to be misclassified as a range
+                # loop and fail validation ("Range loop requires 'from'
+                # attribute") — confirmed breaking examples in multiple
+                # unrelated features (agents, data_import, scripting).
+                loop_type = 'array' if self.get_attr(element, 'items') else 'range'
+            var_name = self.get_attr(element, 'var')
+
+            if not var_name:
+                raise ParserError("Loop requires 'var' attribute")
+
+            loop_node = LoopNode(loop_type, var_name)
+
+        # Configure based on loop type
+        if loop_type == 'range':
+            loop_node.from_value = self.get_attr(element, 'from')
+            loop_node.to_value = self.get_attr(element, 'to')
+            loop_node.step_value = self.get_int_attr(element, 'step', 1)
+
+        elif loop_type == 'array':
+            loop_node.items = self.get_attr(element, 'items')
+            loop_node.index_name = self.get_attr(element, 'index')
+
+        elif loop_type == 'list':
+            loop_node.items = self.get_attr(element, 'items')
+            loop_node.delimiter = self.get_attr(element, 'delimiter', ',')
+            loop_node.index_name = self.get_attr(element, 'index')
+
+        elif loop_type == 'query':
+            loop_node.index_name = self.get_attr(element, 'index')
+
+        # Parse loop body - add text content before first child
+        if element.text and element.text.strip():
+            loop_node.add_statement(TextNode(element.text))
+
+        # Parse loop body statements
+        for child in element:
+            statement = self.parse_statement(child)
+            if statement:
+                loop_node.add_statement(statement)
+            # Add tail text after child element
+            if child.tail and child.tail.strip():
+                loop_node.add_statement(TextNode(child.tail))
+
+        return loop_node