rpnc/rpn.pod

=head1 NAME 

rpn - Programmable command-line calculator using reverse polish notation

=head1 SYNOPSIS

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

You can enter integers, floating  point numbers (positive or negative)
or hex numbers (prefixed with 0x).

=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.  However,
sometimes only  the last two  values are in  the wrong order.  Use the
B<swap> command to exchange them.

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

=head2 BUILTIN OPERATORS AND FUNCTIONS

Basic operators:

    +                    add
    -                    substract
    /                    divide
    x                    multiply (alias: *)
    ^                    power

Bitwise operators:

    and                  bitwise and
    or                   bitwise or
    xor                  bitwise xor
    <                    left shift
    >                    right shift

Percent functions:

    %                    percent
    %-                   substract 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

=head1 INTERACTIVE REPL

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

=over

=item ctrl-c + ctrl-d

Exit interactive rpn

=item ctrl-z

Send rpn to the backgound.

=item ctrl-a

Beginning of line.

=item ctrl-e

End of line.

=item ctrl-l

Clear the screen.

=item ctrl-r

Search through history.

=back

=head1 COMMENTS

Lines starting with  C<#> 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.

=head1 VARIABLES

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 B<vars> can be used to get a list of all variables.

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

=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