README.md

███    ██ ██    ██ ███    ███ ██████
████   ██ ██    ██ ████  ████ ██   ██
██ ██  ██ ██    ██ ██ ████ ██ ██████
██  ██ ██ ██    ██ ██  ██  ██ ██   ██
██   ████  ██████  ██      ██ ██   ██

A text calculator for natural language expressions with a vim-style TUI.

Try it online →

Features

• Natural language expressions: 20% of 150, $100 in euros, 2 hours + 30 min
• Variables: tax = 15% then 100 + tax
• Unit conversions: Length, weight, time, temperature, data sizes
• Compound units: 5 m * 10 m = 50 m², 100 km / 2 h = 50 km/h
• Currency conversions: USD, EUR, GBP, JPY, CHF, CNY, CAD, AUD, INR, KRW, RUB, ILS, PLN, UAH + crypto (BTC, ETH, SOL, and more)
• Number base conversions: 22 to hex, 22 to bin
• Live exchange rates: Fetched automatically on startup
• Dual keybinding modes: Vim (modal) or Standard (direct input) - toggle with Shift+Tab
• Mouse support: Scroll with mouse wheel or trackpad
• File persistence: Save with Ctrl+S, supports custom files
• Syntax highlighting: Numbers, operators, variables, units, and currencies
• Comments: Lines starting with # or // are treated as comments
• Continuation: Start a line with an operator (+ 10, * 2) to continue from the previous result
• Wrap mode: Toggle text wrapping with bottom-aligned results
• Grouped totals: Currencies and units summed separately in footer (respects exchange rates)

Installation

macOS (Homebrew)

brew tap nasedkinpv/tap
brew install numr

Installs both binaries: numr (opens the calculator file in the TUI) and numr-cli (CLI/REPL/server).

Arch Linux (AUR)

# Using yay
yay -S numr

# Using paru
paru -S numr

Installs both binaries: numr (opens the calculator file in the TUI) and numr-cli (CLI/REPL/server).

From source

# Install the TUI binary
cargo install --path crates/numr-tui

# Install the CLI binary
cargo install --path crates/numr-cli

# Or build both from source
cargo build --release

# Binaries will be available at target/release/numr and target/release/numr-cli

Release archives also contain both binaries: numr (opens the calculator file in the TUI) and numr-cli (CLI/REPL/server).

Usage

TUI Mode

# Open default file (stored in OS config directory)
numr

# Open specific file
numr example.numr

CLI Mode

# Single expression
numr-cli "20% of 150"

# Evaluate file (aligned "input = result" output)
numr-cli -f example.numr

# Interactive REPL
numr-cli -i

# Pipe mode
echo "100 + 200" | numr-cli

# Show running total
numr-cli -t -f example.numr

# Aligned output for any mode
numr-cli --verbose "20% of 150"

By default, numr-cli prints just the result. File mode (-f) uses aligned input = result output. Use --verbose to get aligned output in other modes. Use -t to show a running total at the end.

On Linux, use rlwrap numr-cli -i for readline-style history and editing in the REPL.

JSON-RPC Server Mode

Run numr as a backend for other tools (editors, launchers, scripts):

numr-cli --server

Send JSON-RPC 2.0 requests via stdin, receive responses via stdout:

echo '{"jsonrpc":"2.0","method":"eval","params":{"expr":"20% of 150"},"id":1}' | numr-cli --server
# {"jsonrpc":"2.0","result":{"type":"number","value":"30","display":"30"},"id":1}

Available methods:

Keybindings (TUI)

The TUI supports two keybinding modes: Vim (default) and Standard. Press Shift+Tab to toggle between them.

Vim Mode

Normal Mode

Insert Mode

Standard Mode

Direct input like traditional editors - no modal switching required.

Supported Operations

Compound unit aliases: kph (km/h), mph (mi/h), mps (m/s), m2 (m²), km2 (km²), ft2 (ft²)

10 + 20           → 30
100 - 25          → 75
6 * 7             → 42
100 / 4           → 25
2 ^ 8             → 256

