rpn - Programmable command-line calculator using reverse polish notation
Usage: rpn [-bdvh] [<operator>]
Options:
-b, --batchmode enable batch mode
-d, --debug enable debug mode
-s, --stack show last 5 items of the stack (off by default)
-i --intermediate print intermediate results
-m, --manual show manual
-c, --config <file> load <file> containing LUA code
-p, --precision <int> floating point number precision (default 2)
-v, --version show version
-h, --help show help
When <operator> is given, batch mode ist automatically enabled. Use
this only when working with stdin. E.g.: echo "2 3 4 5" | rpn +
rpn is a command line calculator using reverse polish notation.
Reverse Polish Notation (short: RPN) requires to have a stack where numbers and results are being put. So, you put numbers onto the stack and each math operation uses these for calculation, removes them and puts the result back.
To visualize it, let's look at a calculation:
((80 + 20) / 2) * 4
This is how you enter the formula int an RPN calculator and how the stack evolves during the operation:
| rpn commands | stack contents | calculation |
|--------------|----------------|---------------|
| 80 | 80 | |
| 20 | 80 20 | |
| + | 100 | 80 + 20 = 100 |
| 2 | 100 2 | |
| / | 50 | 100 / 2 = 50 |
| 4 | 50 4 | |
| x | 200 | 50 * 4 = 200 |
The last stack element 200 is the calculation result.
The default mode of operation is the interactive mode. You'll get a prompt which shows you the current size of the stack. At the prompt you enter numbers followed by operators or mathematical functions. You can use completion for the functions. You can either enter each number or operator on its own line or separated by whitespace, that doesn't matter. After a calculation the result will be immediately displayed (and added to the stack). You can quit interactive mode using the commands quit or exit or hit one of the ctrl-d
or ctrl-c
key combinations.
If you feed data to standard input (STDIN), rpn just does the calculation denoted in the contet fed in via stdin, prints the result and exits. You can also specify a calculation on the commandline.
Here are the three variants ($ is the shell prompt):
$ rpn
rpn> 2
rpn> 2
rpn> +
= 4
$ rpn
rpn> 2 2 +
= 4
$ echo 2 2 + | rpn
4
$ rpn 2 2 +
4
The rpn calculator provides a batch mode which you can use to do math operations on many numbers. Batch mode can be enabled using the commandline option -b
or toggled using the interactive command batch. Not all math operations and functions work in batch mode though.
Example of batch mode usage:
$ rpn -b
rpn->batch > 2 2 2 2 +
= 8
$ rpn
rpn> batch
rpn->batch> 2 2 2 2 +
8
$ echo 2 2 2 2 + | rpn -b
8
$ echo 2 2 2 2 | rpn +
8
If the first parameter to rpn is a math operator or function, batch mode is enabled automatically, see last example.
You can enter integers, floating point numbers (positive or negative) or hex numbers (prefixed with 0x).
There are lots of stack manipulation commands provided. The most important one is undo which goes back to the stack before the last math operation.
You can use dump to display the stack. If debugging is enabled (-d
switch or debug toggle command), then the backup stack is also being displayed.
The stack can be reversed using the reverse command. However, sometimes only the last two values are in the wrong order. Use the swap command to exchange them.
You can use the shift command to remove the last number from the stack.
Basic operators:
+ add
- subtract
/ divide
x multiply (alias: *)
^ power
Bitwise operators:
and bitwise and
or bitwise or
xor bitwise xor
< left shift
> right shift
Percent functions:
% percent
%- subtract percent
%+ add percent
Batch functions:
sum sum of all values (alias: +)
max max of all values
min min of all values
mean mean of all values (alias: avg)
median median of all values
Math functions:
mod sqrt abs acos acosh asin asinh atan atan2 atanh cbrt ceil cos cosh
erf erfc erfcinv erfinv exp exp2 expm1 floor gamma ilogb j0 j1 log
log10 log1p log2 logb pow round roundtoeven sin sinh tan tanh trunc y0
y1 copysign dim hypot
Conversion functions:
cm-to-inch
inch-to-cm
gallons-to-liters
liters-to-gallons
yards-to-meters
meters-to-yards
miles-to-kilometers
kilometers-to-miles
Configuration Commands:
[no]batch toggle batch mode (nobatch turns it off)
[no]debug toggle debug output (nodebug turns it off)
[no]showstack show the last 5 items of the stack (noshowtack turns it off)
Show commands:
dump display the stack contents
hex show last stack item in hex form (converted to int)
history display calculation history
vars show list of variables
Stack manipulation commands:
clear clear the whole stack
shift remove the last element of the stack
reverse reverse the stack elements
swap exchange the last two stack elements
dup duplicate last stack item
undo undo last operation
edit edit the stack interactively using vi or $EDITOR
Other commands:
help|? show this message
manual show manual
quit|exit|c-d|c-c exit program
Register variables:
>NAME Put last stack element into variable NAME
<NAME Retrieve variable NAME and put onto stack
Refer to https://pkg.go.dev/math for details about those functions.
There are also a number of shortcuts for some commands available:
d debug
b batch
s showstack
h history
p dump (aka print)
v vars
c clear
u undo
While you can use rpn in the command-line, the best experience you'll have is the interactive repl (read eval print loop). Just execute rpn
and you'll be there.
In interactive mode you can use TAB completion to complete commands, operators and functions. There's also a history, which allows you to repeat complicated calculations (as long as you've entered them in one line).
There are also a lot of key bindings, here are the most important ones:
- ctrl-c + ctrl-d
-
Exit interactive rpn
- ctrl-z
-
Send rpn to the backgound.
- ctrl-a
-
Beginning of line.
- ctrl-e
-
End of line.
- ctrl-l
-
Clear the screen.
- ctrl-r
-
Search through history.
Lines starting with #
are being ignored as comments. You can also append comments to rpn input, e.g.:
# a comment
123 # another comment
In this case only 123 will be added to the stack.
You can register the last item of the stack into a variable. Variable names must be all caps. Use the ">NAME" command to put a value into variable "NAME". Use "<NAME" to retrieve the value of variable "NAME" and put it onto the stack.
The command vars can be used to get a list of all variables.
You can use a lua script with lua functions to extend the calculator. By default the tool looks for ~/.rpn.lua
. You can also specify a script using the <kbd>-c</kbd> flag.
Here's an example of such a script:
function add(a,b)
return a + b
end
function init()
register("add", 2, "addition")
end
Here we created a function add()
which adds two parameters. All parameters are FLOAT64
numbers. You don't have to worry about stack management, this is taken care of automatically.
The function init()
MUST be defined, it will be called on startup. You can do anything you like in there, but you need to call the register()
function to register your functions to the calculator. This function takes these parameters:
function name
number of arguments expected (see below)
Number of expected arguments can be:
- 0: expect 1 argument but do NOT modify the stack - 1-n: do a singular calculation - -1: batch mode work with all numbers on the stack
help text
Please refer to the lua language reference: https://www.lua.org/manual/5.4/ for more details about LUA.
Please note, that io, networking and system stuff is not allowed though. So you can't open files, execute other programs or open a connection to the outside!
rpn can be configured via command line flags (see usage above). Most of the flags are also available as interactive commands, such as --batch
has the same effect as the batch command.
The floating point number precision option -p, --precision
however is not available as interactive command, it MUST be configured on the command line, if needed. The default precision is 2.
In interactive mode you can enter the help command (or ?) to get a short help along with a list of all supported operators and functions.
To read the manual you can use the manual command in interactive mode. The commandline option -m
does the same thing.
If you have installed rpn as a package or using the distributed tarball, there will also be a manual page you can read using man rpn
.
In order to report a bug, unexpected behavior, feature requests or to submit a patch, please open an issue on github: https://github.com/TLINDEN/rpnc/issues.
This software is licensed under the GNU GENERAL PUBLIC LICENSE version 3.
Copyright (c) 2023-2024 by Thomas von Dein
This software uses the following GO modules:
- readline (github.com/chzyer/readline)
-
Released under the MIT License, Copyright (c) 2016-2023 ChenYe
- pflag (https://github.com/spf13/pflag)
-
Released under the BSD 3 license, Copyright 2013-2023 Steve Francia
- gopher-lua (github.com/yuin/gopher-lua)
-
Released under the MIT License, Copyright (c) 2015-2023 Yusuke Inuzuka
Thomas von Dein tom AT vondein DOT org