Native Generator

Purpose and Scope

The Native Generator produces query strings in Galach format from a parsed SyntaxTree. This generator reconstructs the original Galach syntax with proper character escaping and formatting, making it useful for query normalization, round-trip conversion, or generating canonical query representations. The Native Generator is one of three primary generators in the system; for Solr backend generation, see Solr ExtendedDisMax Generator, and for Elasticsearch backend generation, see Elasticsearch QueryString Generator.

The Native Generator follows the Visitor pattern (documented in Visitor Pattern Implementation) where each visitor handles a specific node type in the SyntaxTree, producing the corresponding Galach syntax string.

Sources: lib/Languages/Galach/Generators/Native.php1-34

Generator Architecture

The Native Generator consists of a main Native class and eight specialized visitor implementations that handle different node types. The generator receives a SyntaxTree and traverses it using the visitor pattern to produce a Galach-formatted query string.

Diagram: Native Generator Component Structure

Sources: lib/Languages/Galach/Generators/Native.php1-34 lib/Languages/Galach/Generators/Native/Query.php1-40 lib/Languages/Galach/Generators/Native/Group.php1-43 lib/Languages/Galach/Generators/Native/BinaryOperator.php1-40 lib/Languages/Galach/Generators/Native/UnaryOperator.php1-44 lib/Languages/Galach/Generators/Native/Word.php1-42 lib/Languages/Galach/Generators/Native/Phrase.php1-42 lib/Languages/Galach/Generators/Native/Tag.php1-39 lib/Languages/Galach/Generators/Native/User.php1-39

Generator Class

The Native class lib/Languages/Galach/Generators/Native.php11-34 serves as the entry point for native Galach generation. It accepts a Visitor instance in its constructor and provides a single generate() method.

Class Structure

Component	Type	Purpose
$visitor	Visitor	The aggregate visitor that dispatches to specialized visitors
__construct(Visitor $visitor)	Method	Initializes the generator with a visitor
generate(SyntaxTree $syntaxTree)	Method	Generates Galach query string from syntax tree

The generate() method lib/Languages/Galach/Generators/Native.php30-33 delegates to the visitor by calling $this->visitor->visit($syntaxTree->rootNode), which initiates the visitor traversal pattern.

Sources: lib/Languages/Galach/Generators/Native.php1-34

Visitor Implementations

Each visitor implementation extends the base Visitor class and implements two key methods: accept() to determine if the visitor can handle a node, and visit() to generate the output string for that node.

Query Visitor

Diagram: Query Visitor Processing Flow

The Query visitor lib/Languages/Galach/Generators/Native/Query.php1-40 handles QueryNode instances, which represent the root of the query. It iterates through all child nodes lib/Languages/Galach/Generators/Native/Query.php34-36 visits each with the sub-visitor, and joins the resulting clauses with spaces lib/Languages/Galach/Generators/Native/Query.php38

Accept Logic: Returns true for QueryNode instances lib/Languages/Galach/Generators/Native/Query.php17

Sources: lib/Languages/Galach/Generators/Native/Query.php1-40

Group Visitor

The Group visitor lib/Languages/Galach/Generators/Native/Group.php1-43 handles GroupNode instances, which represent parenthesized expressions in the query.

Processing Logic:

1. Extracts domain prefix from $node->tokenLeft->domain lib/Languages/Galach/Generators/Native/Group.php39
2. Visits all child nodes lib/Languages/Galach/Generators/Native/Group.php34-36
3. Joins clauses with spaces lib/Languages/Galach/Generators/Native/Group.php38
4. Wraps in delimiters from tokenLeft and tokenRight lib/Languages/Galach/Generators/Native/Group.php41

Output Format: {domain}:({clauses})

Accept Logic: Returns true for GroupNode instances lib/Languages/Galach/Generators/Native/Group.php17

Sources: lib/Languages/Galach/Generators/Native/Group.php1-43

BinaryOperator Visitor

Diagram: BinaryOperator Visitor Logic

The BinaryOperator visitor lib/Languages/Galach/Generators/Native/BinaryOperator.php1-40 handles binary logical operators (LogicalAnd and LogicalOr nodes).

Processing Logic:

1. Visits left operand lib/Languages/Galach/Generators/Native/BinaryOperator.php34
2. Visits right operand lib/Languages/Galach/Generators/Native/BinaryOperator.php35
3. Joins with operator lexeme from $node->token->lexeme lib/Languages/Galach/Generators/Native/BinaryOperator.php38

