flowquery 1.0.16 → 1.0.17

package/flowquery-py/src/parsing/base_parser.py

@@ -0,0 +1,84 @@
+"""Base class for parsers providing common token manipulation functionality."""
+
+from typing import List, Optional
+
+from ..tokenization.token import Token
+from ..tokenization.tokenizer import Tokenizer
+
+
+class BaseParser:
+    """Base class for parsers providing common token manipulation functionality.
+    
+    This class handles tokenization and provides utility methods for navigating
+    through tokens, peeking ahead, and checking token sequences.
+    """
+
+    def __init__(self, tokens: Optional[List[Token]] = None):
+        self._tokens: List[Token] = tokens or []
+        self._token_index: int = 0
+
+    def tokenize(self, statement: str) -> None:
+        """Tokenizes a statement and initializes the token array.
+        
+        Args:
+            statement: The input statement to tokenize
+        """
+        self._tokens = Tokenizer(statement).tokenize()
+        self._token_index = 0
+
+    def set_next_token(self) -> None:
+        """Advances to the next token in the sequence."""
+        self._token_index += 1
+
+    def peek(self) -> Optional[Token]:
+        """Peeks at the next token without advancing the current position.
+        
+        Returns:
+            The next token, or None if at the end of the token stream
+        """
+        if self._token_index + 1 >= len(self._tokens):
+            return None
+        return self._tokens[self._token_index + 1]
+
+    def ahead(self, tokens: List[Token], skip_whitespace_and_comments: bool = True) -> bool:
+        """Checks if a sequence of tokens appears ahead in the token stream.
+        
+        Args:
+            tokens: The sequence of tokens to look for
+            skip_whitespace_and_comments: Whether to skip whitespace and comments when matching
+            
+        Returns:
+            True if the token sequence is found ahead, False otherwise
+        """
+        j = 0
+        for i in range(self._token_index, len(self._tokens)):
+            if skip_whitespace_and_comments and self._tokens[i].is_whitespace_or_comment():
+                continue
+            if not self._tokens[i].equals(tokens[j]):
+                return False
+            j += 1
+            if j == len(tokens):
+                break
+        return j == len(tokens)
+
+    @property
+    def token(self) -> Token:
+        """Gets the current token.
+        
+        Returns:
+            The current token, or EOF if at the end
+        """
+        if self._token_index >= len(self._tokens):
+            return Token.EOF
+        return self._tokens[self._token_index]
+
+    @property
+    def previous_token(self) -> Token:
+        """Gets the previous token.
+        
+        Returns:
+            The previous token, or EOF if at the beginning
+        """
+        if self._token_index - 1 < 0:
+            return Token.EOF
+        return self._tokens[self._token_index - 1]

package/flowquery-py/src/parsing/components/__init__.py

@@ -0,0 +1,19 @@
+"""Components module for FlowQuery parsing."""
+
+from .csv import CSV
+from .json import JSON
+from .text import Text
+from .from_ import From
+from .headers import Headers
+from .post import Post
+from .null import Null
+
+__all__ = [
+    "CSV",
+    "JSON",
+    "Text",
+    "From",
+    "Headers",
+    "Post",
+    "Null",
+]

package/flowquery-py/src/parsing/components/csv.py

@@ -0,0 +1,8 @@
+"""CSV component node."""
+
+from ..ast_node import ASTNode
+
+
+class CSV(ASTNode):
+    """Represents a CSV data type marker in LOAD operations."""
+    pass

package/flowquery-py/src/parsing/components/from_.py

@@ -0,0 +1,10 @@
+"""From component node."""
+
+from ..ast_node import ASTNode
+
+
+class From(ASTNode):
+    """Represents a FROM clause in LOAD operations."""
+
+    def value(self) -> str:
+        return self.children[0].value()

package/flowquery-py/src/parsing/components/headers.py

