# thisisthedarshan/pss-grammar architecture

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

- Interactive diagram: https://gitdiagram.com/thisisthedarshan/pss-grammar
- Repository: https://github.com/thisisthedarshan/pss-grammar

## Overview

##### Project type and purpose
- This is an open-source tooling repository whose sole purpose is to define, build, and distribute parsers for the Portable Stimulus Standard (PSS).
- It provides two parallel grammar pipelines: one for ANTLR4 (in `ANTLR4/v3/`) and one for Tree-sitter (described in the README, typically under `TreeSitter/v3/`).

##### File structure
- Top-level:
- `README.md`, `LICENSE` – project overview and license.
- `ANTLR4/` – directory containing ANTLR4 grammar files.
– `v3/` – version-3 grammars broken out by language feature (e.g., `expressions.g4`, `data_types.g4`, etc.).
– `README.md` – build instructions for ANTLR4.
- (Implicit per README) `TreeSitter/v3/` – Tree-sitter grammar definitions and build scripts.
- No application code, runtime, or UI here—only grammar definitions and build instructions.

##### README for additional insights
- Describes two build pipelines:
- ANTLR4: you run `antlr4 pss.g4` in `ANTLR4/v3/` to generate parser/lexer code.
- Tree-sitter: you initialize, generate, compile with `tree-sitter-cli` and `gcc -shared`.
- Targets multiple output languages via ANTLR4’s code generators and Tree-sitter’s language bindings.

a. Main components
1. Input: PSS language specification (the Accellera LRM).
2. Grammar source modules:
– ANTLR4 grammars (`.g4` files under `ANTLR4/v3/`).
– Tree-sitter grammar files under `TreeSitter/v3/` (per README).
3. Generator tools:
– ANTLR4 CLI tool.
– Tree-sitter CLI tool & C compiler.
4. Generated artifacts:
– Parser & lexer source code in target languages (Java, Python, C#, etc.).
– Shared library (`parser.so`) for Tree-sitter.
5. Consumers / Integration points:
– Host projects embedding the generated parsers.
– IDEs or editor plugins using the Tree-sitter grammar.
– CI pipelines that test grammar correctness against sample PSS code.

b. Relationships & interactions

c. Architectural patterns & principles
- **Separation of concerns**: grammar definition vs. parser generation vs. integration.
- **Modular grammar**: each `.g4` is a slice of the language, combined by ANTLR4.
- **Dual-pipeline architecture**: two parallel build flows for different parser frameworks.
- **Polyglot codegen support**: multiple target languages configured in one grammar repo.

d. Key technologies & libraries
- ANTLR4 grammar files (`*.g4`) + ANTLR4 CLI
- Tree-sitter grammar JS + `tree-sitter-cli`, GCC
- Generated language runtimes: Java, Python, C#, JavaScript/TypeScript, Go, C++ etc.
- Node.js (for Tree-sitter initialization)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Input
    Spec["PSS Language Specification"]:::source

    %% ANTLR4 Pipeline
    subgraph "ANTLR4 Pipeline"
        Grammar["ANTLR4 Grammars (v3)"]:::source
        ANTLR4Readme["Build Instructions (README.md)"]:::source
        PSSG4["Core Grammar: pss.g4 & pssLexer.g4"]:::source
        Slices["Modular Grammar Slices (.g4 files)"]:::source
        Tool4["ANTLR4 CLI Tool"]:::tool
        Outputs4["Generated Parser Code<br/>(Java, Python, C#, etc.)"]:::output
    end

    %% Tree-sitter Pipeline
    subgraph "Tree-sitter Pipeline"
        TSGrammar["Tree-sitter Grammar (v3)"]:::source
        TSTool["tree-sitter CLI & Node.js"]:::tool
        CCompile["C Compiler (gcc -shared)"]:::tool
        TSOutput["parser.so & Language Bindings"]:::output
    end

    %% Consumers
    subgraph "Consumers and Integration"
        Host["Host Applications"]:::consumer
        IDE["IDEs / Editor Plugins"]:::consumer
        CI["CI Pipelines / Tests"]:::consumer
    end

    %% Connections
    Spec --> Grammar
    Grammar --> ANTLR4Readme
    Grammar --> PSSG4
    Grammar --> Slices
    PSSG4 --> Tool4
    Slices --> Tool4
    Tool4 --> Outputs4
    Spec --> TSGrammar
    TSGrammar --> TSTool
    TSTool --> CCompile
    CCompile --> TSOutput
    Outputs4 --> Host
    Outputs4 --> IDE
    Outputs4 --> CI
    TSOutput --> Host
    TSOutput --> IDE
    TSOutput --> CI

    %% Click Events
    click README.md "https://github.com/thisisthedarshan/pss-grammar/blob/main/README.md"
    click LICENSE "https://github.com/thisisthedarshan/pss-grammar/tree/main/LICENSE"
    click Grammar "https://github.com/thisisthedarshan/pss-grammar/tree/main/ANTLR4/v3/"
    click ANTLR4Readme "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/README.md"
    click PSSG4 "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/pss.g4"
    click PSSG4 "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/pssLexer.g4"
    click Slices "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/expressions.g4"
    click Slices "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/data_types.g4"
    click Slices "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/behavioral_coverage.g4"
    click Slices "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/conditional_compilation.g4"
    click Slices "https://github.com/thisisthedarshan/pss-grammar/blob/main/ANTLR4/v3/constraints.g4"

    %% Styles
    classDef source fill:#cce5ff,stroke:#1e73be,color:#1e73be;
    classDef tool fill:#d4edda,stroke:#28a745,color:#155724;
    classDef output fill:#fff3cd,stroke:#ffce54,color:#856404;
    classDef consumer fill:#ffe5d4,stroke:#f39c12,color:#7f5200;
```
