docs: refresh README and add HP48-style browser demo

This commit is contained in:
2026-04-24 21:16:40 +02:00
parent b6ca7d6b75
commit 30714a6c4e
3 changed files with 545 additions and 309 deletions
+101 -1
View File
@@ -11,7 +11,107 @@ This project defines a reusable RPN calculator engine with:
- centralized command metadata
- a browser demo that uses the same public API as any consumer code
## Package contents
# RPN Virtual Calculator
A browser-friendly RPN calculator built around a small, generic JavaScript API.
## Goal
This project provides a reusable Reverse Polish Notation (RPN) calculator engine with:
- a simple stack-based public API
- configurable numeric behavior
- centralized command metadata
- browser demos that use the same public API as any consumer code
## Project structure
- `src/rpn-calculator.js`: calculator engine
- `samples/dev/index.html`: browser demo
- `samples/hp48/index.html`: HP48-style browser demo
## Main features
- Single JavaScript class: `RpnCalculator`
- Configurable stack size via `maxSize` (default: `2048`)
- Configurable numeric base via `base` (default: `10`)
- Configurable angle mode via `angleMode`:
- `deg` (default)
- `rad`
- `grad`
- Optional command filtering through `enabledCommands`
- Public API limited to generic methods:
- `push(value)`
- `pop()`
- `clear()`
- `swap(index1, index2)`
- `remove(index)`
- `edit(index)`
- `isValidIndex(index)`
- `input(command)`
- `command(name, ...args)`
- `inputValue` is always stored as a string
- `isEditing` is exposed as a boolean
- Supported operations are centralized in one dictionary with metadata such as:
- `argCount`
- `category`
- `aliases`
- Supported categories are limited to:
- `Stack`
- `Arithmetic`
- `Trigonometry`
## Available constants
- `pi`
- `e`
## Supported commands
### Arithmetic
- `add` (`+`)
- `sub` (`-`)
- `mul` (`*`)
- `div` (`/`)
- `mod` (`%`)
- `pow` (`^`, `y^x`)
- `sqr`
- `neg`
- `sqrt`
- `recip` (`1/x`)
- `log`
- `ln`
### Trigonometry
- `sin`
- `cos`
- `tan`
- `asin`
- `acos`
- `atan`
### Stack
- `dup`
- `drop`
- `swap`
- `clear`
- `enter`
## Behavior rules
- `mod` is a percentage operator:
- `a b % => (a * b) / 100`
- `log` uses `Math.log10`
- `ln` uses `Math.log`
- `sqrt`, `asin`, `acos`, `log`, and `ln` throw explicit domain errors on invalid input
- Trigonometric behavior depends on `angleMode`
- In degree mode:
- `sin`, `cos`, `tan` convert degrees to radians internally
- `asin`, `acos`, `atan` return degrees
- `inputValue` remains a string to preserve future support for formats such as hexadecimal input
## Basic usage
### In a browser
- `rpn-calculator.js`: calculator engine
- `rpn-example.html`: example browser interface
+444
View File
@@ -0,0 +1,444 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>HP48-style RPN Calculator</title>
<style>
:root {
--body: #d8d8d8;
--panel: #202020;
--panel-2: #2b2b2b;
--screen: #d8e7b8;
--screen-text: #1b2a12;
--screen-dim: #5b6f45;
--key: #3a3a3a;
--key-text: #f2f2f2;
--accent: #8cff6d;
--border: #111;
}
* { box-sizing: border-box; }
body {
margin: 0;
font-family: Arial, sans-serif;
background: linear-gradient(180deg, #efefef, var(--body));
color: #111;
}
.wrap {
max-width: 980px;
margin: 0 auto;
padding: 24px;
}
.calc {
background: linear-gradient(180deg, #2f2f2f, #1f1f1f);
border: 1px solid #111;
border-radius: 20px;
padding: 18px;
box-shadow: 0 18px 48px rgba(0, 0, 0, 0.25);
}
.brand {
color: #fafafa;
display: flex;
justify-content: space-between;
align-items: baseline;
margin-bottom: 12px;
gap: 12px;
}
.brand h1 {
margin: 0;
font-size: 18px;
letter-spacing: 0.06em;
}
.brand small {
color: #c9c9c9;
}
.screen {
background: linear-gradient(180deg, #dbe8b8, var(--screen));
color: var(--screen-text);
border: 2px inset #8aa36b;
border-radius: 10px;
padding: 14px;
min-height: 190px;
font-family: "Courier New", monospace;
display: grid;
grid-template-rows: auto auto 1fr;
gap: 10px;
}
.screen-top {
display: flex;
justify-content: space-between;
gap: 12px;
font-size: 12px;
color: var(--screen-dim);
}
.stack {
border-top: 1px solid rgba(27, 42, 18, 0.35);
padding-top: 10px;
line-height: 1.5;
font-size: 18px;
white-space: pre-wrap;
}
.stack-line {
display: grid;
grid-template-columns: 26px 1fr;
gap: 8px;
}
.stack-line .label {
text-align: right;
color: var(--screen-dim);
}
.hidden-input {
position: absolute;
left: -9999px;
width: 1px;
height: 1px;
opacity: 0;
pointer-events: none;
}
.input-row {
display: grid;
grid-template-columns: 1fr 150px;
gap: 12px;
margin-top: 14px;
}
input, select, button {
border-radius: 10px;
border: 1px solid #000;
font: inherit;
}
input, select {
padding: 12px 14px;
background: #f7f7f7;
color: #111;
}
.panel {
margin-top: 14px;
background: rgba(255, 255, 255, 0.04);
border: 1px solid rgba(255, 255, 255, 0.08);
border-radius: 14px;
padding: 14px;
}
.title {
color: #fff;
margin: 0 0 10px;
font-size: 14px;
text-transform: uppercase;
letter-spacing: 0.08em;
}
.buttons {
display: grid;
gap: 8px;
grid-template-columns: repeat(auto-fit, minmax(92px, 1fr));
}
button {
padding: 12px 10px;
background: linear-gradient(180deg, #4a4a4a, var(--key));
color: var(--key-text);
cursor: pointer;
box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.08);
}
button:hover { filter: brightness(1.08); }
button:active { transform: translateY(1px); }
.status {
margin-top: 12px;
display: flex;
flex-wrap: wrap;
gap: 10px;
color: #ececec;
font-size: 13px;
}
.pill {
border: 1px solid rgba(255, 255, 255, 0.15);
border-radius: 999px;
padding: 5px 10px;
background: rgba(255, 255, 255, 0.05);
}
.error {
margin-top: 10px;
min-height: 20px;
color: #ff8a8a;
font-family: "Courier New", monospace;
font-size: 13px;
}
.hint {
color: #ddd;
margin-top: 10px;
font-size: 13px;
line-height: 1.5;
}
</style>
</head>
<body>
<div class="wrap">
<div class="calc">
<div class="brand">
<h1>HP48-style RPN</h1>
<small>powered by src/rpn-calculator.js</small>
</div>
<div class="screen" id="screen" tabindex="0" role="application" aria-label="HP48 style calculator screen">
<div class="screen-top">
<div>RPN stack</div>
<div id="modeLabel">deg</div>
</div>
<div id="stack" class="stack"></div>
<div id="display"></div>
</div>
<input id="input" class="hidden-input" type="text" autocomplete="off" aria-hidden="true" tabindex="-1">
<div class="input-row">
<div class="hint">Keyboard input is captured directly by the screen</div>
<select id="angleMode">
<option value="deg">Degrees</option>
<option value="rad">Radians</option>
<option value="grad">Grads</option>
</select>
</div>
<div class="status">
<div class="pill">inputValue: <span id="inputValueLabel"></span></div>
<div class="pill">isEditing: <span id="editingLabel"></span></div>
</div>
<div class="panel">
<div class="title">Stack</div>
<div class="buttons" id="stackButtons"></div>
</div>
<div class="panel">
<div class="title">Arithmetic</div>
<div class="buttons" id="arithButtons"></div>
</div>
<div class="panel">
<div class="title">Trigonometry</div>
<div class="buttons" id="trigButtons"></div>
</div>
<div class="panel">
<div class="title">Constants</div>
<div class="buttons" id="constButtons"></div>
</div>
<div id="error" class="error"></div>
<div class="hint">Use Enter to commit the current value. Buttons call <code>command(...)</code> directly, like a real RPN demo.</div>
</div>
</div>
<script src="../../src/rpn-calculator.js"></script>
<script>
const calc = new RpnCalculator({ angleMode: 'deg' });
const input = document.getElementById('input');
const screen = document.getElementById('screen');
const stackEl = document.getElementById('stack');
const displayEl = document.getElementById('display');
const errorEl = document.getElementById('error');
const inputValueLabel = document.getElementById('inputValueLabel');
const editingLabel = document.getElementById('editingLabel');
const modeLabel = document.getElementById('modeLabel');
const angleMode = document.getElementById('angleMode');
const groups = {
stack: ['enter', 'dup', 'drop', 'swap', 'clear'],
arithmetic: ['add', 'sub', 'mul', 'div', 'mod', 'pow', 'sqr', 'neg', 'sqrt', 'recip', 'log', 'ln'],
trig: ['sin', 'cos', 'tan', 'asin', 'acos', 'atan'],
const: ['pi', 'e'],
};
function labelFor(command) {
return ({ add: '+', sub: '', mul: '×', div: '÷', pow: 'y^x', recip: '1/x', sqr: 'x²' }[command] || command);
}
function addButtons(container, commands) {
container.innerHTML = '';
commands.forEach((commandName) => {
const button = document.createElement('button');
button.textContent = labelFor(commandName);
button.addEventListener('click', () => execute(commandName));
container.appendChild(button);
});
}
function getLineValue(line) {
if (calc.isEditing) {
if (line === 0) {
return calc.inputValue;
}
return calc.stack[line - 1];
}
return calc.stack[line];
}
function render() {
const names = ['T', 'Z', 'Y', 'X'];
const lines = [];
for (let line = 3; line >= 0; line -= 1) {
const value = getLineValue(line);
lines.push(`<div class="stack-line"><div class="label">${names[3 - line]}</div><div>${value !== undefined && value !== '' ? calc.formatNumber(value) : ''}</div></div>`);
}
stackEl.innerHTML = lines.join('');
displayEl.textContent = calc.isEditing ? `ENTERING: ${calc.inputValue}` : 'READY';
inputValueLabel.textContent = calc.inputValue || '∅';
editingLabel.textContent = String(calc.isEditing);
modeLabel.textContent = calc.angleMode;
angleMode.value = calc.angleMode;
errorEl.textContent = '';
}
function pushEditingValueIfNeeded() {
if (!calc.isEditing) return;
if (calc.inputValue !== '') {
const value = calc.parseInputValue(calc.inputValue);
if (calc.stack.length >= calc.maxSize) {
throw new Error('Stack overflow');
}
calc.stack.unshift(value);
if (calc.stack.length > 4) calc.stack.length = 4;
}
calc.inputValue = '';
calc.isEditing = false;
syncInputFromState();
}
function execute(name) {
try {
if (name === 'swap') {
pushEditingValueIfNeeded();
if (calc.stack.length >= 2) calc.swap(0, 1);
} else if (name === 'drop') {
pushEditingValueIfNeeded();
if (calc.stack.length >= 1) calc.remove(0);
} else if (name === 'clear') {
calc.clear();
} else if (name === 'enter') {
if (calc.isEditing) {
pushEditingValueIfNeeded();
}
} else {
pushEditingValueIfNeeded();
calc.command(name);
}
syncInputFromState();
render();
} catch (error) {
errorEl.textContent = error.message;
}
}
function isInputChar(key) {
return /^[0-9a-fA-F.+\-]$/.test(key);
}
function focusScreen() {
screen.focus();
}
function syncInputFromState() {
input.value = calc.inputValue;
}
function editXWithKey(key) {
if (!calc.isEditing) {
pushEditingValueIfNeeded();
calc.isEditing = true;
calc.inputValue = '';
}
if (key === 'Backspace') {
calc.inputValue = calc.inputValue.slice(0, -1);
} else {
calc.inputValue += key;
}
if (calc.inputValue === '') {
calc.isEditing = false;
}
syncInputFromState();
}
screen.addEventListener('keydown', (event) => {
try {
if (event.key === 'Enter') {
event.preventDefault();
execute('enter');
return;
}
if (event.key === 'Backspace') {
event.preventDefault();
if (calc.isEditing) {
editXWithKey('Backspace');
render();
}
return;
}
if (isInputChar(event.key)) {
event.preventDefault();
editXWithKey(event.key);
render();
return;
}
const keyMap = {
'+': 'add',
'-': 'sub',
'*': 'mul',
'/': 'div',
'%': 'mod',
'^': 'pow',
};
if (keyMap[event.key]) {
event.preventDefault();
execute(keyMap[event.key]);
}
} catch (error) {
errorEl.textContent = error.message;
}
});
screen.addEventListener('click', focusScreen);
window.addEventListener('load', focusScreen);
angleMode.addEventListener('change', (event) => {
calc.angleMode = event.target.value;
render();
});
addButtons(document.getElementById('stackButtons'), groups.stack);
addButtons(document.getElementById('arithButtons'), groups.arithmetic);
addButtons(document.getElementById('trigButtons'), groups.trig);
addButtons(document.getElementById('constButtons'), groups.const);
render();
focusScreen();
</script>
</body>
</html>
-308
View File
@@ -1,308 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>RPN Calculator Demo</title>
<style>
:root {
color-scheme: light dark;
--bg: #f4f4f4;
--panel: #ffffff;
--text: #111;
--muted: #666;
--button: #e9e9e9;
--button-text: #111;
--border: #d0d0d0;
--accent: #0a7;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #111;
--panel: #1a1a1a;
--text: #f3f3f3;
--muted: #aaa;
--button: #2a2a2a;
--button-text: #f3f3f3;
--border: #333;
--accent: #3dc;
}
}
body {
margin: 0;
font-family: Arial, sans-serif;
background: var(--bg);
color: var(--text);
}
.app {
max-width: 860px;
margin: 24px auto;
padding: 16px;
}
.card {
background: var(--panel);
border: 1px solid var(--border);
border-radius: 12px;
padding: 16px;
}
.display {
background: #000;
color: #0f0;
border-radius: 10px;
padding: 12px;
font-family: monospace;
min-height: 72px;
white-space: pre-wrap;
overflow-wrap: anywhere;
}
.grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(92px, 1fr));
gap: 8px;
margin-top: 12px;
}
button, select, input {
border: 1px solid var(--border);
background: var(--button);
color: var(--button-text);
border-radius: 8px;
padding: 10px 12px;
font-size: 15px;
}
button {
cursor: pointer;
}
input, select {
width: 100%;
box-sizing: border-box;
background: var(--panel);
color: var(--text);
font-size: 16px;
}
.row {
display: grid;
grid-template-columns: 1fr 180px;
gap: 12px;
margin-top: 12px;
align-items: end;
}
.stack {
margin-top: 12px;
font-family: monospace;
line-height: 1.5;
}
.muted {
color: var(--muted);
font-size: 14px;
}
.section-title {
margin: 16px 0 8px;
font-size: 14px;
color: var(--muted);
text-transform: uppercase;
letter-spacing: 0.04em;
}
.status {
display: flex;
gap: 12px;
flex-wrap: wrap;
margin-top: 12px;
color: var(--muted);
font-size: 14px;
}
.badge {
border: 1px solid var(--border);
border-radius: 999px;
padding: 4px 10px;
background: rgba(0, 0, 0, 0.04);
}
.accent {
color: var(--accent);
}
</style>
</head>
<body>
<div class="app">
<div class="card">
<h1>RPN Calculator Demo</h1>
<div id="display" class="display"></div>
<div id="stack" class="stack"></div>
<div class="row">
<label>
<div class="section-title">Input</div>
<input id="input" type="text" placeholder="Type a number, pi, e, or a command, then press Enter" autocomplete="off">
</label>
<label>
<div class="section-title">Angle mode</div>
<select id="angleMode">
<option value="deg">Degrees</option>
<option value="rad">Radians</option>
<option value="grad">Grads</option>
</select>
</label>
</div>
<div class="status">
<div class="badge">Mode: <span id="angleModeLabel" class="accent"></span></div>
<div class="badge">Base: <span id="baseLabel" class="accent"></span></div>
</div>
<div class="section-title">Constants</div>
<div class="grid">
<button data-const="pi">pi</button>
<button data-const="e">e</button>
</div>
<div class="section-title">Stack</div>
<div class="grid">
<button data-cmd="enter">Enter</button>
<button data-cmd="dup">Dup</button>
<button data-cmd="swap">Swap top 2</button>
<button data-cmd="drop">Drop</button>
<button data-cmd="clear">Clear</button>
</div>
<div class="section-title">Arithmetic</div>
<div class="grid">
<button data-cmd="add">+</button>
<button data-cmd="sub"></button>
<button data-cmd="mul">×</button>
<button data-cmd="div">÷</button>
<button data-cmd="mod">%</button>
<button data-cmd="pow">y^x</button>
<button data-cmd="sqr"></button>
<button data-cmd="neg">±</button>
<button data-cmd="sqrt">sqrt</button>
<button data-cmd="recip">1/x</button>
<button data-cmd="log">log</button>
<button data-cmd="ln">ln</button>
</div>
<div class="section-title">Trigonometry</div>
<div class="grid">
<button data-cmd="sin">sin</button>
<button data-cmd="cos">cos</button>
<button data-cmd="tan">tan</button>
<button data-cmd="asin">asin</button>
<button data-cmd="acos">acos</button>
<button data-cmd="atan">atan</button>
</div>
<p class="muted">Tip: trig functions follow the selected angle mode. Domain errors are reported with clear messages. sqrt computes the square root of the top stack value.</p>
</div>
</div>
<script src="../../src/rpn-calculator.js"></script>
<script>
const enabledCommands = ['add', 'sub', 'mul', 'div', 'mod', 'pow', 'sqr', 'neg', 'sqrt', 'recip', 'sin', 'cos', 'tan', 'asin', 'acos', 'atan', 'log', 'ln', 'dup', 'swap', 'drop', 'clear', 'enter'];
const calc = new RpnCalculator({ angleMode: 'deg', enabledCommands });
const display = document.getElementById('display');
const stack = document.getElementById('stack');
const input = document.getElementById('input');
const angleMode = document.getElementById('angleMode');
const angleModeLabel = document.getElementById('angleModeLabel');
const baseLabel = document.getElementById('baseLabel');
function render() {
display.textContent = calc.isEditing ? `Editing: ${calc.inputValue}` : 'Ready';
stack.innerHTML = calc.stack.length
? calc.stack.map((value, index) => `<div>${index}: ${value}</div>`).join('')
: '<span class="muted">Stack empty</span>';
angleMode.value = calc.angleMode;
angleModeLabel.textContent = calc.angleMode;
baseLabel.textContent = String(calc.base);
}
function commitInput() {
if (input.value.trim() !== '') {
calc.inputValue = input.value;
calc.isEditing = true;
calc.command('enter');
input.value = '';
}
}
function runCommand(name) {
if (name === 'swap') {
if (calc.stack.length >= 2) calc.swap(0, 1);
return;
}
if (name === 'enter') {
commitInput();
return;
}
calc.command(name);
}
input.addEventListener('input', (event) => {
calc.inputValue = event.target.value;
calc.isEditing = event.target.value.length > 0;
render();
});
input.addEventListener('keydown', (event) => {
if (event.key === 'Enter') {
event.preventDefault();
try {
commitInput();
render();
} catch (error) {
alert(error.message);
}
}
});
angleMode.addEventListener('change', (event) => {
calc.angleMode = ['deg', 'rad', 'grad'].includes(event.target.value) ? event.target.value : 'deg';
render();
});
document.querySelectorAll('button[data-cmd]').forEach((button) => {
button.addEventListener('click', () => {
try {
runCommand(button.dataset.cmd);
render();
} catch (error) {
alert(error.message);
}
});
});
document.querySelectorAll('button[data-const]').forEach((button) => {
button.addEventListener('click', () => {
try {
calc.inputValue = '';
calc.isEditing = false;
calc.command(button.dataset.const);
input.value = '';
render();
} catch (error) {
alert(error.message);
}
});
});
render();
</script>
</body>
</html>