# scijava/parsington architecture

> Architecture diagram of the GitHub repository scijava/parsington, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scijava/parsington
- Repository: https://github.com/scijava/parsington

## Overview

##### Overall Project Type and Purpose
- This is a single-library (or module) project meant to serve as an expression parser for mathematical expressions.
- It supports converting infix expressions to both postfix queues and syntax trees, and includes an evaluation subpackage for processing these parsed expressions.
- It is distributed via Maven Central and is part of the broader SciJava ecosystem.

##### Analysis of the File Structure
- The top-level structure contains configuration folders (.github), build files (pom.xml), and clearly separated source (src/main/java) and test directories (src/test/java).
- In the src/main/java directory, the package structure (org/scijava/parsington) contains all the core parser classes such as ExpressionParser, Tokens, SyntaxTree, and classes to represent different elements (Operator, Function, Group, etc.).
- The eval subpackage under src/main/java/org/scijava/parsington/eval holds various evaluator implementations (like DefaultStackEvaluator, DefaultTreeEvaluator, and their abstract and standard counterparts).
- There is also an interactive console (Main.java) that provides an entry point to experiment with the parser.

##### Key System Components and Their Responsibilities
a. Input/Interface Layer:
- Interactive Console (Main.java) – provides a command-line interface for testing and interacting with the parser.
- API Exposure – by means of public classes such as ExpressionParser which are used both by the console and by client applications.

b. Parsing Core:
- ExpressionParser – the primary entry point for converting an infix expression into a postfix queue or a syntax tree.
- Token and Tokens classes – responsible for breaking the input into manageable pieces.
- SyntaxTree and its associated nodes – used for representing the nested structure of expressions.

c. Evaluation Engine:
- The eval subpackage classes like DefaultTreeEvaluator and DefaultStackEvaluator that process the parsed expressions.
- Abstract evaluators (AbstractEvaluator, AbstractStandardEvaluator) that define the evaluation contracts and ensure extensibility.

d. Support and Customization:
- Literal, Variable, Operator, and Function classes which encapsulate the behaviors and properties needed to support custom parsing and operator precedence.
- Test classes located in the src/test directory, ensuring that the parser’s functionality is rigorously validated.