Output Format: {leftClause} {operator} {rightClause} (e.g., term1 AND term2)

Accept Logic: Returns true for LogicalAnd or LogicalOr instances lib/Languages/Galach/Generators/Native/BinaryOperator.php16-18

Sources: lib/Languages/Galach/Generators/Native/BinaryOperator.php1-40

UnaryOperator Visitor

The UnaryOperator visitor lib/Languages/Galach/Generators/Native/UnaryOperator.php1-44 handles unary operators: Mandatory (+), Prohibited (-), and LogicalNot (NOT).

Processing Logic:

1. Visits the operand node lib/Languages/Galach/Generators/Native/UnaryOperator.php35
2. Adds padding space after NOT tokens lib/Languages/Galach/Generators/Native/UnaryOperator.php37-40
3. Prepends operator lexeme to the operand clause lib/Languages/Galach/Generators/Native/UnaryOperator.php42

Output Format:

• For + and -: {operator}{clause} (e.g., +required, -excluded)
• For NOT: {operator} {clause} (e.g., NOT term)

Accept Logic: Returns true for Mandatory, Prohibited, or LogicalNot instances lib/Languages/Galach/Generators/Native/UnaryOperator.php18-20

Sources: lib/Languages/Galach/Generators/Native/UnaryOperator.php1-44

Word Visitor

The Word visitor lib/Languages/Galach/Generators/Native/Word.php1-42 handles Term nodes containing WordToken instances.

Processing Logic:

1. Extracts domain prefix from $token->domain lib/Languages/Galach/Generators/Native/Word.php37
2. Escapes special characters in the word lib/Languages/Galach/Generators/Native/Word.php38
3. Combines domain prefix and escaped word lib/Languages/Galach/Generators/Native/Word.php40

Character Escaping: The following characters are escaped with backslashes lib/Languages/Galach/Generators/Native/Word.php38:

• \ (backslash)
• ' (single quote)
• " (double quote)
• + (plus)
• - (minus)
• ! (exclamation)
• ( and ) (parentheses)
• : (colon)
• # (hash)
• @ (at sign)
• (space)

Output Format: {domain}:{escapedWord} or {escapedWord} if no domain

Accept Logic: Returns true for Term nodes with WordToken lib/Languages/Galach/Generators/Native/Word.php16-18

Sources: lib/Languages/Galach/Generators/Native/Word.php1-42

Phrase Visitor

The Phrase visitor lib/Languages/Galach/Generators/Native/Phrase.php1-42 handles Term nodes containing PhraseToken instances.

Processing Logic:

1. Extracts domain prefix from $token->domain lib/Languages/Galach/Generators/Native/Phrase.php37
2. Escapes quote characters matching $token->quote lib/Languages/Galach/Generators/Native/Phrase.php38
3. Wraps the escaped phrase in quotes lib/Languages/Galach/Generators/Native/Phrase.php40

