=head1 NAME rpn - Reverse Polish Notation Calculator for the commandline =head1 SYNOPSIS Usage: rpn [-bdvh] [] Options: -b, --batchmode enable batch mode -d, --debug enable debug mode -v, --version show version -h, --help show help When is given, batch mode ist automatically enabled. Use this only when working with stdin. E.g.: echo "2 3 4 5" | rpn + =head1 DESCRIPTION rpn is a command line calculator using reverse polish notation. =head2 Working principle 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. =head2 USAGE 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 B or B or hit one of the C or 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 C<-b> or toggled using the interactive command B. 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. =head2 STACK MANIPULATION There are lots of stack manipulation commands provided. The most important one is B which goes back to the stack before the last math operation. You can use B to display the stack. If debugging is enabled (C<-d> switch or B toggle command), then the backup stack is also being displayed. The stack can be reversed using the B command. You can use the B command to remove the last number from the stack. =head2 BUILTIN OPERATORS AND FUNCTIONS Basic operators: + - x / Math functions: sqrt square root mod remainder of division (alias: remainder) max batch mode only: max of all values min batch mode only: min of all values mean batch mode only: mean of all values (alias: avg) median batch mode only: median of all values % percent %- substract percent %+ add percent ^ power =head1 EXTENDING RPN USING LUA You can use a lua script with lua functions to extend the calculator. By default the tool looks for C<~/.rpn.lua>. You can also specify a script using the -c 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 C which adds two parameters. All parameters are C numbers. You don't have to worry about stack management, this is taken care of automatically. The function C B be defined, it will be called on startup. You can do anything you like in there, but you need to call the C function to register your functions to the calculator. This function takes these parameters: =over =item * function name =item * number of arguments expected (1,2 or -1 allowed), -1 means batch mode. =item * help text =back Please refer to the lua language reference: L for more details about LUA. B =head1 GETTING HELP In interactive mode you can enter the B command (or B) to get a short help along with a list of all supported operators and functions. To read the manual you can use the B command in interactive mode. The commandline option C<-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 C. =head1 BUGS In order to report a bug, unexpected behavior, feature requests or to submit a patch, please open an issue on github: L. =head1 LICENSE This software is licensed under the GNU GENERAL PUBLIC LICENSE version 3. Copyright (c) 2023 by Thomas von Dein This software uses the following GO modules: =over 4 =item readline (github.com/chzyer/readline) Released under the MIT License, Copyright (c) 2016-2023 ChenYe =item pflag (https://github.com/spf13/pflag) Released under the BSD 3 license, Copyright 2013-2023 Steve Francia =item gopher-lua (github.com/yuin/gopher-lua) Released under the MIT License, Copyright (c) 2015-2023 Yusuke Inuzuka =back =head1 AUTHORS Thomas von Dein B =cut