@@ -0,0 +1,12 @@
+"""Headers component node."""
+
+from typing import Dict
+
+from ..ast_node import ASTNode
+
+
+class Headers(ASTNode):
+    """Represents a HEADERS clause in LOAD operations."""
+
+    def value(self) -> Dict:
+        return self.first_child().value() or {}

package/flowquery-py/src/parsing/components/json.py

@@ -0,0 +1,8 @@
+"""JSON component node."""
+
+from ..ast_node import ASTNode
+
+
+class JSON(ASTNode):
+    """Represents a JSON data type marker in LOAD operations."""
+    pass

package/flowquery-py/src/parsing/components/null.py

@@ -0,0 +1,10 @@
+"""Null component node."""
+
+from ..ast_node import ASTNode
+
+
+class Null(ASTNode):
+    """Represents a NULL value in the AST."""
+    
+    def value(self):
+        return None

package/flowquery-py/src/parsing/components/post.py

@@ -0,0 +1,8 @@
+"""Post component node."""
+
+from ..ast_node import ASTNode
+
+
+class Post(ASTNode):
+    """Represents a POST clause in LOAD operations."""
+    pass

package/flowquery-py/src/parsing/components/text.py

@@ -0,0 +1,8 @@
+"""Text component node."""
+
+from ..ast_node import ASTNode
+
+
+class Text(ASTNode):
+    """Represents a Text data type marker in LOAD operations."""
+    pass

package/flowquery-py/src/parsing/context.py

@@ -0,0 +1,50 @@
+"""Maintains a stack of AST nodes to track parsing context."""
+
+from typing import List, Optional, Type
+
+from .ast_node import ASTNode
+
+
+class Context:
+    """Maintains a stack of AST nodes to track parsing context.
+    
+    Used during parsing to maintain the current context and check for specific node types
+    in the parsing hierarchy, which helps with context-sensitive parsing decisions.
+    
+    Example:
+        context = Context()
+        context.push(node)
+        has_return = context.contains_type(Return)
+    """
+
+    def __init__(self):
+        self._nodes: List[ASTNode] = []
+
+    def push(self, node: ASTNode) -> None:
+        """Pushes a node onto the context stack.
+        
+        Args:
+            node: The AST node to push
+        """
+        self._nodes.append(node)
+
+    def pop(self) -> Optional[ASTNode]:
+        """Pops the top node from the context stack.
+        
+        Returns:
+            The popped node, or None if the stack is empty
+        """
+        if len(self._nodes) == 0:
+            return None
+        return self._nodes.pop()
+
+    def contains_type(self, type_: Type[ASTNode]) -> bool:
+        """Checks if the nodes stack contains a node of the specified type.
+        
+        Args:
+            type_: The class of the node type to search for
+            
+        Returns:
+            True if a node of the specified type is found in the stack, False otherwise
+        """
+        return any(isinstance(v, type_) for v in self._nodes)

package/flowquery-py/src/parsing/data_structures/__init__.py

@@ -0,0 +1,15 @@
+"""Data structures module for FlowQuery parsing."""
+
+from .associative_array import AssociativeArray
+from .json_array import JSONArray
+from .key_value_pair import KeyValuePair
+from .lookup import Lookup
+from .range_lookup import RangeLookup
+
+__all__ = [
+    "AssociativeArray",
+    "JSONArray",
+    "KeyValuePair",
+    "Lookup",
+    "RangeLookup",
+]

package/flowquery-py/src/parsing/data_structures/associative_array.py

