feat: add browser RPN calculator engine and demo

2026-04-22 22:08:01 +02:00
parent 707c6f3f73
commit e23373fee0
4 changed files with 851 additions and 1 deletions
@@ -1,2 +1,123 @@
-# mtm-rpn-js
+# RPN Virtual Calculator

+A browser-friendly RPN calculator implemented as a single JavaScript class, with a simple API and an example HTML interface.
+
+## Overview
+
+The project includes:
+
+- `rpn-calculator.js`: calculator engine
+- `rpn-example.html`: browser demo
+
+## Highlights
+
+- Self-contained JavaScript class
+- Configurable stack size (`maxSize`, default: 2048)
+- Configurable numeric base (`base`, default: 10)
+- Configurable angle mode (`angleMode`, default: `deg`)
+- Optional command enabling via `enabledCommands`
+- Generic public API centered on `push`, `pop`, `clear`, `swap`, `remove`, `edit`, `isValidIndex`, `input`, and `command`
+- `inputValue` stays a string to keep hexadecimal input possible later
+- `isEditing` tracks typed input mode
+- Operations are centralized with `argCount`, category, and aliases
+- Categories are limited to `Stack`, `Arithmetic`, and `Trigonometry`
+- Clear domain errors for invalid inputs
+- Degree-based trig demo in the example HTML
+
+## Quick start
+
+### In the browser
+
+```html
+<script src="rpn-calculator.js"></script>
+<script>
+  const calc = new RpnCalculator();
+  calc.input('1');
+  calc.input('2');
+  calc.command('enter');
+  calc.command('add');
+  console.log(calc.stack);
+</script>
+```
+
+### With options
+
+```js
+const calc = new RpnCalculator({
+  maxSize: 1024,
+  base: 10,
+  angleMode: 'deg',
+  enabledCommands: ['add', 'sub', 'mul', 'div', 'enter', 'clear'],
+});
+```
+
+## Public API
+
+### Properties
+
+- `stack`: current stack, with the top item at index `0`
+- `inputValue`: input text as a string
+- `isEditing`: whether input is currently being edited
+
+### Generic methods
+
+- `push(value)`
+- `pop()`
+- `clear()`
+- `swap(index1, index2)`
+- `remove(index)`
+- `edit(index)`
+- `isValidIndex(index)`
+- `input(command)`
+- `command(name, ...args)`
+
+## Supported commands
+
+### Stack
+
+- `enter`
+- `dup`
+- `drop`
+- `swap`
+- `clear`
+
+### Arithmetic
+
+- `add` / `+`
+- `sub` / `-`
+- `mul` / `*`
+- `div` / `/`
+- `mod` / `%`
+- `pow` / `^` / `y^x`
+- `sqr`
+- `neg`
+- `sqrt`
+- `recip` / `1/x`
+- `log`
+- `ln`
+
+### Trigonometry
+
+- `sin`
+- `cos`
+- `tan`
+- `asin`
+- `acos`
+- `atan`
+
+## Important behavior
+
+- `%` behaves as the RPN percentage operator: `a b % => (a * b) / 100`
+- `sqrt`, `asin`, `acos`, `log`, and `ln` throw clear errors for invalid inputs
+- `log` uses `Math.log10`
+- `ln` uses `Math.log`
+- `sin`, `cos`, and `tan` convert degrees to radians in the default demo
+- `asin`, `acos`, and `atan` return degrees in `deg` mode
+
+## Example HTML
+
+The example UI groups buttons into `Stack`, `Arithmetic`, and `Trigonometry` sections, and calls `command(...)` to execute operations.
+
+## License
+
+To be completed according to your project.