Reverse Polish Notation Calculator

Versions

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:

$ seq 1 5 | rpn --sum
15

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
$ seq 1 5 | rpn --sum
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 hints 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
  Sequence operations:
    N N  seq     *    Generate integer sequence (start to stop)
      3  step    *    Generate integer sequence (start with step to stop)
      *  sort    *    Sort stack or sequence
      *  rev     *    Reverse stack or sequence
      *  flat    *    Flatten entire stack
  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 (in UTC)
      N  plain   N    Format as a plain value
      N  delta   N    Format as a delta value (duration)
      N  time    N    Format as a time value (in UTC)
  Formatting commands:
         dec          Format as decimal values
         hex          Format as hexadecimal values
         sep          Include comma separators
         nosep        Include no separators
      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...    Import file e.g. "import file.txt"
         export...    Export file e.g. "export file.txt"
         set,=...     Set variable, e.g. "set x"
         define...    Define function e.g. "define cube 3 pow"
         apply...     Apply to stack or sequence, e.g. "apply 3 pow"
  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

Sequence Operations

The seq operation creates increasing or decreasing sequences of values, popping the start and end values from the stack and generating a step of 1.0 or -1.0:

rpn> 1 5 seq
┌ 1 ┐
│ 2 │
│ 3 │
│ 4 │
└ 5 ┘

rpn> 5 1 seq
┌ 5 ┐
│ 4 │
│ 3 │
│ 2 │
└ 1 ┘

The step operation does the same thing, but pops the start, step and end values; new values are created with the same meaning (plain, delta or time) as the start value:

rpn> 0 0.2 1 step
┌ 0   ┐
│ 0.2 │
│ 0.4 │
│ 0.6 │
│ 0.8 │
└ 1   ┘

rpn> 0 delta 3600 18000 step
┌       00.000 ┐
│ 01:00:00.000 │
│ 02:00:00.000 │
│ 03:00:00.000 │
│ 04:00:00.000 │
└ 05:00:00.000 ┘

The sort operation sorts values on the stack, treating "not a number" values as lower than everything else:

rpn> 4 2 1 0 div 3 5 1
    4
    2
  NaN
    3
    5
    1
rpn> sort
  NaN
    1
    2
    3
    4
    5

The rev operation reverses values on the stack:

rpn> 1 2 3 4 5 show
  1
  2
  3
  4
  5
rpn> rev
  5
  4
  3
  2
  1

The flat operation flattens all sequences on the stack:

rpn> 1 5 seq 6 8 seq
┌ 1 ┐
│ 2 │
│ 3 │
│ 4 │
└ 5 ┘
┌ 6 ┐
│ 7 │
└ 8 ┘
rpn> flat
  1
  2
  3
  4
  5
  6
  7
  8

Special Behaviour for Value Sequences at Head of Stack

If the values at the head of the stack are part of a sequence, operations which would otherwise apply to the entire stack (such as prod and sort) instead apply to that sequence only:

rpn> 11 10 5 4 3 2 1 show
  11
  10
   5
   4
   3
   2
   1
rpn> sort
   1
   2
   3
   4
   5
  10
  11
rpn> prod
  13200

rpn> 11 10 5 1 seq show
  11
  10
┌  5 ┐
│  4 │
│  3 │
│  2 │
└  1 ┘
rpn> sort
  11
  10
┌  1 ┐
│  2 │
│  3 │
│  4 │
└  5 ┘
rpn> prod
   11
   10
  120

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> 0xff00 hex
  0x0000ff00
rpn> 8 shl
  0x00ff0000

The shr operation shifts right, i.e. divides by a power of 2:

rpn> 0xff00 hex
  0x0000ff00
rpn> 8 shr
  0x000000ff

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 set or = directive sets a named variable to the most recent entry on the stack:

rpn> 36 sqrt = x
  6 = x
rpn> 49 sqrt = y
  6 = x
  7 = y
rpn> x y mul
   6 = x
   7 = y
  42
rpn> set xy
   6 = x
   7 = y
  42 = xy

Multiple variables can be set on the same line, and variables can be listed with the set or = directive by itself:

rpn> 1 = one 2 = two 3 = three 4 = four 5 = five 6 7 8
  1 = one
  2 = two
  3 = three
  4 = four
  5 = five
  6
  7
  8
rpn> set
  5 = five
  4 = four
  1 = one
  3 = three
  2 = two

The define directive defines a custom function for subsequent use:

rpn> define cube 3 pow
rpn> 2 cube
  8

The define directive with a function name but no body undefines the function. The directive with no function name lists defined functions, with hints on expected inputs and outputs, and this information is also included in the inline help:

rpn> define cube 3 pow
rpn> define percent 100 div
rpn> define fubar 0 div
rpn> define fubar
rpn> define
  Defined functions:
      N  cube    N    Function "3 pow"
      N  percent N    Function "100 div"

The apply directive applies the same operation (or sequence of operations) to each value on the stack:

rpn> 1 2 3 4 5 show
  1
  2
  3
  4
  5
rpn> apply 3 pow
    1
    8
   27
   64
  125

Only operations which pop one input and push one output are allowed:

rpn> 1 2 3 4 5 show
  1
  2
  3
  4
  5
rpn> apply add
  Unsupported apply operation (must be unary)

Special Behaviour for Value Sequences at Head of Stack

Because sequence operations are applied to the sequence at the head of the stack, this can be used to define and run functions without affecting other values on the stack:

rpn> define fact 1 swap seq prod
rpn> 10 11 5 show
  10
  11
   5
rpn> fact
   10
   11
  120

rpn> define fact 1 swap seq prod
rpn> 10 11 1 5 seq
  10
  11
┌  1 ┐
│  2 │
│  3 │
│  4 │
└  5 ┘
rpn> apply fact
   10
   11
┌   1 ┐
│   2 │
│   6 │
│  24 │
└ 120 ┘

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