Reverse Polish Notation Calculator

Versions

• 1.0.0
  • Initial version.
• 1.1.0
  • 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
  • Parse and format hexadecimal as 0x89ab.
  • Export hexadecimal in batch mode with --hex option.
  • Export no separators in batch mode or with export directive.

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 --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

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
  2024-03-02T11:37:15.724

The plain command converts to an integer or fractional value:

rpn> now
  2024-03-02T11:37:15.724
rpn> plain
  1709379435.724

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.000

Delta values can be added to or subtracted from times:

rpn> 1709294400 time 86400 delta
  2024-03-01T12:00:00.000
           1:00:00:00.000
rpn> sub
  2024-02-29T12:00:00.000

One time value can be subtracted from another:

rpn> 1709294400 time 1709208000 time
  2024-03-01T12:00:00.000
  2024-02-29T12:00:00.000
rpn> sub
  1:00: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. 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 (for example) copied to duplicated values:

rpn> 6 7
rpn> mul # the answer
  42 # the answer
rpn> dup
  42 # the answer
  42 # the answer
rpn> # deep thought
  42 # the answer
  42 # deep thought