@@ -0,0 +1,41 @@
+"""Represents an associative array (object/dictionary) in the AST."""
+
+from typing import Any, Dict
+
+from ..ast_node import ASTNode
+from .key_value_pair import KeyValuePair
+
+
+class AssociativeArray(ASTNode):
+    """Represents an associative array (object/dictionary) in the AST.
+    
+    Associative arrays map string keys to values, similar to JSON objects.
+    
+    Example:
+        # For { name: "Alice", age: 30 }
+        obj = AssociativeArray()
+        obj.add_key_value(KeyValuePair("name", name_expr))
+        obj.add_key_value(KeyValuePair("age", age_expr))
+    """
+
+    def add_key_value(self, key_value_pair: KeyValuePair) -> None:
+        """Adds a key-value pair to the associative array.
+        
+        Args:
+            key_value_pair: The key-value pair to add
+        """
+        self.add_child(key_value_pair)
+
+    def __str__(self) -> str:
+        return 'AssociativeArray'
+
+    def _value(self):
+        for child in self.children:
+            key_value = child
+            yield {key_value.key: key_value._value}
+
+    def value(self) -> Dict[str, Any]:
+        result = {}
+        for item in self._value():
+            result.update(item)
+        return result

package/flowquery-py/src/parsing/data_structures/json_array.py

@@ -0,0 +1,30 @@
+"""Represents a JSON array in the AST."""
+
+from typing import Any, List
+
+from ..ast_node import ASTNode
+
+
+class JSONArray(ASTNode):
+    """Represents a JSON array in the AST.
+    
+    JSON arrays are ordered collections of values.
+    
+    Example:
+        # For [1, 2, 3]
+        arr = JSONArray()
+        arr.add_value(Number("1"))
+        arr.add_value(Number("2"))
+        arr.add_value(Number("3"))
+    """
+
+    def add_value(self, value: ASTNode) -> None:
+        """Adds a value to the array.
+        
+        Args:
+            value: The AST node representing the value to add
+        """
+        self.add_child(value)
+
+    def value(self) -> List[Any]:
+        return [child.value() for child in self.children]

package/flowquery-py/src/parsing/data_structures/key_value_pair.py

@@ -0,0 +1,38 @@
+"""Represents a key-value pair in an associative array."""
+
+from typing import Any
+
+from ..ast_node import ASTNode
+from ..expressions.string import String
+
+
+class KeyValuePair(ASTNode):
+    """Represents a key-value pair in an associative array.
+    
+    Used to build object literals in FlowQuery.
+    
+    Example:
+        kvp = KeyValuePair("name", String("Alice"))
+    """
+
+    def __init__(self, key: str, value: ASTNode):
+        """Creates a new key-value pair.
+        
+        Args:
+            key: The key string
+            value: The AST node representing the value
+        """
+        super().__init__()
+        self.add_child(String(key))
+        self.add_child(value)
+
+    @property
+    def key(self) -> str:
+        return self.children[0].value()
+
+    @property
+    def _value(self) -> Any:
+        return self.children[1].value()
+
+    def __str__(self) -> str:
+        return "KeyValuePair"

package/flowquery-py/src/parsing/data_structures/lookup.py

@@ -0,0 +1,49 @@
+"""Represents a lookup operation (array/object indexing) in the AST."""
+
+from typing import Any
+
+from ..ast_node import ASTNode
+
+
+class Lookup(ASTNode):
+    """Represents a lookup operation (array/object indexing) in the AST.
+    
+    Lookups access elements from arrays or properties from objects using an index or key.
+    
+    Example:
+        # For array[0] or obj.property or obj["key"]
+        lookup = Lookup()
+        lookup.variable = array_or_obj_node
+        lookup.index = index_node
+    """
+
+    @property
+    def index(self) -> ASTNode:
+        return self.children[0]
+
+    @index.setter
+    def index(self, index: ASTNode) -> None:
+        self.add_child(index)
+
+    @property
+    def variable(self) -> ASTNode:
+        return self.children[1]
+
+    @variable.setter
+    def variable(self, variable: ASTNode) -> None:
+        self.add_child(variable)
+
+    def is_operand(self) -> bool:
+        return True
+
+    def value(self) -> Any:
+        obj = self.variable.value()
+        key = self.index.value()
+        # Try dict-like access first, then fall back to attribute access for objects
+        try:
+            return obj[key]
+        except (TypeError, KeyError):
+            # For objects with attributes (like dataclasses), use getattr
+            if hasattr(obj, key):
+                return getattr(obj, key)
+            raise

