# 🧮 goca > A feature-rich, high-precision, scientific command-line calculator written in Go, powered by an Abstract Syntax Tree (AST) evaluator and arbitrary-precision decimal arithmetic. [![Go Version](https://img.shields.io/badge/go-1.18%2B-blue.svg)](https://go.dev/) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) --- ## ✨ Features * **High-Precision Arithmetic**: Uses arbitrary-precision decimal math (no floating-point rounding errors). * **Unit Conversions**: Supports Length, Mass, Time, Area, Temperature, Digital Storage, and Angle conversions natively. * **Live Currency Exchange**: Real-time currency conversion rates fetched automatically and cached. * **IP & CIDR Utilities**: Built-in network functions to parse IPs, calculate networks, broadcasts, netmasks, and address ranges. * **User-Defined Variables & Functions**: Persists variables and custom functions across sessions automatically. * **Rich Scientific Math**: Trigonometric (supporting deg/rad/grad), hyperbolic, and standard statistical/mathematical functions. * **Interactive CLI**: Autocompletion (TAB), history scroll, and syntax-colored output. Can also be used non-interactively via shell pipes. --- ## 🚀 Installation & Setup Ensure you have [Go](https://go.dev/doc/install) installed. 1. **Clone and Navigate**: ```bash git clone https://git.fhi.mpg.de/mike/goca.git cd goca ``` 2. **Build the Binary**: ```bash go build -o goca ``` 3. **Install to Path (Optional)**: ```bash mv goca /usr/local/bin/ ``` --- ## 💡 Quick Start Simply run `goca` to start the interactive shell: ```bash $ ./goca goca v1.0.15, type 'help' for examples. goca> 5 + 3 * 2 = 11 (0xB, 0b1011) goca> 100 USD to EUR = 91.42 EUR ``` Or pipe expressions directly from your shell: ```bash echo "10 mi to km" | ./goca ``` ### 🌐 Web GUI & Server Mode goca now features an interactive cyberpunk-styled web dashboard! Start the server by passing the `-p` or `--port` flag: ```bash $ ./goca -p 8800 🌐 Go-Ca web server started on http://localhost:8800 ``` Open your browser and navigate to `http://localhost:8800` to access the console. The Web GUI supports: * **Interactive Console**: Runs calculations with ANSI terminal color rendering. * **Command History**: Navigate your previous queries using the `ArrowUp` and `ArrowDown` keys in the input box. * **User Registry Panel**: Displays your currently defined variables and custom functions in real-time. Click any item to insert it directly into the input line. * **Quick Reference Guide**: Direct access to mathematical, conversion, IP, and currency syntax templates. * **State Management**: Clear the server state (variables/functions) via the `Reset State` header action. #### 📡 Developer REST API Integrate the calculator engine with other services via HTTP REST endpoints: * **Evaluate**: `GET /api/calculate?q=` - Returns `{ "output": "", "exit": }` * **List Variables**: `GET /api/variables` - Returns a sorted JSON array of user-defined variables * **List Functions**: `GET /api/functions` - Returns a sorted JSON array of user-defined functions * **Reset**: `POST /api/reset` - Deletes all user-defined variables/functions --- ## 📘 Comprehensive Guide ### 🔢 Core Math & Number Systems goca supports standard mathematical operations, bitwise logic, and various number systems: * **Arithmetic**: `+`, `-`, `*`, `/`, `%` (modulo), `**` or `pow(a, b)` * **Bitwise Operations**: `&` (AND), `|` (OR), `^` (XOR), `~` (NOT), `<<` (Left Shift), `>>` (Right Shift) * **Number Systems**: * **Hexadecimal**: `0xFF` * **Binary**: `0b1010` * **Octal**: `0o77` * **Implicit Multiplication**: `2(3 + 4)` or `2km` ### 📐 Scientific & Mathematical Functions A rich suite of functions is built-in: * **Trigonometry**: `sin(x)`, `cos(x)`, `tan(x)` (supports suffixes, e.g., `sin(90 deg)` or `sin(pi rad)`) * **Inverse Trig**: `asin(x)`, `acos(x)`, `atan(x)` (returns units, e.g., `asin(1) to deg`) * **Hyperbolic**: `sinh(x)`, `cosh(x)`, `tanh(x)` * **General Math**: `sqrt(x)`, `abs(x)`, `exp(x)`, `ln(x)` (natural), `log(x)` (base 10), `log2(x)` * **Rounding**: `ceil(x)`, `floor(x)`, `round(x)` * **Combinatorics & Stats**: `fact(x)` (factorial), `min(a, b, ...)`, `max(a, b, ...)`, `mod(a, b)` * **Conditionals**: `if(cond, true_val, false_val)` (e.g., `if(5 > 3, 10, 20)`) * **Constants**: `PI` and `E` ### 💾 Variables & Custom Functions Define and persist your own variables and functions: * **Variables**: * Assign: `x = 5.5` * Reference last output: `ans` or `_` (e.g., `ans * 2`) * List variables: `var` * Delete variable: `unset x` (or `unset *` to clear all) * **Custom Functions**: * Define: `f(x, y) = x * y + 2` * Evaluate: `f(3, 4)` (yields `14`) * List functions: `funcs` * Delete function: `unset f` All custom variables and functions are saved to `~/.goca_variables.json` and `~/.goca_functions.json` respectively, making them available in future sessions. ### 🌐 IP & Subnet Calculations goca includes a robust set of network utility functions: * **Parse IP / CIDR**: `ip("192.168.1.1")`, `cidr("10.0.0.0/24")` * **Network Address**: `network(cidr("10.0.0.50/24"))` (yields `10.0.0.0/24`) * **Broadcast Address**: `broadcast(cidr("10.0.0.50/24"))` (yields `10.0.0.255`) * **Netmask**: `mask(cidr("10.0.0.50/24"))` (yields `255.255.255.0`) * **Hosts Count**: `hosts(cidr("10.0.0.0/24"))` (yields `254`) * **IP Range**: `range(cidr("10.0.0.0/24"))` (returns string representation of start and end IPs) ### 📏 Unit Conversions Convert measurements using the syntax: ` to ` or ` in `. | Dimension | Supported Units | | :--- | :--- | | **Length** | `km`, `m`, `dm`, `cm`, `mm`, `um`, `nm`, `mi` (mile), `nmi` (nautical mile), `ft` (foot), `in` (inch), `yd` (yard) | | **Mass** | `t` (tonne), `kg`, `g`, `mg`, `ct` (carat), `lb` (pound), `oz` (ounce) | | **Time** | `yr` (year), `wk` (week), `d` (day), `h` (hour), `min` (minute), `s`, `ms`, `us`, `ns` | | **Digital Storage** | `EB`, `PB`, `TB`, `GB`, `MB`, `KB`, `B` (binary multiplier: `1024` base) | | **Area** | `km2` (sq. kilometer), `ha` (hectare), `acre`, `m2` (sq. meter), `cm2`, `mm2` | | **Temperature** | `K` (Kelvin), `C` (Celsius), `F` (Fahrenheit) | | **Angle** | `rad`, `deg` (degree), `grad` | **Examples**: ```text goca> 100 mi to km = 160.9344 km goca> 1 GB in MB = 1024 MB goca> 0 C to F = 32.0000 °F ``` ### 💱 Live Currency Exchange goca fetches exchange rates daily from the Open Exchange Rates API and caches them locally at `~/.goca_rates.json`. * **Conversion**: `100 USD to EUR` or `10$ to €` * **Change Base Currency**: `base USD` * **List Supported Currency Codes**: `cur` * **View Exchange Rates**: `rates` (shows core currencies relative to base) --- ## 🛠️ Commands Reference The interactive shell supports the following commands: * `help` - Show help information. * `units` - List all supported measurement units. * `rates` - Show currency exchange rates relative to the base currency. * `cur` - List all supported currency codes. * `var` - List all user-defined variables. * `funcs` - List all user-defined functions. * `unset ` - Delete a variable or custom function (or `unset *` to clear all). * `base ` - Change base currency. * `clear` - Clear the terminal screen. * `exit` or `quit` - Close the session. --- ## 📦 Project Architecture * [cli.go](file:///Users/mike/src/goca/cli.go) - Command loop, line-completion, history, and user input handler. * [units.go](file:///Users/mike/src/goca/units.go) - Units registry and conversion metadata. * [currency.go](file:///Users/mike/src/goca/currency.go) - Exchange rates fetcher, caching, and currency unit initialization. * [evaluator.go](file:///Users/mike/src/goca/evaluator.go) - AST evaluator implementing all math, logic, IP, and unit conversion rules. * [parser.go](file:///Users/mike/src/goca/parser.go) - Lexer and recursive descent parser. * [ast.go](file:///Users/mike/src/goca/ast.go) - Abstract Syntax Tree structures for parsing expressions. * [types.go](file:///Users/mike/src/goca/types.go) - Core types used across parsing and evaluation. * [main_test.go](file:///Users/mike/src/goca/main_test.go) - Test suite covering math, variables, functions, and unit conversions.