Character Escaping: Only the quote character used to delimit the phrase (either " or ') is escaped lib/Languages/Galach/Generators/Native/Phrase.php38

Output Format: {domain}:{quote}{escapedPhrase}{quote} or {quote}{escapedPhrase}{quote} if no domain

Accept Logic: Returns true for Term nodes with PhraseToken lib/Languages/Galach/Generators/Native/Phrase.php16-18

Sources: lib/Languages/Galach/Generators/Native/Phrase.php1-42

Tag Visitor

The Tag visitor lib/Languages/Galach/Generators/Native/Tag.php1-39 handles Term nodes containing TagToken instances (e.g., #tag).

Processing Logic:

1. Extracts marker (typically #) from $token->marker lib/Languages/Galach/Generators/Native/Tag.php37
2. Extracts tag value from $token->tag lib/Languages/Galach/Generators/Native/Tag.php37
3. Concatenates marker and tag lib/Languages/Galach/Generators/Native/Tag.php37

Output Format: {marker}{tag} (e.g., #important)

Accept Logic: Returns true for Term nodes with TagToken lib/Languages/Galach/Generators/Native/Tag.php16-18

Note: Tags do not support domain prefixes and require no character escaping.

Sources: lib/Languages/Galach/Generators/Native/Tag.php1-39

User Visitor

The User visitor lib/Languages/Galach/Generators/Native/User.php1-39 handles Term nodes containing UserToken instances (e.g., @username).

Processing Logic:

1. Extracts marker (typically @) from $token->marker lib/Languages/Galach/Generators/Native/User.php37
2. Extracts user value from $token->user lib/Languages/Galach/Generators/Native/User.php37
3. Concatenates marker and user lib/Languages/Galach/Generators/Native/User.php37

Output Format: {marker}{user} (e.g., @johndoe)

Accept Logic: Returns true for Term nodes with UserToken lib/Languages/Galach/Generators/Native/User.php16-18

Note: Users do not support domain prefixes and require no character escaping.

Sources: lib/Languages/Galach/Generators/Native/User.php1-39

Visitor Mapping Table

The following table summarizes which visitor handles which node and token types:

Visitor Class	Node Type	Token Type	Domain Support	Escaping Required
Query	QueryNode	N/A	No	No
Group	GroupNode	N/A	Yes	No
BinaryOperator	LogicalAnd, LogicalOr	N/A	No	No
UnaryOperator	Mandatory, Prohibited, LogicalNot	N/A	No	No
Word	Term	WordToken	Yes	Yes (11 chars)
Phrase	Term	PhraseToken	Yes	Yes (quotes)
Tag	Term	TagToken	No	No
User	Term	UserToken	No	No

Sources: All Native visitor files

Character Escaping Rules

Character escaping in the Native Generator preserves the original syntax while ensuring special characters are properly escaped for re-parsing.

Diagram: Character Escaping Decision Tree

Word Escaping Pattern

The Word visitor uses the regex pattern '/([\\\'"+\-!():#@ ])/' lib/Languages/Galach/Generators/Native/Word.php38 to escape special characters. Each matched character is prefixed with a backslash.

Example Transformations:

• hello world → hello\ world
• foo:bar → foo\:bar
• test+required → test\+required

Phrase Escaping Pattern

The Phrase visitor uses the regex pattern /([\\{$token->quote}])/ lib/Languages/Galach/Generators/Native/Phrase.php38 to escape the delimiter quote character and backslashes.

Example Transformations:

• "hello \"world\"" → "hello \\\"world\\\""
• 'it\'s working' → 'it\\\'s working'

Sources: lib/Languages/Galach/Generators/Native/Word.php38 lib/Languages/Galach/Generators/Native/Phrase.php38

Domain Prefix Handling

Domain prefixes allow field-scoped queries in Galach syntax (e.g., title:search searches only in the title field). The Native Generator preserves domain prefixes for node types that support them.

Domain-Aware Visitors

Visitor	Domain Support	Domain Extraction	Output Format
Word	Yes	$token->domain	{domain}:{word} or {word}
Phrase	Yes	$token->domain	{domain}:{quote}{phrase}{quote} or {quote}{phrase}{quote}
Group	Yes	$node->tokenLeft->domain	{domain}:({clauses}) or ({clauses})
Tag	No	N/A	{marker}{tag}
User	No	N/A	{marker}{user}

Domain Prefix Logic

Each domain-aware visitor checks if $token->domain (or $node->tokenLeft->domain for groups) is an empty string:

• If empty: No domain prefix is added
• If non-empty: Adds {domain}: prefix to the output

This logic appears in:

• lib/Languages/Galach/Generators/Native/Word.php37
• lib/Languages/Galach/Generators/Native/Phrase.php37
• lib/Languages/Galach/Generators/Native/Group.php39

Example Domain Transformations:

• Word with domain "title" and word "search" → title:search
• Phrase with domain "content" and phrase "hello world" → content:"hello world"
• Group with domain "author" and child nodes → author:(john OR jane)

Sources: lib/Languages/Galach/Generators/Native/Word.php37-40 lib/Languages/Galach/Generators/Native/Phrase.php37-40 lib/Languages/Galach/Generators/Native/Group.php39-41

Usage Pattern

The Native Generator is typically instantiated with an aggregate visitor that combines all Native visitor implementations. The visitor pattern documentation (Visitor Pattern Implementation) details how visitors are composed.

Typical Usage Flow:

Diagram: Native Generator Execution Sequence

The generator receives a SyntaxTree, initiates visitor traversal from the root node, and recursively visits all child nodes to construct the output string. Each visitor handles its specific node type and delegates child node processing to the aggregate visitor.

Sources: lib/Languages/Galach/Generators/Native.php30-33