scip/rpnc
1
0
Fork 0
mirror of https://codeberg.org/scip/rpnc.git synced 2025-12-17 04:21:01 +01:00
Code Issues Packages Projects Releases Wiki Activity

deprecate perl version, make go version the new one (2.0.0)

Browse Source
This commit is contained in:
Thomas von Dein
2023-11-01 17:55:22 +01:00
parent 19b8aa7883
commit 093591314a
15 changed files with 1157 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
README.md
View File

@@ -4,95 +4,87 @@ This is a small commandline calculator which takes its input in
[reverse polish notation](https://en.wikipedia.org/wiki/Reverse_Polish_notation)
form.
It has an unlimited stack, supports various stack manipulation
commands, can be used interactively or via a pipe and has a collector
mode. It doesn't have any other dependencies than Perl.
Features:
- unlimited stack
- undo
- various stack manipulation commands
- basic math operators
- advanced math functions (not yet complete)
- provides interactive repl
- can be used on the commandline
- can calculate data in batch mode (also from STDIN)
- extensible with custom LUA functions
## Usage
Calculate the summary resistance of parallel resistors with 220, 330
and 440 Ohm using the following formula:
Basically you enter numbers followed by an operator or a
function. Each number you enter will be put into the stack. Say you
entered two numbers, 2 and 4. If you now enter the `+` operator, those
two numbers will be removed from the stack, added and the result will
be put back onto the stack.
Here's a comprehensive example: calculate the summary resistance of
parallel resistors with 220, 330 and 440 Ohm using the following
formula:
1 / (1/R1 + 1/R2 + 1/R3)
Here's the sample session:
0 % 1
stack 1: 1
1 % 1
stack 2: 1
stack 1: 1
2 % 220
stack 3: 1
stack 2: 1
stack 1: 220
3 % /
stack 2: 1
stack 1: 0.00454545454545455
=> 0.00454545454545455
2 % 1
stack 3: 1
stack 2: 0.00454545454545455
stack 1: 1
3 % 330
stack 4: 1
stack 3: 0.00454545454545455
stack 2: 1
stack 1: 330
4 % /
stack 3: 1
stack 2: 0.00454545454545455
stack 1: 0.00303030303030303
=> 0.00303030303030303
3 % 1
stack 4: 1
stack 3: 0.00454545454545455
stack 2: 0.00303030303030303
stack 1: 1
4 % 440
stack 5: 1
stack 4: 0.00454545454545455
stack 3: 0.00303030303030303
stack 2: 1
stack 1: 440
5 % /
stack 4: 1
stack 3: 0.00454545454545455
stack 2: 0.00303030303030303
stack 1: 0.00227272727272727
=> 0.00227272727272727
4 % +
stack 3: 1
stack 2: 0.00454545454545455
stack 1: 0.0053030303030303
=> 0.0053030303030303
3 % +
stack 2: 1
stack 1: 0.00984848484848485
=> 0.00984848484848485
2 % /
stack 1: 101.538461538462
=> 101.538461538462
```
rpn [0]» 1
rpn [1]» 1 220 /
= 0.004545454545454545
rpn [2]» 1 330 /
= 0.0030303030303030303
rpn [3]» 1 440 /
= 0.0022727272727272726
rpn [4]» +
= 0.0053030303030303025
rpn [3]» +
= 0.009848484848484848
rpn [2]» /
= 101.53846153846155
```
The *%* character denotes the interactive prompt. What we basically entered was:
It doesn't matter wether you enter numbers and operators/function on
the same line or separated by whitespace:
```
rpn [0]» 1 1 220 / 1 330 / 1 440 / + + /
= 0.004545454545454545
= 0.0030303030303030303
= 0.0022727272727272726
= 0.0053030303030303025
= 0.009848484848484848
= 101.53846153846155
```
Works on the commandline as well:
```
rpn 1 1 220 / 1 330 / 1 440 / + + /
0.004545454545454545
0.0030303030303030303
0.0022727272727272726
0.0053030303030303025
0.009848484848484848
101.53846153846155
```
And via STDIN:
```
echo "1 1 220 / 1 330 / 1 440 / + + /" | rpn
0.004545454545454545
0.0030303030303030303
0.0022727272727272726
0.0053030303030303025
0.009848484848484848
101.53846153846155
```
What we basically entered was:
1 1 220 / 1 330 / 1 440 / + + /
@@ -103,13 +95,15 @@ Which translates to:
So, you're entering the numbers and operators as you would do on
paper. To learn more, refer to the Wikipedia page linked above.
## Collector mode
## Batch mode
Beside traditional RPN you can also enter a special mode, called
*collector mode* by entering the <kbd>(</kbd> command. The collector
mode has its own stack (a sub stack) which is independed of the
primary stack. Inside this mode you can use all operators, however
they work on *ALL* items on the sub stack.
*batch mode* either by entering the `batch` command or using the
commandline switch <kbd>-b</kbd>.
Most operators and functions can be used with batch mode but not
all. In this mode the calculation works on all numbers on the stack so
far.
So, let's compare. If you had in normal RPN mode the following stack:
@@ -117,148 +111,102 @@ So, let's compare. If you had in normal RPN mode the following stack:
5
6
and then entering the <kbd>+</kbd> operator, the calculator would pop
5 and 6 from the stack, add them and push the result 11 back to the
and then enter the <kbd>+</kbd> operator, the calculator would pop 5
and 6 from the stack, add them and push the result 11 back to the
stack.
However, if you are in collector mode with this stack, then all the
items would be added, the sub stack would be cleared and the result 14
would be added to the primary stack.
However, if you are in collector mode, then all the items would be
added, the sub stack would be cleared and the result 14 would be added
to the stack.
You will leave the collector mode after an operator has been
executed. But you can also just leave the collector mode with the
command <kbd>)</kbd> leaving the sub stack intact. That is, upon
re-entering collector mode at a later time, you'll find the unaltered
sub stack of before.
To leave batch mode just enter the `batch` command again (this is a
toggle).
Here's an example using a math function:
echo 1 2 3 4 5 6 7 | rpn -b median
4
Really simple.
## Undo
Every operation which modifies the stack can be reversed by entering
the <kbd>u</kbd> command. There's only one level of undo and no redo.
the `undo` command. There's only one level of undo and no redo.
## Functions
## Extend the calculator with LUA functions
You can define functions anytime directly on the cli or in a file called
`~/.rpnc`. A function has a name (which must not collide with existing
functions and commands) and a body of commands.
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.
Example:
Here's an example of such a script:
f res2vcc 1.22 R1 R2 + R2 / 1 + *
```lua
function add(a,b)
return a + b
end
Which calculates:
function init()
register("add", 2, "addition")
end
```
(((R1 + R2) / R2) + 1) * 1.22 = ??
To use it later, just enter the variables into the stack followed by the
function name:
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.
470
220
res2vcc
=> 2.79
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:
You can also put the function definition in the config file
`~/.rpnc`. Empty lines and lines beginning with `#` will be ignored.
- function name
- number of arguments expected (1,2 or -1 allowed), -1 means batch
mode
- help text
Another way to define a function is to use perl code directly. The
perl code must be a closure string and surrounded by braces. You can
access the stack via `@_`. Here's an example:
Please [refer to the lua language
reference](https://www.lua.org/manual/5.4/** for more details about
LUA.
f pr { return "1.0 / (" . join(' + ', map { "1.0 / $_"} @_) . ")" }
This function calculates the parallel resistance of a number of
resistors. It adds up all values from the stack. Usage:
**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!**
22
47
330
pr
=> 41.14
## Documentation
The documentation is provided as a unix man-page. It will be
automatically installed if you install from source. However, you can
read the man-page online:
## Using STDIN via a PIPE
https://github.com/TLINDEN/rpnc/blob/main/rpn.pod
If the commandline includes any operator, commands will be read from
STDIN, the result will be printed to STDOUT wihout any decoration and
the program will exit. Commands can be separated by whitespace or
newline.
Or if you cloned the repository you can read it this way (perl needs
to be installed though): `perldoc rpn.pod`.
Examples:
If you have the binary installed, you can also read the man page with
this command:
echo "2 2" | rpnc +
(echo 2; echo 2) | rpnc +
Both commands will print 4 to STDOUT.
rpn --man
## Getting help
## Complete list of all supported commands:
Although I'm happy to hear from rpn users in private email, that's the
best way for me to forget to do something.
### Stack Management
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.
* <kbd>s</kbd> show the stack
* <kbd>ss</kbd> show the whole stack
* <kbd>sc</kbd> clear stack
* <kbd>scx</kbd> clear last stack element
* <kbd>sr</kbd> reverse the stack
* <kbd>srt</kbd> rotate the stack
## Copyright and license
## Configuration
This software is licensed under the GNU GENERAL PUBLIC LICENSE version 3.
* <kbd>td</kbd> toggle debugging (-d)
* <kbd>ts</kbd> toggle display of the stack (-n)
## Authors
## Supported mathematical operators:
T.v.Dein <tom AT vondein DOT org>
* <kbd>+</kbd> add
* <kbd>-</kbd> substract
* <kbd>/</kbd> divide
* <kbd>*</kbd> multiply
* <kbd>^</kbd> expotentiate
* <kbd>%</kbd> percent
* <kbd>%+</kbd> add percent
* <kbd>%-</kbd> substract percent
* <kbd>%d</kbd> percentual difference
* <kbd>&</kbd> bitwise AND
* <kbd>|</kbd> bitwise OR
* <kbd>x</kbd> bitwise XOR
* <kbd>m</kbd> median
* <kbd>a</kbd> average
* <kbd>v</kbd> pull root (2nd if stack==1)
* <kbd>(</kbd> enter collect mode
* <kbd>)</kbd> leave collect mode
## Project homepage
## Register Commands
* <kbd>r</kbd> put element into register
* <kbd>rc</kbd> clear register
* <kbd>rcx</kbd> clear last register element
## Various Commands
* <kbd>u</kbd> undo last operation
* <kbd>q</kbd> finish (<kbd>C-d</kbd> works as well)
* <kbd>h</kbd> show history of past operations
* <kbd>?</kbd> print help
## Converters
* <kbd>tl</kbd> gallons to liters
* <kbd>tk</kbd> miles to kilometers
* <kbd>tm</kbd> yards to meters
* <kbd>tc</kbd> inches to centimeters
* <kbd>tkb</kbd> bytes to kilobytes
* <kbd>tmb</kbd> bytes to megabytes
* <kbd>tgb</kbd> bytes to gigabytes
* <kbd>ttb</kbd> bytes to terabytes
## Function Comands
* <kbd>f NAME CODE</kbd> define a functions (see ab above)
* <kbd>fs</kbd> show list of defined functions
## Copyleft
Copyleft (L) 2019 - Thomas von Dein.
Licensed under the terms of the GPL 3.0.
https://github.com/TLINDEN/rpnc