# Reverse Polish Notation Calculator
## Versions
| 1.0.0 | 06-Mar-2024 | Initial version. |
| 1.1.0 | 20-May-2024 | Import values and operations from file with `import` directive or `--import` option. |
| | | Export results to file with `export` directive. |
| | | Define custom functions with `define` directive. |
| | | Sum values in batch mode with `--sum` option. |
| | | Correct floating point errors by rounding to nearest repeating decimal. |
| 1.2.0 | 05-Jun-2024 | Parse and format hexadecimal as `0x89ab`. |
| | | Export hexadecimal in batch mode with `--hex` option. |
| | | Export no separators in batch mode or with `export` directive. |
| 1.3.0 | 15-Mar-2025 | Format and parse time (already in UTC) with "Z". |
| | | Format hexadecimal with commas not underscores. |
| | | Export separators in batch mode with `--sep` option. |
| | | Export precision in batch mode with `--dp` option. |
## Introduction
RPN is a command line reverse Polish notation calculator. As such, it pushes integer and fractional numbers onto a stack, and pops them off for operations, running in interactive mode:
```
$ rpn
rpn> 6 7
rpn> show
6
7
rpn> mul
42
```
It accepts input from files supplied on the command line, running in batch mode:
```
$ cat input.txt
6 7
mul
$ rpn input.txt
42
```
It accepts input from a POSIX shell command pipeline, running in batch mode:
```
```
It writes output to a POSIX shell command pipeline, running in batch mode:
```
$ rpn >output.txt
6 7
mul
$ cat output.txt
42
```
Feature requests are welcome, but it's a hobby project in a language I don't get to use in my day job, so I prefer to do all the development myself.
## Program Options
The `-c` or `--command` option accepts input directly from the command line:
```
$ rpn --command 6 7 mul
42
```
The `--import` option imports values and operations from a text file. This can be used for commonly used custom functions:
```
$ cat defines.txt
define cube 3 pow
define percent 100 div
$ rpn --import defines.txt
rpn> 2 cube
8
```
The `--sum` option causes all results to be summed, if running in batch mode:
```
$ cat numbers.txt
1 2 3 4 5
$ rpn --sum numbers.txt
15
$ rpn --sum --command 1 2 3 4 5
15
```
The `--hex` option causes results to be printed in hexadecimal, if running in batch mode:
```
$ rpn --hex --command 10 10 mul
0x00000064
```
The `--sep` option causes results to be printed with separators, if running in batch mode:
```
$ rpn --sep --command 10 10 pow
10,000,000,000
```
## Program Features
Some operations are binary like `add` and `mul`, some are unary like `neg` and `inv`, some are nullary like `now`, while others operate on the entire stack like `sum` and `prod`. Inline help provides a hint on expected inputs and outputs:
```
rpn> help
Arithmetic operations:
N N add,+ N Add two values
N N sub,- N Subtract two values
N N mul,* N Multiply two values
N N div,/ N Divide two values
N N mod,% N Modulo two values
N neg N Find the negative
N inv N Find the inverse
N N pow N Raise to the power
N sqrt N Find the square root
* sum N Sum all values
* prod N Multiply all values
Bitwise operations:
N N and N Bitwise AND two values
N N or N Bitwise OR two values
N N xor N Bitwise XOR two values
N N shl N Shift left (multiply by power of 2)
N N shr N Shift right (divide by power of 2)
Time operations:
now N Get the current time
N plain N Convert to a plain value
N delta N Convert to a delta value
N time N Convert to a time value
Formatting commands:
dec Format values as decimal
hex Format values as hexadecimal
sep Include a separator
nosep Include no separator
N dp Use fixed decimal places
nodp Use free decimal places
Stack commands:
* c(lear) Remove all values from the stack
N p(op) Remove a value from the stack
N d(up) N N Duplicate a value on the stack
N N s(wap) N N Swap two values on the stack
N cut Cut a value to the internal clipboard
N copy N Copy a value to the internal clipboard
paste N Paste a value from the internal clipboard
History commands:
u(ndo) Undo the last operation
r(edo) Redo the next operation
h(ist) Show all undo/redo history
General directives:
import F Import file (expect filename)
export F Export file (expect filename)
define K * Define function (expect keyword then values and operations)
General commands:
show Show all values on the stack
help Show this help text
```
### Arithmetic Operations
The `add` operation adds two values:
```
rpn> 5.5 2.5 show
5.5
2.5
rpn> add
8
```
The `sub` operation subtracts two values:
```
rpn> 5.5 2.5 show
5.5
2.5
rpn> sub
3
```
The `mul` operation multiplies two values:
```
rpn> 5.5 2.5 show
5.5
2.5
rpn> mul
13.75
```
The `div` operation divides two values:
```
rpn> 5.5 2.5 show
5.5
2.5
rpn> div
2.2
```
The `mod` operation divides two values and finds the remainder:
```
rpn> 5.5 2.5 show
5.5
2.5
rpn> mod
0.5
```
The `neg` operation finds the negative:
```
rpn> 8 show
8
rpn> neg
-8
```
The `inv` operation finds the inverse:
```
rpn> 8 show
8
rpn> inv
0.125
```
The `pow` operation raises to the power:
```
rpn> 3 4 show
3
4
rpn> pow
81
```
The `sqrt` operation finds the square root:
```
rpn> 100 show
100
rpn> sqrt
10
```
The `sum` operation sums all values on the stack:
```
rpn> 1 2 3 4 5 show
1
2
3
4
5
rpn> sum
15
```
The `prod` operation multiplies all values on the stack:
```
rpn> 1 2 3 4 5 show
1
2
3
4
5
rpn> prod
120
```
#### Fractional Representation and Floating Point Errors
RPN uses big fractions for all operations, except when calculating square roots or other fractional powers, when it converts the arguments to floating point. In order to avoid floating point errors, it rounds all results to the nearest repeating decimal. Without this feature, the final result would be something like "2.000000000000000273...":
```
rpn> 2 sqrt
1.4142135623730951454746218587388284504413604736328125
rpn> dup mul
2
```
### Bitwise Operations
The `and` operation performs a bitwise AND on all bits:
```
rpn> 0xffff 0xff00ff hex
0x0000ffff
0x00ff00ff
rpn> and
0x000000ff
```
The `or` operation performs a bitwise OR on all bits:
```
rpn> 0xffff 0xff00ff hex
0x0000ffff
0x00ff00ff
rpn> or
0x00ffffff
```
The `xor` operation performs a bitwise XOR on all bits:
```
rpn> 0xffff 0xff00ff hex
0x0000ffff
0x00ff00ff
rpn> xor
0x00ffff00
```
The `shl` operation shifts left, i.e. multiplies by a power of 2:
```
rpn> 16 4 show
16
4
rpn> shl
256
```
The `shr` operation shifts right, i.e. divides by a power of 2:
```
rpn> 16 4 show
16
4
rpn> shr
1
```
### Time Operations
The `now` command gets the current time, showing times in UTC:
```
rpn> now
2025-03-31T12:34:56.789Z
```
The `plain` command converts to an integer or fractional value:
```
rpn> now
2025-03-31T12:34:56.789Z
rpn> plain
1743424496.789
```
The `delta` command converts to a delta value, optionally showing days, hours, minutes, seconds and milliseconds:
```
rpn> 86399 show
86399
rpn> delta
23:59:59.000
```
The `time` command converts to a time value, showing times in UTC:
```
rpn> 1709294400 show
1709294400
rpn> time
2024-03-01T12:00:00.000Z
```
Delta values can be added to or subtracted from times:
```
rpn> 1709294400 time 86400 delta
2024-03-01T12:00:00.000Z
1T00:00:00.000
rpn> sub
2024-02-29T12:00:00.000Z
```
One time value can be subtracted from another:
```
rpn> 1709294400 time 1709208000 time
2024-03-01T12:00:00.000Z
2024-02-29T12:00:00.000Z
rpn> sub
1T00:00:00.000
```
### Formatting Commands
The `dec` and `hex` commands format values as decimal and hexadecimal:
```
rpn> 2 32 pow hex
0x0000000100000000
rpn> dec
4294967296
```
The `sep` and `nosep` commands show and hide separators for decimal and hexadecimal:
```
rpn> 2 32 pow hex sep
0x,00000001,00000000
rpn> dec
4,294,967,296
```
The `dp` and `nodp` commands set and cancel fixed precision for decimal:
```
rpn> 2 sqrt
1.4142135623730951454746218587388284504413604736328125
rpn> 0 dp
1
rpn> 3 dp
1.414
rpn> 6 dp
1.414214
rpn> nodp
1.4142135623730951454746218587388284504413604736328125
```
### Stack Commands
The `clear` command removes all values from the stack:
```
rpn> 1 23 456 show
1
23
456
rpn> clear
```
The `pop` command removes a value from the stack:
```
rpn> 1 23 456 show
1
23
456
rpn> pop
1
23
```
The `dup` command duplicates a value on the stack:
```
rpn> 1 23 456 show
1
23
456
rpn> dup
1
23
456
456
```
The `swap` command swaps two values on the stack:
```
rpn> 1 23 456 show
1
23
456
rpn> swap
1
456
23
```
The `cut` and `copy` commands store a value from the stack in the internal clipboard. The `paste` command copies that value back to the stack:
```
rpn> 1 23 show
1
23
rpn> copy
rpn> 456 show
1
23
456
rpn> paste
1
23
456
23
```
### History Commands
The `undo` and `redo` commands undo the last operation, and redo the next operation in the history:
```
rpn> 1 23 456 show
1
23
456
rpn> prod
10488
rpn> undo
1
23
456
rpn> undo
rpn> undo
Start of undo history
rpn> redo
1
23
456
rpn> redo
10488
rpn> redo
End of undo history
```
The `hist` command shows all undo history:
```
rpn> 1 23 456 show
1
23
456
rpn> prod
10488
rpn> undo
1
23
456
rpn> hist
1 23 456
<==
prod
```
### General Directives
The `import` directive imports values and operations from a text file; the `export` directive exports values to a text file. The following creates a file containing the result of the multiplication:
```
rpn> import params.txt
6
7
rpn> mul
42
rpn> export result.txt
```
The `define` directive defines a custom function for subsequent use:
```
rpn> define cube 3 pow
rpn> 2 cube
8
```
Custom functions are added to the inline help:
```
rpn> define cube 3 pow
rpn> define percent 100 div
rpn> help
...
General commands:
show Show all values on the stack
help Show this help text
Defined functions:
cube Function "3 pow"
percent Function "100 div"
```
### Comments
It is possible to add a comment to any entered value, or the result of a calculation. Comments remain attached to their values until replaced, and are copied to duplicated values:
```
rpn> 6 7
rpn> mul # the answer
42 # the answer
rpn> dup
42 # the answer
42 # the answer
rpn> # the ultimate answer
42 # the answer
42 # the ultimate answer
```