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 →

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

» resistance = voltage / current
Result: 4.8

Project Architecture

Module Organization

Axion/
├── main.go                 # Application entry point
├── install.sh              # Installation script
├── constants.json          # Mathematical constants
├── history.json           # Persistent calculation history
├── go.mod                 # Go module definition
│
├── cmd/                   # Cobra CLI commands
│   └── cmd.go            # Root command & REPL
│
├── constants/             # Constants management
│   └── constants.go       # JSON-based constant loading
│
├── tokenizer/            # Lexical analysis
│   ├── tokenizer.go      # Token generation
│   └── tokenizer_test.go # Unit tests (68.0% coverage)
│
├── parser/               # Syntax analysis
│   ├── parser.go         # AST construction
│   └── parser_test.go    # Unit tests (76.4% coverage)
│
├── evaluator/            # Expression evaluation
│   ├── evaluator.go      # Mathematical computation
│   └── evaluator_test.go # Unit tests (74.5% coverage)
│
├── units/                # Unit conversion
│   └── units.go          # Multi-category conversion (100% coverage)
│
├── history/              # History management
│   └── history.go        # JSON-based persistent storage
│
└── settings/             # Configuration
    └── settings.go       # Precision and display settings

Processing Pipeline

User Input (REPL)
     ↓
[Cobra CLI Handler] → Command Processing
     ↓
[Tokenizer] → Lexical Analysis → Token Stream
     ↓
[Parser] → Syntax Analysis → Abstract Syntax Tree (AST)
     ↓
[Evaluator] → Mathematical Evaluation → Numerical Result
     ↓
[Formatter] → Color-Coded Output → Terminal Display
     ↓
[History] → Persistent Storage → JSON Archive

Key Design Patterns

Command Pattern: Cobra framework for CLI command handling
Recursive Descent: Parser implementation for expression analysis
Singleton: Settings and variable storage
Strategy Pattern: Unit conversion system

Test Coverage

Module	Coverage	Status
Units	100%	✓ Passing
Parser	76.4%	✓ Passing
Evaluator	74.5%	✓ Passing
Tokenizer	68.0%	✓ Passing
Core Modules Average	79.7%	✓ All Passing

Running Tests

# Run complete test suite
go test ./...

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

# Run with detailed output
go test -v ./...

# Run specific package tests
go test ./tokenizer
go test ./parser
go test ./evaluator
go test ./units

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Technical Highlights

Recursive Descent Parser: Proper operator precedence and associativity
AST Traversal: Post-order evaluation for correct computation
Cobra Framework: Professional CLI with subcommands and flags
JSON Persistence: History and variable storage across sessions
Comprehensive Testing: 79.7% coverage on core computational modules
Error Handling: Domain-specific error messages with context
Cross-Platform: Windows, macOS, and Linux support
Scientific Notation: Full support for exponential notation

What I Learned

Building a complete expression parser with proper precedence from scratch
Implementing Abstract Syntax Tree construction and traversal
Managing floating-point precision and scientific notation in Go
Designing modular, extensible CLI architecture with Cobra
Implementing persistent storage with JSON serialization
Writing comprehensive test suites with high coverage
Creating intuitive, color-coded terminal interfaces
Handling edge cases in mathematical computations

Contributing

We welcome contributions! Here's how you can help:

Fork the repository on GitHub
Clone your fork locally
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with proper tests
Test thoroughly (go test ./...)
Commit with descriptive messages
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request with detailed description

Development Guidelines

Follow Go standard formatting (gofmt, golint)
Add tests for new features
Update documentation for API changes
Keep commits atomic and well-described
Ensure all tests pass before submitting PR

Support & Community

Getting Help

Documentation: Check this README and inline code comments
Issues: GitHub Issues for bugs and features
Discussions: GitHub Discussions for questions

Issue Reporting

When reporting bugs, please include:

Go version (go version)
Operating system and architecture
Axion version or commit hash
Complete error message
Steps to reproduce
Expected vs. actual behavior

Acknowledgments

Go Community: For excellent standard library and tooling
Cobra: For providing an excellent CLI framework
Mathematical Computing: Inspired by scientific calculators and computing environments
Open Source: Built on principles of transparency and collaboration

License

This project is licensed under the MIT License - see the LICENSE file for details.

View Source Code on GitHub →

Built by Uthman | @codetesla51

Built with Go 1.24.5+ & Cobra CLI Framework
If you find Axion helpful, please consider giving it a ⭐ on GitHub!

Uthman Dev

Tech Stack

Project Status

Project Overview