package/flowquery-py/src/parsing/data_structures/range_lookup.py

@@ -0,0 +1,42 @@
+"""Represents a range lookup operation in the AST."""
+
+from typing import Any, List
+
+from ..ast_node import ASTNode
+
+
+class RangeLookup(ASTNode):
+    """Represents a range lookup (array slicing) operation in the AST."""
+
+    @property
+    def from_(self) -> ASTNode:
+        return self.children[0]
+
+    @from_.setter
+    def from_(self, from_: ASTNode) -> None:
+        self.add_child(from_)
+
+    @property
+    def to(self) -> ASTNode:
+        return self.children[1]
+
+    @to.setter
+    def to(self, to: ASTNode) -> None:
+        self.add_child(to)
+
+    @property
+    def variable(self) -> ASTNode:
+        return self.children[2]
+
+    @variable.setter
+    def variable(self, variable: ASTNode) -> None:
+        self.add_child(variable)
+
+    def is_operand(self) -> bool:
+        return True
+
+    def value(self) -> List[Any]:
+        array = self.variable.value()
+        from_val = self.from_.value() or 0
+        to_val = self.to.value() or len(array)
+        return array[from_val:to_val]

package/flowquery-py/src/parsing/expressions/__init__.py

@@ -0,0 +1,57 @@
+"""Expressions module for FlowQuery parsing."""
+
+from .expression import Expression
+from .boolean import Boolean
+from .number import Number
+from .string import String
+from .identifier import Identifier
+from .reference import Reference
+from .f_string import FString
+from .expression_map import ExpressionMap
+from .operator import (
+    Operator,
+    Add,
+    Subtract,
+    Multiply,
+    Divide,
+    Modulo,
+    Power,
+    Equals,
+    NotEquals,
+    GreaterThan,
+    LessThan,
+    GreaterThanOrEqual,
+    LessThanOrEqual,
+    And,
+    Or,
+    Not,
+    Is,
+)
+
+__all__ = [
+    "Expression",
+    "Boolean",
+    "Number",
+    "String",
+    "Identifier",
+    "Reference",
+    "FString",
+    "ExpressionMap",
+    "Operator",
+    "Add",
+    "Subtract",
+    "Multiply",
+    "Divide",
+    "Modulo",
+    "Power",
+    "Equals",
+    "NotEquals",
+    "GreaterThan",
+    "LessThan",
+    "GreaterThanOrEqual",
+    "LessThanOrEqual",
+    "And",
+    "Or",
+    "Not",
+    "Is",
+]

package/flowquery-py/src/parsing/expressions/boolean.py

@@ -0,0 +1,20 @@
+"""Represents a boolean literal in the AST."""
+
+from ..ast_node import ASTNode
+
+
+class Boolean(ASTNode):
+    """Represents a boolean literal in the AST."""
+
+    def __init__(self, value: str):
+        super().__init__()
+        _value = value.upper()
+        if _value == "TRUE":
+            self._value = True
+        elif _value == "FALSE":
+            self._value = False
+        else:
+            raise ValueError(f"Invalid boolean value: {value}")
+
+    def value(self) -> bool:
+        return self._value

package/flowquery-py/src/parsing/expressions/expression.py

