mtm-rpn-js/README.md

RPN Virtual Calculator

A browser-friendly RPN calculator built around a small, generic JavaScript API.

Overview

This project provides:

• a reusable JavaScript RPN engine in src/rpn-calculator.js
• a browser demo in samples/dev/
• a command system centralized in a single operation dictionary
• a small public API focused on stack operations and generic command dispatch

The main class is RpnCalculator.

Project structure

• src/rpn-calculator.js: calculator engine
• samples/dev/index.html: active browser demo entry point
• samples/dev/index.css: demo styles
• samples/dev/index.js: demo UI and keyboard logic
• samples/calc-01/index.html: active browser demo entry point
• samples/calc-01/index.css: demo styles
• samples/calc-01/index.js: demo UI and keyboard logic
• samples/calc-XX/index.html: active browser demo entry point
• samples/calc-XX/index.css: demo styles
• samples/calc-XX/index.js: demo UI and keyboard logic

Public API

The calculator API is centered on these methods:

• push(value)
• pop()
• clear()
• swap(index1, index2)
• remove(index)
• edit(index)
• isValidIndex(index)
• input(command)
• command(name, ...args)

Instance helpers also available:

• getOperationsByCategory()
• getConstants()

Static helpers also available:

• RpnCalculator.getOperationCategories()
• RpnCalculator.getOperationsByCategory()

State exposed on instances:

• inputValue as a string
• isEditing as a boolean
• stack as the current internal stack array used by the demo
• angleMode
• base
• maxSize

Constructor options

const calc = new RpnCalculator({
  maxSize: 2048,
  base: 10,
  angleMode: 'deg',
  enabledCommands: ['add', 'sub', 'mul', 'div']
});

Supported options:

• maxSize: maximum stack size, default 2048
• base: numeric base, default 10, accepted range 2..16
• angleMode: deg, rad, or grad, default deg
• enabledCommands: optional whitelist of enabled commands and aliases

Constants

Available constants:

• pi
• e

They can be used through command(...):

calc.command('pi');
calc.command('e');

Supported commands

Stack

• enter
• dup
• drop
• swap
• clear

Arithmetic

• add alias: +
• sub alias: -
• mul alias: *
• div alias: /
• mod alias: %
• pow aliases: ^, y^x
• sqr
• neg
• sqrt alias: sqrt(x)
• recip alias: 1/x
• log
• ln

Trigonometry

• sin
• cos
• tan
• asin
• acos
• atan

Behavior notes

• mod is a percentage operator:
  • a b % => (a * b) / 100
• div and recip throw Division by zero when needed
• sqrt throws Invalid input for sqrt for negative values
• asin and acos throw explicit domain errors outside [-1, 1]
• log throws Invalid input for log for values <= 0
• ln throws Invalid input for ln for values <= 0
• log uses Math.log10
• ln uses Math.log
• direct trigonometric functions convert input using toRadians(...)
• inverse trigonometric functions convert results back using the current angle mode
• formatted numeric values are rounded to 12 decimal places
• -0 is normalized to 0
• inputValue remains a string to preserve future non-decimal input support
• base 10 input is parsed with Number(...)
• non-decimal input currently uses parseInt(..., base)

Input handling

input(command) supports two modes:

• single-character editing input
• command dispatch

Accepted single-character editing input currently includes:

• 0-9
• A-F
• a-f
• +
• -
• .

Everything else is forwarded to command(...).

Basic usage

CommonJS

const RpnCalculator = require('./src/rpn-calculator');

const calc = new RpnCalculator();
calc.push(2);
calc.push(3);
calc.command('add');

console.log(calc.pop()); // 5

Browser

<script src="./src/rpn-calculator.js"></script>
<script>
  const calc = new RpnCalculator({ angleMode: 'deg' });
  calc.push(9);
  calc.command('sqrt');
  console.log(calc.pop());
</script>

Editing values through input(...)

const calc = new RpnCalculator();

calc.input('1');
calc.input('2');
calc.input('.');
calc.input('5');
calc.command('enter');

console.log(calc.pop()); // 12.5

Aliases

const calc = new RpnCalculator();
calc.push(6);
calc.push(7);
calc.command('+');
console.log(calc.pop()); // 13

Constants and trigonometry

const calc = new RpnCalculator({ angleMode: 'deg' });
calc.command('pi');
console.log(calc.pop());

calc.push(30);
calc.command('sin');
console.log(calc.pop()); // 0.5

Demo

The active demo lives in samples/dev/.

Main UI features:

• four visible stack lines
• main display/status area
• visible angle mode indicator
• angle mode selector for deg, rad, and grad
• status pills for inputValue and isEditing
• grouped panels for Stack, Arithmetic, Trigonometry, and Constants
• error display area

The demo loads the engine from:

<script src="../../src/rpn-calculator.js"></script>

Demo keyboard support

The current demo supports:

• digits and decimal point
• numpad digits and numpad arithmetic keys
• Enter
• Backspace
• Delete
• Escape
• ArrowUp, ArrowDown, ArrowRight
• +, -, *, /, %, ^
• q, n, r, i, g, l, s, c, S, C
• x, y, z, t

The demo also implements stack selection and stack-item move mode in its UI layer using the public calculator methods.

Exports

RpnCalculator is exposed in both environments:

• browser: window.RpnCalculator
• CommonJS: module.exports = RpnCalculator