CalCulator (Cal-see-you-later)

A lightweight command-line calculator written in C.

CalCulator is a modular expression engine designed around a clean frontend/backend architecture. The current implementation provides a complete command-line calculator capable of tokenizing mathematical input, building an abstract syntax tree (AST), evaluating expressions, and handling named mathematical functions.

The long-term goal is to expand the project with additional frontends, including a graphical user interface, while keeping the core calculation engine independent from input methods.

---

Features

Expression Engine

CalCulator currently supports:

• Basic arithmetic

  • Addition (+)
  • Subtraction (-)
  • Multiplication (*)
  • Division (/)
  • Modulus (%)

• Advanced operators

  • Exponentiation (^)
  • Factorial (!)
  • Unary negation (-5)

• Expression parsing

  • Operator precedence
  • Parentheses
  • Implicit multiplication

Examples:

2 + 2
5 * (3 + 4)
2^8
5!
2(4 + 3)

---

Mathematical Functions

Named mathematical operations are stored in a centralized operation registry.

Supported functions include:

Trigonometry

sin(x)
cos(x)
tan(x)

sec(x)
csc(x)
cot(x)

Inverse Trigonometry

asin(x)
acos(x)
atan(x)

Logarithms

ln(x)
log(x)
log10(x)

Exponential and Utility Functions

exp(x)
sqrt(x)
abs(x)

Multi-argument Functions

pow(x, y)
root(x, y)
mod(x, y)

Function lookup is case-insensitive.

Example:

SIN(1)
sin(1)
Sin(1)

All resolve to the same operation.

---

Architecture

CalCulator is designed as a layered calculation engine.

User Input
    |
    v
Dispatcher
    |
    +----------------+
    |                |
 Commands       Calculator Engine
                    |
                    v
                 Lexer
                    |
                    v
                 Parser
                    |
                    v
                  AST
                    |
                    v
                Evaluator
                    |
                    v
                 Result

---

Project Structure

CalCulator/
|
|----build/
|      |----calculator.exe
|
|----include/
|      |----ast.h
|      |----calculator.h
|      |----commands.h
|      |----config.h
|      |----dispatcher.h
|      |----evaluator.h
|      |----input.h
|      |----lexer.h
|      |----operations.h
|      |----parser.h
|
|----src/
|      |----ast.c
|      |----calculator.c
|      |----commands.c
|      |----dispatcher.c
|      |----evaluator.c
|      |----input.c
|      |----lexer.c
|      |----main.c
|      |----operations.c
|      |----parser.c
|
|----Makefile
|----README.md

---

Core Components

Lexer

The lexer converts raw text input into a stream of tokens.

Responsibilities:

• Recognize numbers
• Recognize operators
• Recognize identifiers/functions
• Track token positions
• Prepare input for parsing

Example:

sqrt(25)+5

becomes:

IDENTIFIER
LEFT_PAREN
NUMBER
RIGHT_PAREN
ADD
NUMBER

---

Parser

The parser converts tokens into an Abstract Syntax Tree.

Responsibilities:

• Enforce operator precedence
• Handle nested expressions
• Build mathematical structures
• Validate syntax

The parser uses recursive descent parsing.

Example:

2 + 3 * 4

is represented internally as:

      +
     / \
    2   *
       / \
      3   4

---

Abstract Syntax Tree (AST)

The AST represents the mathematical structure of an expression.

Supported node types include:

• Numbers
• Binary operations
• Unary operations
• Factorials
• Function calls

The AST allows the evaluator to operate independently from the original input format.

---

Evaluator

The evaluator recursively executes the AST.

Responsibilities:

• Perform mathematical calculations
• Execute registered functions
• Detect runtime errors
• Return structured results

Evaluation returns:

• Numeric value
• Error status

Example:

10 / 2

returns:

value = 5
error = EVAL_SUCCESS

---

Building

CalCulator uses a Makefile for compilation.

The Makefile provides native build targets for:

• Windows
• Linux
• macOS

The build system does not cross-compile. Each platform must be built from its corresponding operating system or development environment.