@@ -0,0 +1,138 @@
+"""Represents an expression in the FlowQuery AST."""
+
+from typing import Any, List, Optional, Generator, TYPE_CHECKING
+
+from ..ast_node import ASTNode
+
+if TYPE_CHECKING:
+    from ..functions.aggregate_function import AggregateFunction
+    from ...graph.pattern_expression import PatternExpression
+
+
+class Expression(ASTNode):
+    """Represents an expression in the FlowQuery AST.
+    
+    Expressions are built using the Shunting Yard algorithm to handle operator
+    precedence and associativity. They can contain operands (numbers, strings, identifiers)
+    and operators (arithmetic, logical, comparison).
+    
+    Example:
+        expr = Expression()
+        expr.add_node(number_node)
+        expr.add_node(plus_operator)
+        expr.add_node(another_number_node)
+        expr.finish()
+    """
+
+    def __init__(self):
+        super().__init__()
+        self._operators: List[ASTNode] = []
+        self._output: List[ASTNode] = []
+        self._alias: Optional[str] = None
+        self._overridden: Any = None
+        self._reducers: Optional[List['AggregateFunction']] = None
+        self._patterns: Optional[List['PatternExpression']] = None
+
+    def add_node(self, node: ASTNode) -> None:
+        """Adds a node (operand or operator) to the expression.
+        
+        Uses the Shunting Yard algorithm to maintain correct operator precedence.
+        
+        Args:
+            node: The AST node to add (operand or operator)
+        """
+        # Implements the Shunting Yard algorithm
+        if node.is_operand():
+            self._output.append(node)
+        elif node.is_operator():
+            operator1 = node
+            while len(self._operators) > 0:
+                operator2 = self._operators[-1]
+                if (operator2.precedence > operator1.precedence or
+                    (operator2.precedence == operator1.precedence and operator1.left_associative)):
+                    self._output.append(operator2)
+                    self._operators.pop()
+                else:
+                    break
+            self._operators.append(operator1)
+
+    def finish(self) -> None:
+        """Finalizes the expression by converting it to a tree structure.
+        
+        Should be called after all nodes have been added.
+        """
+        while self._operators:
+            self._output.append(self._operators.pop())
+        self.add_child(self._to_tree())
+
+    def _to_tree(self) -> ASTNode:
+        if not self._output:
+            return ASTNode()
+        node = self._output.pop()
+        if node.is_operator():
+            rhs = self._to_tree()
+            lhs = self._to_tree()
+            node.add_child(lhs)
+            node.add_child(rhs)
+        return node
+
+    def nodes_added(self) -> bool:
+        return len(self._operators) > 0 or len(self._output) > 0
+
+    def value(self) -> Any:
+        if self._overridden is not None:
+            return self._overridden
+        if self.child_count() != 1:
+            raise ValueError("Expected one child")
+        return self.children[0].value()
+
+    def set_alias(self, alias: str) -> None:
+        self._alias = alias
+
+    @property
+    def alias(self) -> Optional[str]:
+        from .reference import Reference
+        if isinstance(self.first_child(), Reference) and self._alias is None:
+            return self.first_child().identifier
+        return self._alias
+
+    @alias.setter
+    def alias(self, value: str) -> None:
+        self._alias = value
+
+    def __str__(self) -> str:
+        if self._alias is not None:
+            return f"Expression ({self._alias})"
+        return "Expression"
+
+    def reducers(self) -> List['AggregateFunction']:
+        if self._reducers is None:
+            from ..functions.aggregate_function import AggregateFunction
+            self._reducers = list(self._extract(self, AggregateFunction))
+        return self._reducers
+
+    def patterns(self) -> List['PatternExpression']:
+        if self._patterns is None:
+            from ...graph.pattern_expression import PatternExpression
+            self._patterns = list(self._extract(self, PatternExpression))
+        return self._patterns
+
+    def _extract(self, node: ASTNode, of_type: type) -> Generator[Any, None, None]:
+        if isinstance(node, of_type):
+            yield node
+        for child in node.get_children():
+            yield from self._extract(child, of_type)
+
+    def mappable(self) -> bool:
+        return len(self.reducers()) == 0
+
+    def has_reducers(self) -> bool:
+        return len(self.reducers()) > 0
+
+    @property
+    def overridden(self) -> Any:
+        return self._overridden
+
+    @overridden.setter
+    def overridden(self, value: Any) -> None:
+        self._overridden = value