How sidhant92/bool-parser-java works
Project Type & Purpose
• This is an open-source Java library (bool-parser-java) that provides functionality for parsing, validating, and evaluating boolean expressions.
• Its main use cases include transforming a textual boolean expression into a parsed tree (using ANTLR-generated parsers) and then evaluating it using various data types (String, Integer, Decimal, etc.).
File Structure
• Top-Level Directories and Files:
• The project is structured with a clear Maven/Gradle style using src/main/java for source code and src/test for unit tests.
• Build files (build.gradle, settings.gradle, gradlew) indicate it’s a Java library.
• Package Organization:
• com.github.sidhant92.boolparser/application contains the BooleanExpressionEvaluator class which acts as the API for evaluating expressions.
• com.github.sidhant92.boolparser/constant holds enum-like definitions (DataType, OperatorType, NodeType, etc.) that are used throughout.
• com.github.sidhant92.boolparser/datatype provides a DataType hierarchy and factory (factory pattern) for encapsulating the supported data types.
• com.github.sidhant92.boolparser/domain includes AST node classes (e.g. BooleanNode, NumericRangeNode, InNode) used to represent parts of a boolean expression.
• com.github.sidhant92.boolparser/operator implements various operators; note the inclusion of a factory and service to manage operator creation and usage.
• com.github.sidhant92.boolparser/parser (and subfolder antlr) handles the parsing logic using ANTLR. This is the entry point for converting a string into a structured AST.
• com.github.sidhant92.boolparser/util, exception, and the test packages add utility functions, error handling, and test coverage for each component.
High-Level Components
a. Input & Parsing:
• Component: BoolParser (in the parser package)
• Sub-component: ANTLR-based Parser (in parser/antlr) that tokenizes and parses the expression using a provided grammar (BooleanExpression.g4).
• Data Flow: Expression string → ANTLR Lexer/Parser → AST Node generation.
b. AST (Abstract Syntax Tree) Builder:
• Component: Domain Nodes (located in com/github/sidhant92/boolparser/domain)
• These nodes represent various expression types:
• NumericNode, NumericRangeNode, BooleanNode, UnaryNode, InNode
c. Data Types & Operators:
• DataType Factory (in the datatype package) produces concrete data type instances (Boolean, Integer, Long, Decimal, String, Version).
• Operator and Operator Factory (in the operator package) encapsulate logic for comparison and boolean operations.
d. Evaluation Engine:
• Component: BooleanExpressionEvaluator within the application package.
• Data Flow: Received AST → Evaluates the expression against an input Map representing data.
• Interaction: Uses services from the datatype and operator layers and handles exceptions (error flow from exception package).
e. Exception Handling:
• Component: Exception classes (e.g., InvalidExpressionException, ExpressionEvaluationException, etc.) provide standardized error reporting.
• Interaction: Exceptions are raised throughout parsing and evaluation; show these pathways with directed error flows.
f. Testing & Benchmarking (Support Infrastructure):
• Not part of the runtime architecture but important for understanding the component reliability:
• Test classes in src/test validate the logic of parsing and evaluation.
Relationships and Interactions
• The Input (a Boolean expression string) to the ANTLR Parser.
• ANTLR Parser to the AST Node Builder indicating a transformation from raw tokens to structured nodes.
• AST Nodes to the Evaluation Engine (BooleanExpressionEvaluator), as the AST represents the structure that the evaluator processes.
• Exception flows to be depicted as feedback loops from Parser/Evaluator back to the caller indicating failure modes.
Architectural Patterns & Design Principles
• Factory Pattern: Clearly used in DataTypeFactory and OperatorFactory.
• Separation of Concerns: Parsing logic is separated from data type definitions, operator implementations, and AST node definitions.
• Modularity: The project is organized into logical packages that each fulfill a distinct responsibility (parsing, domain modeling, evaluation, error handling).
• Abstraction: The API (BooleanExpressionEvaluator) abstracts the complexity behind parsing and evaluating boolean expressions.