⚡ calc-cli

A sleek, interactive CLI calculator crafted with Python.

Cyberpunk Dark / Cyan / Emerald TUI • Modular Python Architecture • Zero-Division Guard • Session History

---

✨ Key Features

• 🎨 Cyberpunk Rich TUI — Built with rich featuring rounded neon borders, high-contrast Dark / Cyan / Emerald styling, and structured terminal tables.
• 🛡️ Zero-Division & Input Guards — Explicit DivisionByZeroError protection for division (/) and modulo (%) operations alongside resilient numeric validation.
• 🧠 Session Memory & ans Chaining — Automatically records timestamped calculations in an interactive history table and lets you chain results using the ans keyword.
• 🧩 Clean Modular Architecture — Strict separation of concerns across core.py (pure math), history.py (state & audit trail), ui.py (Rich presentation), and main.py (CLI controller).
• 🧪 Test-Driven Reliability — Verified by a comprehensive pytest unit test suite covering arithmetic operations, edge cases, UI rendering, and interactive session flows.

---

🚀 Quickstart

Run the entire installation and launch calc-cli with a single command:

git clone https://github.com/4jeeh/calc-cli.git && cd calc-cli && pip install -e . && calc-cli

Want to preview the full TUI showcase non-interactively?

python -m calc_cli.main --demo

---

⌨️ Navigation & Shortcuts

Key	Shortcut	Operation	Description
[1]	+ / add	Addition	Compute $a + b$
[2]	- / sub	Subtraction	Compute $a - b$
[3]	* / mul	Multiplication	Compute $a \times b$
[4]	/ / div	Division	Compute $a \div b$ with zero-division guard
[5]	^ / pow	Exponentiation	Compute $a^b$
[6]	% / mod	Modulo	Compute $a \bmod b$ with zero-division guard
[H]	hist	Session History	Render the timestamped session calculation table
[C]	clear	Clear History	Reset session history and clear the ans register
[M]	menu / ?	Show Menu	Re-display the navigation and shortcut table
[Q]	exit / quit	Quit Application	Exit calc-cli cleanly

Pro Tip: Type ans when prompted for the first or second number to automatically inject the previous calculation's result.

---

🗂️ Project Structure

calc-cli/
├── src/
│   └── calc_cli/
│       ├── __init__.py   # Package metadata & version
│       ├── core.py       # Pure mathematical functions & DivisionByZeroError guard
│       ├── history.py    # Immutable CalculationRecord & session history manager
│       ├── ui.py         # Rich TUI panels, tables, and Dark/Cyan/Emerald theme
│       └── main.py       # Interactive CLI loop & --demo showcase runner
├── tests/
│   ├── test_core.py      # Unit tests for arithmetic & edge cases
│   ├── test_history.py   # Unit tests for session history tracking
│   ├── test_main.py      # Unit tests for CLI dispatcher & interactive loop
│   └── test_ui.py        # Unit tests for Rich TUI component rendering
├── .gitignore            # Standard Python gitignore
├── LICENSE               # MIT License
├── pyproject.toml        # Modern PEP 621 packaging & pytest/black config
├── requirements.txt      # Runtime & test dependencies
└── README.md             # Showcase documentation

---

🧪 Running Tests

Execute the pytest suite from the repository root:

pytest

---

📖 From CS101 Homework to Modern Open-Source CLI Tool

Every developer's journey starts with a humble script. calc-cli began life as kalkulator.py—a 45-line introductory Computer Science (CS101) homework assignment written in a single procedural while True loop with basic print() and input() statements.

Rather than letting that early milestone gather dust, this repository reimagines what happens when foundational code is refactored with modern software engineering discipline:

1. Decoupled Architecture: The monolithic script was decomposed into pure mathematical primitives (core.py), stateful session tracking (history.py), declarative terminal rendering (ui.py), and an entrypoint controller (main.py).
2. Human-Centered Terminal UX: Plain stdout lines were replaced with a cyber-styled rich TUI featuring rounded panels, semantic color coding, operator shortcuts, and ans result chaining.
3. Engineering Rigor: String-based error returns were upgraded to typed exceptions (DivisionByZeroError), backed by automated pytest verification and PEP 621 packaging.

What started as a classroom exercise in basic control flow is now a clean, extensible, open-source command-line utility.

---

📄 License

Distributed under the MIT License. See LICENSE for full details.