Back to Projects

Axion – CLI math engine

Go
Axion – CLI math engine

Axion - High-Precision CLI Calculator

Axion is a sophisticated, high-precision mathematical engine with advanced CLI interface, built in Go. Powered by the Cobra CLI framework, it offers a complete mathematical computing environment with expression parsing, scientific functions, unit conversions, variable management, and persistent calculation history.

View on GitHub →

Axion Calculator Screenshot

Why Axion?

  • Precision: Advanced mathematical expression parser with proper operator precedence
  • Scientific: Complete scientific notation support and comprehensive function library
  • Conversions: Built-in unit conversion across length, weight, and time categories
  • Memory: Persistent calculation history and variable storage across sessions
  • Performance: Optimized Go implementation with minimal memory footprint
  • Modern CLI: Beautiful, color-coded interface powered by Cobra framework
  • Reliability: Comprehensive error handling and 79.7% test coverage
  • Extensible: Modular architecture for easy feature additions

Core Features

Mathematical Engine

  • Expression Parsing: Advanced recursive descent parser with proper precedence
  • Scientific Notation: Full support (2e-10, 3.14e+5, 1.5E-20)
  • Operators: +, -, *, /, ^ (power), ! (factorial), mod()
  • Parentheses Grouping: Complex nested expression support
  • Implicit Multiplication: Automatic insertion (2sin(x) → 2 * sin(x))

Mathematical Functions

  • Trigonometric: sin(), cos(), tan(), asin(), acos(), atan(), atan2()
  • Logarithmic: ln(), log(), log10(), log2(), log(x, base)
  • Exponential: exp(), pow(), sqrt()
  • Utility: abs(), ceil(), floor(), round(), trunc(), sign()
  • Statistical: mean(), median(), mode(), sum(), product()
  • Comparison: max(), min()

Variables & Constants

  • Variable Assignment: x = 5, result = sin(30) + cos(60)
  • Mathematical Constants: pi, e, phi, sqrt2, c (speed of light), G, h, R
  • Persistent Storage: Variables maintained across calculator sessions
  • Dynamic Updates: Real-time variable modification and retrieval

Unit Conversion System

  • Length: m, cm, mm, km, in, ft, yd, mi
  • Weight: kg, g, mg, lb, oz, ton
  • Time: s, ms, min, h, d
  • Cross-Category Protection: Prevents invalid conversions

Advanced Features

  • Calculation History: JSON-based persistent storage with session continuity
  • Precision Control: Configurable decimal precision (0-20 places)
  • Interactive REPL: Beautiful color-coded command interface with help system
  • Error Handling: Comprehensive error reporting with context
  • Cross-Platform: Native support for Windows, macOS, and Linux
  • Cobra Framework: Professional CLI with subcommands and flags

Installation

Quick Installation (Linux/macOS)

# Clone the repository
git clone https://github.com/codetesla51/Axion.git
cd Axion

# Run the installation script
chmod +x install.sh
./install.sh

# Reload your shell configuration
source ~/.bashrc  # or ~/.zshrc for Zsh users

# Verify installation
axion --help

The install script will automatically:

  • Build the Axion binary
  • Create a symlink in ~/.local/bin/axion
  • Detect your shell (bash/zsh)
  • Add ~/.local/bin to your PATH if needed

Manual Installation

# Clone and run
git clone https://github.com/codetesla51/Axion.git
cd Axion

# Install dependencies
go mod download

# Run directly
go run main.go

# Or build executable
go build -o axion
./axion

Go Install

go install github.com/codetesla51/Axion@latest

Usage Examples

Getting Started

axion

A Powerful CLI Calculator
Type 'help' for commands or 'exit' to quit

» 2 + 3 * 4
Result: 14

» sin(30) + cos(60)
Result: 1

» x = sqrt(16)
Result: 4

» convert 100 cm to m
100 cm = 1 m

Command Reference