Requirements

A C compiler and make are required.

The Makefile automatically selects the compiler appropriate for the platform:

Platform	Compiler
Windows	GCC
Linux	GCC
macOS	cc / Apple Clang

The required compiler must be installed and available through the system's PATH.

---

Default Build

Running:

make

automatically builds CalCulator for the operating system on which make is running.

---

Windows

Build the Windows version with:

make windows

Aliases are also available:

make win
make w

The resulting executable is:

build/calculator.exe

---

Linux

Build the Linux version with:

make linux

Aliases are also available:

make lin
make l

The resulting executable is:

build/calculator

Linux builds can also be performed through WSL on Windows.

For example:

make linux

when executed inside a WSL environment will produce the native Linux executable.

---

macOS

Build the macOS version with:

make mac

An additional alias is available:

make m

The resulting executable is:

build/calculator

macOS uses the system C compiler (cc), which is normally provided by Apple's Command Line Tools.

---

Platform Validation

The Makefile verifies that a requested platform matches the environment where the build is being performed.

For example, attempting:

make linux

from Windows will not attempt to produce a Linux executable.

Instead, the Makefile reports that the Linux target must be built from Linux or WSL.

Likewise:

make windows

from Linux will be rejected.

This prevents accidentally producing a binary for a different platform without an appropriate cross-compilation toolchain.

---

Compiler Validation

Before compilation begins, the Makefile checks that the selected compiler is available.

If the required compiler cannot be found, the build stops with a readable error explaining that the necessary development tools need to be installed.

---

Build Utilities

Clean generated executables:

make clean

Perform a clean rebuild:

make rebuild

Display available build targets:

make help

---

Running

Windows

./build/calculator.exe

Linux / macOS

./build/calculator

Example session:

CalCulator (cal-see-u-later)
by: FairInHeight
Version: 0.1.0

> 2+2
= 4

> sqrt(25)
= 5

> root(27,3)
= 3

---

Design Philosophy

The primary design goal of CalCulator is separation of concerns.

The calculation engine does not depend on the user interface.

Currently:

Terminal
    |
Dispatcher
    |
Calculator Engine

Future frontends can provide input through a translation layer:

GUI
 |
Mobile App
 |
Web Interface
 |
Terminal
 |
      Translation Layer
             |
             v
      Calculator Engine

As long as a frontend can produce valid tokens or expressions, the same backend can process them.

This architecture allows the input system to evolve without requiring the underlying mathematical engine to be rewritten.

---

Cross-Platform Design

CalCulator is being developed with platform independence in mind.

The calculation engine itself relies on standard C functionality and the standard math library rather than platform-specific APIs.

Platform-specific concerns are isolated primarily to the build system.

                CalCulator
                    |
          +---------+---------+
          |         |         |
       Windows    Linux     macOS
          |         |         |
         GCC       GCC    Apple Clang
          |         |         |
          +---------+---------+
                    |
              Same C Source

The Makefile handles platform detection, compiler selection, executable naming, and validation.

This allows the same source tree to be built natively on each supported platform.

---

Current Limitations

The current version does not yet include:

• GUI frontend

• Constants such as:

  • π
  • e

• Variables

• User-defined functions

• Persistent calculation history

• Advanced mathematical libraries

These features are planned for future versions.

---

Roadmap

Version 0.1.x

Completed:

• Lexer
• Recursive descent parser
• AST generation
• Expression evaluator
• Function registry
• Error handling
• Command dispatcher
• Native Windows build
• Native Linux build
• Native macOS build configuration
• Cross-platform Makefile
• Platform validation
• Compiler selection

Future Development

Planned:

• GUI frontend
• Improved input system
• Mathematical constants
• Extended function support
• Calculation history
• Expanded cross-platform testing

---

Author

FairInHeight

CalCulator is a personal C programming project focused on building a clean, extensible mathematical expression engine from the ground up.

This project and its documentation should be considered incomplete at this moment. I will continue to update the project and documentation until I consider the project to be a finished engine and API.