22 to hex         → 0x16
22 to bin         → 0b10110
-42 to hex        → -0x2a

20% of 150        → 30
100 + 15%         → 115
\$50 - 10%         → \$45

price = \$100
tax = 8%
price + tax       → \$108

# This is a comment
// This is also a comment
Groceries         \$45.00

\$100              → \$100
+ \$50             → \$150 (continues from previous)
* 2               → \$300
- 10%             → \$270
total = _         → \$270 (_ or ANS references previous result)

sum(10, 20, 30)   → 60
avg(10, 20, 30)   → 20
min(5, 3, 8)      → 3
max(5, 3, 8)      → 8
sqrt(16)          → 4
abs(-5)           → 5
round(3.7)        → 4
floor(3.7)        → 3
ceil(3.2)         → 4

5 m * 10 m        → 50 m²
100 km / 2 h      → 50 km/h
50 kph * 2 h      → 100 km
50 kph in mps     → 13.89 m/s
25 km / 100 km    → 0.25 (dimensionless)

Supported Units

Architecture

graph TB
    subgraph Frontends
        CLI[numr-cli<br/>CLI · REPL · JSON-RPC]
        TUI[numr-tui<br/>Terminal UI · Vim/Standard]
        Web[numr-web<br/>WASM web app]
    end

    Editor[numr-editor<br/>Syntax highlighting]

    subgraph Core[numr-core]
        Engine[Engine]
        Engine --> Parser[PEG Parser]
        Parser --> Eval[Evaluator]
        Eval --> Types[Currency · Units · Values]
        Eval --> Cache[(Rate Cache)]
    end

    Fiat[open.er-api.com]
    Crypto[CoinGecko]

    CLI --> Engine
    TUI --> Engine
    TUI --> Editor
    Web --> Engine
    Web --> Editor
    Cache -.-> Fiat
    Cache -.-> Crypto

numr/
├── crates/
│   ├── numr-core/      # Core evaluation engine (WASM-compatible)
│   │   ├── parser/     # Pest PEG grammar and AST builder
│   │   ├── eval/       # Expression evaluation with unit/currency handling
│   │   ├── types/      # Value, Currency, Unit registries
│   │   ├── cache/      # Exchange rate caching with BFS path finding
│   │   ├── fetch.rs    # HTTP rate fetching (optional "fetch" feature)
│   │   └── wasm.rs     # WASM bindings (optional "wasm" feature)
│   ├── numr-editor/    # Syntax highlighting and text buffer (WASM-compatible)
│   ├── numr-tui/       # Terminal UI (Ratatui) with vim/standard modes
│   └── numr-cli/       # CLI, interactive REPL, and JSON-RPC server

The core library (numr-core) is UI-agnostic and can be embedded in CLI, TUI, GUI, or WASM contexts. The fetch feature flag enables HTTP fetching (adds reqwest dependency, not WASM-compatible).

Config and cache are stored in the OS config directory (~/.config/numr/ on Linux, ~/Library/Application Support/numr/ on macOS). Settings persist automatically when toggled in the TUI.

Example config.toml:

[preferences]
keybinding_mode = "vim"   # "vim" or "standard"
wrap_mode = false
show_line_numbers = false
show_header = false

[files]
default_path = "~/Documents/calculations.numr"

[api]
fiat_rates_url = "https://open.er-api.com/v6/latest/USD"
crypto_rates_url = "https://api.coingecko.com/api/v3/simple/price"

[api.keys]
coingecko_api_key = "your-key-here"

CoinGecko API key header (demo vs pro) is selected automatically based on the URL host.

Exchange rates are cached to rates.json in the same config directory with 1-hour expiry. Both TUI and CLI share this cache:

• TUI: Fetches fresh rates on startup
• CLI: Fetches only if cache is expired

Rate sources:

• Fiat currencies: open.er-api.com (152 currencies, free)
• Cryptocurrency: CoinGecko (15 tokens, free)

Integrations

• elephant-numr — Provider for Walker/Elephant launcher

License

MIT