Command Syntax Example
Expression <mathematical expression> 2 + 3 * sin(45)
Assignment <variable> = <expression> x = 10
Conversion convert <value> <from> to <to> convert 5 km to mi
History history history
Variables variables or vars variables
Precision precision <digits> precision 10
Clear clear or cls clear
Help help help
Exit exit or quit exit

Basic Operations

# Arithmetic with proper precedence
» 15 + 25 * 2 - 10 / 5
Result: 63

# Scientific notation
» 2e-10 + 3.5E+12
Result: 3500000000000

# Complex expressions with parentheses
» ((10 + 5) * 2)^2 / 3
Result: 300

# Factorial operations
» 10! / (5! * 2!)
Result: 15120

Advanced Functions

# Trigonometric calculations
» sin(30) + cos(60) + tan(45)
Result: 2

# Logarithmic functions
» log(100) + ln(e) + log2(16)
Result: 9.60517

# Custom base logarithm
» log(8, 2)
Result: 3

# Statistical functions
» mean(10, 20, 30, 40, 50)
Result: 30

» median(1, 3, 3, 6, 7, 8, 9)
Result: 6

Variable Management

# Variable assignment and usage
» radius = 5
Result: 5

» area = pi * radius^2
Result: 78.5398

» circumference = 2 * pi * radius
Result: 31.4159

# View all variables
» variables
┌─ Stored Variables ───────────────────┐
│ radius          = 5
│ area            = 78.5398
│ circumference   = 31.4159
└──────────────────────────────────────┘

# Use constants
» speed_of_light = c
Result: 299792458

Unit Conversions

# Length conversions
» convert 5280 ft to mi
5280 ft = 1 mi

» convert 1000 mm to in
1000 mm = 39.3701 in

# Weight conversions
» convert 2.5 kg to lb
2.5 kg = 5.51156 lb

# Time conversions
» convert 90 min to h
90 min = 1.5 h

Complex Calculations

# Physics calculations
» F = 9.8 * 75  # Force = mass * acceleration
Result: 735

» E = F * 10    # Energy = force * distance
Result: 7350

# Financial calculations
» principal = 1000
Result: 1000

» rate = 0.05
Result: 0.05

» compoundInterest = principal * (1 + rate)^10
Result: 1628.89

# Engineering calculations
» voltage = 12
Result: 12

» current = 2.5
Result: 2.5

» power = voltage * current
Result: 30

Technical Implementation

  • Expression Parser: Recursive descent parser with operator precedence
  • Tokenizer: Lexical analysis with scientific notation support
  • Variable System: In-memory map with JSON persistence
  • History Engine: Timestamped calculation logging
  • Conversion System: Type-safe unit conversion with validation
  • CLI Framework: Cobra-powered command interface
  • Error Recovery: Graceful error handling with helpful messages

Project Structure

Axion/
├── cmd/
│   └── root.go           CLI command definitions
├── pkg/
│   ├── calculator/       Core calculation engine
│   ├── converter/        Unit conversion system
│   ├── parser/           Expression parser
│   └── history/          Calculation history
├── tests/                Comprehensive test suite
├── install.sh            Installation script
└── main.go              Entry point

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Verbose output
go test -v ./...

Current test coverage: 79.7%

Built With

  • Go: High-performance compiled language
  • Cobra: Professional CLI framework
  • Color: Terminal color output library
  • JSON: Data persistence format

What I Learned

  • Building a recursive descent parser from scratch
  • Implementing operator precedence and associativity
  • Designing type-safe unit conversion systems
  • Creating interactive CLI applications with Cobra
  • Managing persistent state across sessions
  • Writing comprehensive test suites for mathematical software
  • Handling floating-point precision edge cases
  • Building modular, extensible software architecture

Future Enhancements

  • Matrix operations and linear algebra
  • Calculus operations (derivatives, integrals)
  • Complex number support
  • Graph plotting capabilities
  • More unit categories (temperature, pressure, volume)
  • Custom function definitions
  • Scripting support for batch calculations

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

View Source Code on GitHub →

Built by Uthman | @codetesla51