Rcal – Dimension-Safe Command-Line Calculator

1. Introduction and Motivation

Rcal arose from the need for a fast, reliable tool for scientific and technical calculations directly in the terminal. Standard software calculators process exclusively naked numbers, which quickly leads to unnoticed unit errors in complex physical formulas. Rcal combines the simplicity of a CLI tool with the safety of true dimensional analysis and additionally enables automation through scripts.

2. Problem Statement and Goals

Problem: Classic CLI calculators ignore physical units, which can lead to incorrect results (e.g., the unnoticed addition of meters and seconds). In addition, complex formulas are often difficult to save and reuse.

Goals:

Dimensional Safety: Strictly preventing impossible calculations (e.g., 5m + 10s) through an integrated SI unit system.
Reusability: Definition of custom variables and functions (e.g., f(x, y) = x^2 + y^2) as well as the execution of .rcal scripts.
Excellent UX: Syntax highlighting, tab completion for constants/units, and location-aware error reporting.
Performance & Safety: Development of a fast and memory-safe application in Rust.

3. System Architecture and Design

Architecture Overview: Rcal implements a complete, custom-built interpreter. The architecture cleanly separates input processing from mathematical evaluation.

Architecture Components:

Frontend (CLI): Uses the rustyline crate for interactive inputs, command history, syntax highlighting, and tab completion.
Lexer & Parser: A custom-written lexer tokenizes the inputs, after which a recursive descent parser generates an abstract syntax tree (AST).
Evaluator: Executes the AST and manages the state (variables, functions). This is where the dimensional check takes place, evaluating and validating 8 base dimensions (length, mass, time, etc.) as arrays.

Architecture Diagram: ::BaseMermaid

graph TD
    subgraph "Frontend (CLI)"
        UI[Rustyline Shell] -- Input --> Lexer[Lexer / Tokenizer]
    end

    subgraph "Interpreter Core"
        Lexer -- Tokens --> Parser[Parser]
        Parser -- Abstract Syntax Tree --> Evaluator[Evaluator]
        Evaluator -- Read / Write --> State[(Variables & Functions)]
        Evaluator -- Validation --> UnitSys[Unit System & Dimensions]
    end
    
    Evaluator -- Result / Error --> UI

4. Implementation Highlights

Dimensional Analysis Engine: The unit system tracks basic physical dimensions (such as length, mass, time) via an array of integers ([i8; 8]). Multiplications (5N * 2m) automatically generate correctly derived units (Joule), while incompatible additions are safely blocked with a precise error message.

Custom Parser for Natural Inputs: The parser supports natural mathematical expressions, including implicit multiplication (e.g., 2pi or 10m / 2s) and programmer tools like bitwise operations and base conversions (in hex, in bin).

Precise Error Handling: If a syntax or mathematical error occurs (e.g., division by zero or a dimension mismatch), Rcal visualizes the exact location of the error in the terminal or outputs the faulty line number in script mode.

5. Results and Outlook

Current Status: Rcal is fully functional as an interactive shell and script runner. It offers advanced mathematics (trigonometry, logarithms), aggregate functions, and a set of natural constants. Using GitHub Actions, binaries for Windows, macOS, and Linux are built completely automatically and provided as releases.

Next Steps:

Advanced Data Types: Support for vectors and matrices for more complex physical calculations.
Standard Library: Expansion of the built-in physical and chemical constants.
Library Export: Provisioning the Rcal engine as a standalone Rust crate for other projects.

6. Personal Growth and Lessons Learned

Compiler and Interpreter Construction: I gained deep insights into the construction of lexers, abstract syntax trees (ASTs), and state-based evaluators. Writing a parser completely "from scratch" was one of the most educational experiences.

Rust & Memory Safety: The project strongly solidified my understanding of Rust's strict typing and ownership concepts, especially when designing the interpreter architecture.