# pardim93/bashtruthtable architecture

> Architecture diagram of the GitHub repository pardim93/bashtruthtable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pardim93/bashtruthtable
- Repository: https://github.com/pardim93/bashtruthtable

## Overview

1. **Repository shape**
   - This is a very small, single-purpose repo: one interactive Bash program, `truth_table.sh`, plus documentation in `README.md`.
   - There are no libraries, services, build steps, or background workers. The architecture is entirely inside one shell script process.

2. **Primary subsystem: interactive expression builder**
   - The script’s main job is to let a user incrementally assemble a logical expression from a menu.
   - Each action adds or modifies tokens in an in-memory expression state rather than asking the user to type a full expression at once.

3. **Expression state model**
   - The script tracks a sequence of variables named automatically as `p, q, r, …` up to `y` (10 variables total).
   - Operator choices (`AND`, `OR`, `XOR`) and grouping tokens (`(`, `)`) are accumulated into the current expression.
   - Negation is modeled as a per-variable flag, not by rewriting the entire expression text.

4. **Input/action handling**
   - The UI is menu-driven: single-key commands map to expression mutations, preview, undo, reset, export, and evaluate.
   - There are two different negation pathways:
     - `n` queues negation for the next variable added.
     - `t` toggles negation on an already-added variable.
   - `u` and `r` provide local state management: undo the last token or reset the whole expression.

5. **Evaluation subsystem**
   - When the user presses Enter, the script evaluates the current expression into a truth table.
   - Evaluation is done using Bash’s built-in arithmetic/logic handling, so operator precedence follows Bash rules.
   - The README explicitly calls out precedence as `^` before `&&` before `||`, with parentheses used to override grouping.

6. **Truth-table generation flow**
   - The evaluator enumerates all possible input combinations for the variables currently in the expression.
   - For each row, it computes the boolean result and prints a formatted table with aligned columns.
   - The `5` command previews the table without finalizing the current state, which implies the evaluator can run in a non-committing mode as well.

7. **Grouping and logical correctness boundary**
   - Parentheses are treated as part of the expression-building layer, not as a separate parser service.
   - The README emphasizes that grouping changes semantics, especially for expressions like `(p || q) && r` versus `p && (q || r)`.
   - This makes the key architectural boundary: the script is both editor and evaluator, but the correctness of results depends on the token sequence it assembles.

8. **Export subsystem**
   - After evaluation, the script can export the last computed table.
   - Two output formats are supported:
     - `.txt` for a human-readable aligned table.
     - `.csv` for spreadsheet use, including expression metadata in the header.
   - The export step depends on a previously evaluated table, so evaluation is a prerequisite data source for file output.

9. **User-facing data flow**
   - The flow is: user keystrokes → expression state mutation → optional preview/evaluation → truth table rendering → optional export.
   - Undo/reset operate only on the in-memory expression state, while export consumes the most recently evaluated result set.
   - In other words, there is one core state machine with two outputs: terminal display and file export.

10. **Runtime and portability constraints**
   - The repo targets Bash 4.0+ and is designed to run on macOS without GNU grep dependencies, using `grep -oE` instead of `grep -oP`.
   - That portability choice is part of the architecture: the script is intended to be self-contained and work across common Unix-like environments without extra tooling.

Main entry points: [`truth_table.sh`](https://github.com/pardim93/bashtruthtable/blob/master/truth_table.sh) (truth_table.sh), [`README.md`](https://github.com/pardim93/bashtruthtable/blob/master/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme["README<br/>guide<br/>[README.md]"]
end

subgraph group_shell["Shell program"]
  node_script["truth_table.sh<br/>bash entrypoint<br/>[truth_table.sh]"]
  node_menu(("Menu loop<br/>command dispatcher"))
  node_state["Expr state<br/>token buffer"]
  node_negation(("Negation<br/>var flags"))
  node_undoreset(("Undo/Reset<br/>state control"))
  node_previeweval["Preview/Eval<br/>truth evaluator"]
  node_renderer["Table render<br/>formatter"]
  node_exporter["Export<br/>file output"]
end

node_readme -.->|"documents"| node_script
node_script -->|"starts"| node_menu
node_menu -->|"mutates"| node_state
node_menu -->|"toggles"| node_negation
node_menu -->|"controls"| node_undoreset
node_menu -->|"triggers"| node_previeweval
node_state -->|"feeds"| node_previeweval
node_negation -->|"annotates"| node_state
node_previeweval -->|"produces"| node_renderer
node_previeweval -->|"stores last result"| node_exporter
node_renderer -.->|"shares table"| node_exporter
node_menu -.->|"preview mode"| node_renderer

click node_readme "https://github.com/pardim93/bashtruthtable/blob/master/README.md"
click node_script "https://github.com/pardim93/bashtruthtable/blob/master/truth_table.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme toneBlue
class node_script,node_menu,node_state,node_negation,node_undoreset,node_previeweval,node_renderer,node_exporter toneAmber
```

## Components

### Documentation

User-facing usage and behavior notes

- [README](https://github.com/pardim93/bashtruthtable/blob/master/README.md): guide · Usage and precedence notes · `README.md`

### Shell program

Single Bash process that builds, evaluates, and exports truth tables

- [truth_table.sh](https://github.com/pardim93/bashtruthtable/blob/master/truth_table.sh): bash entrypoint · Interactive truth table generator · `truth_table.sh`
- **Menu loop**: command dispatcher · Maps keystrokes to actions and modes
- **Expr state**: token buffer · Accumulates variables, operators, and grouping tokens
- **Negation**: var flags · Queues or toggles per-variable negation
- **Undo/Reset**: state control · Rolls back the last token or clears the expression
- **Preview/Eval**: truth evaluator · Runs Bash precedence rules over all input combinations
- **Table render**: formatter · Formats aligned truth tables for terminal output
- **Export**: file output · Writes last evaluated table as TXT or CSV

## Connections

- README → truth_table.sh: documents · Describes commands, precedence, and usage
- truth_table.sh → Menu loop: starts · Launches the interactive command loop
- Menu loop → Expr state: mutates · Adds variables, operators, and parentheses
- Menu loop → Negation: toggles · Queues negation for next variable or toggles existing one
- Menu loop → Undo/Reset: controls · Undo last token or reset entire expression
- Menu loop → Preview/Eval: triggers · Enter or preview command sends current expression to evaluation
- Expr state → Preview/Eval: feeds · Current token sequence becomes the evaluated expression
- Negation → Expr state: annotates · Applies negation flags to variables in the expression
- Preview/Eval → Table render: produces · Computed rows are formatted for terminal display
- Preview/Eval → Export: stores last result · Evaluation result becomes the export source
- Table render → Export: shares table · Export uses the most recently rendered evaluated table
- Menu loop → Table render: preview mode · Can show a table without finalizing the edit state