##### Architectural Patterns and Design Principles
- Separation of Concerns – the parser is distinct from the evaluator. This separation helps client code decide whether to only parse or also evaluate.
- Extensibility – the design supports custom operators and literals. The evaluator package provides base classes meant to be extended for custom behavior.
- Single Responsibility – components such as tokenization, syntax tree construction, and evaluation are each managed by dedicated classes.
- Modularity – the clear package structure supports potential reuse in other projects and makes maintenance easier.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input/Interface Layer"
         IC("Interactive Console"):::interfaceLayer
         EP("ExpressionParser"):::interfaceLayer
    end

    subgraph "Parsing Core"
         subgraph "Tokenization"
              T1("Token"):::parsingCore
              T2("Tokens"):::parsingCore
         end
         ST("Syntax Tree Builder"):::parsingCore
         PC("Postfix Converter"):::parsingCore
    end

    subgraph "Evaluation Engine"
         AE("AbstractEvaluator"):::evaluationEngine
         ASE("AbstractStandardEvaluator"):::evaluationEngine
         DSE("DefaultStackEvaluator"):::evaluationEngine
         DTE("DefaultTreeEvaluator"):::evaluationEngine
         EI("Evaluator Interface"):::evaluationEngine
         SE("StackEvaluator"):::evaluationEngine
         STE("StandardEvaluator"):::evaluationEngine
         SSE("StandardStackEvaluator"):::evaluationEngine
         STE2("StandardTreeEvaluator"):::evaluationEngine
         TE("TreeEvaluator"):::evaluationEngine
         UN("Unresolved"):::evaluationEngine
         EC("EvaluatorConsole"):::evaluationEngine
    end

    subgraph "Customization & Support"
         F("Function"):::customSupport
         G("Group"):::customSupport
         L("Literals"):::customSupport
         OP("Operator"):::customSupport
         OPS("Operators"):::customSupport
         V("Variable"):::customSupport
         PO("ParseOperation"):::customSupport
         P("Position"):::customSupport
         SS("SubSequence"):::customSupport
    end

    subgraph "Testing"
         TST1("ExpressionParserTest"):::testing
         TST2("SyntaxTreeTest"):::testing
         TST3("DefaultStackEvaluatorTest"):::testing
         TST4("DefaultTreeEvaluatorTest"):::testing
    end

    %% Connections
    IC -->|"calls"| EP
    EP -->|"tokenizes"| T1
    EP -->|"tokenizes"| T2
    EP -->|"builds"| ST
    EP -->|"converts"| PC
    ST -->|"evaluatedby"| DTE
    PC -->|"evaluatedby"| DSE
    EP -->|"utilizes"| F
    EP -->|"utilizes"| G
    EP -->|"utilizes"| L
    EP -->|"utilizes"| OP
    EP -->|"utilizes"| OPS
    EP -->|"utilizes"| V
    EP -->|"utilizes"| PO
    EP -->|"utilizes"| P
    EP -->|"utilizes"| SS
    IC -->|"triggers"| EC
    AE -->|"basefor"| DTE
    ASE -->|"basefor"| DSE
    EI -->|"defines"| SE
    EI -->|"defines"| STE
    EI -->|"defines"| SSE
    EI -->|"defines"| STE2
    EI -->|"defines"| TE
    DTE -->|"implof"| TE
    DSE -->|"implof"| SE

    %% Styles
    classDef interfaceLayer fill:#B2DFDB,stroke:#00695C,stroke-width:2px;
    classDef parsingCore fill:#FFF59D,stroke:#F9A825,stroke-width:2px;
    classDef evaluationEngine fill:#FFCC80,stroke:#F57C00,stroke-width:2px;
    classDef customSupport fill:#C5E1A5,stroke:#66BB6A,stroke-width:2px;
    classDef testing fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;

    %% Click Events
    click IC "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Main.java"
    click EP "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/ExpressionParser.java"
    click T1 "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Token.java"
    click T2 "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Tokens.java"
    click ST "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/SyntaxTree.java"
    click DSE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/DefaultStackEvaluator.java"
    click DTE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/DefaultTreeEvaluator.java"
    click AE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/AbstractEvaluator.java"
    click ASE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/AbstractStandardEvaluator.java"
    click EI "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/Evaluator.java"
    click SE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/StackEvaluator.java"
    click STE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/StandardEvaluator.java"
    click SSE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/StandardStackEvaluator.java"
    click STE2 "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/StandardTreeEvaluator.java"
    click TE "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/TreeEvaluator.java"
    click UN "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/Unresolved.java"
    click EC "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/eval/EvaluatorConsole.java"
    click F "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Function.java"
    click G "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Group.java"
    click L "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Literals.java"
    click OP "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Operator.java"
    click OPS "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Operators.java"
    click V "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Variable.java"
    click PO "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/ParseOperation.java"
    click P "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/Position.java"
    click SS "https://github.com/scijava/parsington/blob/main/src/main/java/org/scijava/parsington/SubSequence.java"
    click TST1 "https://github.com/scijava/parsington/blob/main/src/test/java/org/scijava/parsington/ExpressionParserTest.java"
    click TST2 "https://github.com/scijava/parsington/blob/main/src/test/java/org/scijava/parsington/SyntaxTreeTest.java"
    click TST3 "https://github.com/scijava/parsington/blob/main/src/test/java/org/scijava/parsington/eval/DefaultStackEvaluatorTest.java"
    click TST4 "https://github.com/scijava/parsington/blob/main/src/test/java/org/scijava/parsington/eval/DefaultTreeEvaluatorTest.java"
```
