Visitor Pattern Implementation

Purpose and Scope

This document describes how the Visitor Pattern is implemented and utilized within the QueryTranslator library for query generation. The visitor pattern enables the traversal of Abstract Syntax Tree (AST) nodes, converting them into various backend query formats. For information about the specific generators that employ this pattern, see Query Generation and related pages on Native Generator, Solr ExtendedDisMax Generator, and Elasticsearch QueryString Generator.

Visitor Pattern Overview

The QueryTranslator employs the Visitor Design Pattern to separate the query generation logic from the structure of the abstract syntax tree. This pattern allows the library to:

1. Add new operations to existing node structures without modifying them
2. Accumulate state while traversing the AST
3. Apply different generation strategies to the same AST
4. Maintain a clean separation of concerns

Sources: lib/Languages/Galach/Generators/Native/Word.php14-21 lib/Languages/Galach/Generators/Native/Phrase.php14-19

Core Components

Abstract Visitor Class

The Visitor pattern implementation is built around an abstract Visitor class that defines the interface all concrete visitors must implement:

Each visitor must implement:

1. accept(Node $node): Determines if the visitor can handle a specific node type
2. visit(Node $node, Visitor $subVisitor = null, $options = null): Processes the node and returns a string representation

Sources: lib/Languages/Galach/Generators/Native/Word.php16-41 lib/Languages/Galach/Generators/Native/Phrase.php16-41

Concrete Visitor Implementations

The library provides specialized visitors for each node type in the Abstract Syntax Tree:

Sources: lib/Languages/Galach/Generators/Native/Word.php lib/Languages/Galach/Generators/Native/Phrase.php lib/Languages/Galach/Generators/Native/Group.php lib/Languages/Galach/Generators/Native/BinaryOperator.php lib/Languages/Galach/Generators/Native/UnaryOperator.php lib/Languages/Galach/Generators/Native/Tag.php lib/Languages/Galach/Generators/Native/Query.php

Visitor Responsibilities

Each concrete visitor is responsible for a specific type of node in the AST:

Visitor	Node Type	Responsibilities
Word	Term with WordToken	Processes single words, handles domain prefixes, escapes special characters
Phrase	Term with PhraseToken	Processes quoted phrases, handles domain prefixes, escapes quotes
Group	GroupNode	Processes parenthesized expressions, recursively handles nested nodes
BinaryOperator	LogicalAnd, LogicalOr	Processes binary operations, handles left and right operands
UnaryOperator	LogicalNot, Mandatory, Prohibited	Processes unary operations, applies operator to operand
Tag	Term with TagToken	Processes tag expressions (e.g., #hashtag)
Query	QueryNode	Processes the root query node, orchestrates processing of all child nodes

Sources: lib/Languages/Galach/Generators/Native/Word.php16-21 lib/Languages/Galach/Generators/Native/Phrase.php16-19 lib/Languages/Galach/Generators/Native/Group.php16-18 lib/Languages/Galach/Generators/Native/BinaryOperator.php16-19 lib/Languages/Galach/Generators/Native/UnaryOperator.php18-21 lib/Languages/Galach/Generators/Native/Tag.php16-19 lib/Languages/Galach/Generators/Native/Query.php16-18

Visitor Chain Implementation

One of the key features of the visitor pattern implementation is the ability to chain visitors together to process complex node structures. This is implemented through the subVisitor parameter:

Sources: lib/Languages/Galach/Generators/Native/Group.php34-36 lib/Languages/Galach/Generators/Native/BinaryOperator.php33-36 lib/Languages/Galach/Generators/Native/Query.php34-36

Visitor Accept Method Pattern

Each concrete visitor implements the accept method to determine if it can handle a specific node type:

For example, the Word visitor's accept method:

Sources: lib/Languages/Galach/Generators/Native/Word.php16-19 lib/Languages/Galach/Generators/Native/Phrase.php16-19 lib/Languages/Galach/Generators/Native/BinaryOperator.php16-19

Visitor Visit Method Implementation

The visit method performs the actual transformation of the node into a string representation. Each visitor implementation:

1. Validates that the node is of the expected type
2. Extracts the relevant data from the node
3. Processes any sub-nodes using the provided sub-visitor
4. Returns a formatted string representation

For composite nodes (like Group, BinaryOperator, or Query), the visitor recursively processes child nodes:

Sources: lib/Languages/Galach/Generators/Native/Group.php33-38 lib/Languages/Galach/Generators/Native/BinaryOperator.php33-38 lib/Languages/Galach/Generators/Native/Query.php33-38

Example: Word Visitor Implementation

The Word visitor provides a good example of a leaf node visitor implementation:

1. It checks if the node is a Term with a WordToken
2. It extracts the domain prefix and word from the token
3. It escapes special characters in the word
4. It returns the formatted word with domain prefix if present

Sources: lib/Languages/Galach/Generators/Native/Word.php21-41

Example: Group Visitor Implementation

The Group visitor demonstrates how composite nodes are processed:

1. It checks if the node is a GroupNode
2. It processes each child node using the sub-visitor
3. It joins the processed child nodes with spaces
4. It adds the group delimiters and domain prefix
5. It returns the formatted group expression

Sources: lib/Languages/Galach/Generators/Native/Group.php20-42

Integration with Generator System

The visitor pattern implementation is integrated with the generator system, which creates and orchestrates visitors to process the AST:

The generator typically:

1. Creates an aggregate visitor that contains all the concrete visitors
2. Uses the aggregate visitor to process the syntax tree
3. The aggregate visitor delegates to the appropriate concrete visitor for each node

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

Conclusion

The Visitor Pattern implementation in QueryTranslator provides a flexible and extensible way to process the Abstract Syntax Tree and generate output in various formats. By separating the node structure from the operations performed on it, the library can easily support multiple output formats without modifying the AST classes.

For more information on how this pattern is used in specific generators, see the documentation for Native Generator, Solr ExtendedDisMax Generator, and Elasticsearch QueryString Generator.