rpnc/rpn.pod

=head1 NAME 

rpn - Reverse Polish Notation Calculator for the commandline

=head1 SYNOPSIS

    Usage: rpn [-bdvh] [<operator>]
    
    Options:
      -b, --batchmode   enable batch mode
      -d, --debug       enable debug mode
      -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 +

=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<quit> or  B<exit> or hit one of the  C<ctrl-d> or C<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 C<-b> or toggled using the interactive command
B<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.

=head2 STACK MANIPULATION

There are lots of stack manipulation commands provided. The most
important one is B<undo> which goes back to the stack before the last
math operation.

You can use B<dump> to display the stack. If debugging
is enabled (C<-d> switch or B<debug> toggle command), then the backup
stack is also being displayed.

The stack can be reversed using the B<reverse> command.

You can use the B<shift> command to remove the last number from the
stack.


=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 <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  C<add()> which  adds two  parameters. All
parameters are C<FLOAT64> numbers. You  don't have to worry about stack
management, this is taken care of automatically.

The function C<init()> B<MUST> be defined, it will be called on
startup. You can do anything you like in there, but you need to call
the C<register()> 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<https://www.lua.org/manual/5.4/> for more details about LUA.

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

=head1 GETTING HELP

In interactive mode you can enter the B<help> 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<manual> 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<man rpn>.

=head1 BUGS

In order to report a bug, unexpected behavior, feature requests
or to submit a patch, please open an issue on github:
L<https://github.com/TLINDEN/rpnc/issues>.

=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<tom AT vondein DOT org>

=cut