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

added manpage and manpage display commands

Browse Source
This commit is contained in:
Thomas von Dein
2023-11-02 10:11:39 +01:00
parent 89f3669512
commit f86c4c9951
7 changed files with 528 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1,2 +1,3 @@
releases
rpn
rpn.1

21
Makefile
View File

@@ -23,8 +23,27 @@ archs = darwin freebsd linux windows
PREFIX = /usr/local
UID = root
GID = 0
HAVE_POD := $(shell pod2text -h 2>/dev/null)
all: buildlocal
all: $(tool).1 $(tool).go buildlocal
%.1: %.pod
ifdef HAVE_POD
pod2man -c "User Commands" -r 1 -s 1 $*.pod > $*.1
endif
%.go: %.pod
ifdef HAVE_POD
echo "package main" > $*.go
echo >> $*.go
echo "var manpage = \`" >> $*.go
pod2text $*.pod >> $*.go
echo "\`" >> $*.go
echo "var usage = \`" >> $*.go
awk '/SYNOPS/{f=1;next} /DESCR/{f=0} f' $*.pod | sed 's/^ //' >> $*.go
echo "\`" >> $*.go
endif
buildlocal:
CGO_LDFLAGS='-static' go build -tags osusergo,netgo -ldflags "-extldflags=-static" -o $(tool)

49
README.md
View File

@@ -16,6 +16,55 @@ Features:
- can calculate data in batch mode (also from STDIN)
- extensible with custom LUA functions
## 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. This is how it looks with debugging enabled in `rpn`:
```
rpn->debug [0/rev0]» 80 20 + 2 / 4 x
DEBUG(000): push to stack: 80.00
DEBUG(001): push to stack: 20.00
DEBUG(002): remove from stack: 20.00
DEBUG(003): remove from stack: 80.00
DEBUG(calc): evaluating: 80.00 + 20.00
DEBUG(004): push to stack: 100.00
= 100
DEBUG(005): push to stack: 2.00
DEBUG(006): remove from stack: 2.00
DEBUG(007): remove from stack: 100.00
DEBUG(calc): evaluating: 100.00 / 2.00
DEBUG(008): push to stack: 50.00
= 50
DEBUG(009): push to stack: 4.00
DEBUG(010): remove from stack: 4.00
DEBUG(011): remove from stack: 50.00
DEBUG(calc): evaluating: 50.00 x 4.00
DEBUG(012): push to stack: 200.00
= 200
```
## Usage
Basically you enter numbers followed by an operator or a

6
calc.go
View File

@@ -76,9 +76,9 @@ Math operators:
// commands, constants and operators, defined here to feed completion
// and our mode switch in Eval() dynamically
const (
Commands string = `dump reverse debug undebug clear batch shift undo help history exit quit`
Commands string = `dump reverse debug undebug clear batch shift undo help history manual exit quit`
Operators string = `+ - * x / ^ % %- %+`
MathFunctions string = `sqrt remainder avg mean min max median`
MathFunctions string = `sqrt remainder`
Constants string = `Pi Phi Sqrt2 SqrtE SqrtPi SqrtPhi Ln2 Log2E Ln10 Log10E`
BatchFunctions string = `median avg mean max min`
)
@@ -255,6 +255,8 @@ func (c *Calc) Eval(line string) {
fallthrough
case "quit":
os.Exit(0)
case "manual":
man()
default:
fmt.Println("unknown command or operator!")
}

28
main.go
View File

@@ -18,8 +18,11 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
package main
import (
"bytes"
"fmt"
"log"
"os"
"os/exec"
"strings"
"github.com/chzyer/readline"
@@ -36,6 +39,7 @@ Usage: rpn [-bdvh] [<operator>]
Options:
-b, --batchmode enable batch mode
-d, --debug enable debug mode
-m, --manual show manual
-v, --version show version
-h, --help show help
@@ -49,6 +53,7 @@ func main() {
showversion := false
showhelp := false
showmanual := false
enabledebug := false
configfile := ""
@@ -56,6 +61,7 @@ func main() {
flag.BoolVarP(&enabledebug, "debug", "d", false, "debug mode")
flag.BoolVarP(&showversion, "version", "v", false, "show version")
flag.BoolVarP(&showhelp, "help", "h", false, "show usage")
flag.BoolVarP(&showmanual, "manual", "m", false, "show manual")
flag.StringVarP(&configfile, "config", "c",
os.Getenv("HOME")+"/.rpn.lua", "config file (lua format)")
@@ -75,6 +81,11 @@ func main() {
calc.ToggleDebug()
}
if showmanual {
man()
os.Exit(0)
}
// the lua state object is global, instanciate it early
L = lua.NewState(lua.Options{SkipOpenLibs: true})
defer L.Close()
@@ -141,3 +152,20 @@ func inputIsStdin() bool {
stat, _ := os.Stdin.Stat()
return (stat.Mode() & os.ModeCharDevice) == 0
}
func man() {
man := exec.Command("less", "-")
var b bytes.Buffer
b.Write([]byte(manpage))
man.Stdout = os.Stdout
man.Stdin = &b
man.Stderr = os.Stderr
err := man.Run()
if err != nil {
log.Fatal(err)
}
}

206
rpn.go Normal file
View File

@@ -0,0 +1,206 @@
package main
var manpage = `
NAME
rpn - Reverse Polish Notation Calculator for the commandline
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 +
DESCRIPTION
rpn is a command line calculator using reverse polish notation.
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.
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 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.
STACK MANIPULATION
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.
You can use the shift command to remove the last number from the stack.
EXTENDING RPN USING LUA
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 (1,2 or -1 allowed), -1 means batch
mode.
* 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!
GETTING HELP
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".
BUGS
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>.
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:
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
AUTHORS
Thomas von Dein tom AT vondein DOT org
`
var usage = `
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 +
`

220
rpn.pod Normal file
View File

@@ -0,0 +1,220 @@
=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