Merge pull request #17 from TLINDEN/feature/add-disable-swiches

added no versions of batch debug and showstack toggles

Makefile

@@ -57,8 +57,8 @@ test:
 	go test -v ./...
 
 singletest:
-	@echo "Call like this: ''make singletest TEST=TestPrepareColumns MOD=lib"
-	go test -run $(TEST) github.com/tlinden/rpn/$(MOD)
+	@echo "Call like this: ''make singletest TEST=TestPrepareColumns"
+	go test -run $(TEST)
 
 cover-report:
 	go test ./... -cover -coverprofile=coverage.out

README.md

@@ -15,10 +15,18 @@ Features:
 - 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
+- provides interactive repl
+- completion
+- history
+- comments (comment character is `#`)
+- variables
+
+## Demo
+
+![asciicast](demo/demo.gif)
 
 ## Working principle
 
@@ -217,10 +225,15 @@ 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
+- number of arguments expected (see below)
 - help text
 
+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 
+
 Please [refer to the lua language
 reference](https://www.lua.org/manual/5.4/) for more details about
 LUA.

calc.go

@@ -32,27 +32,36 @@ type Calc struct {
 	debug        bool
 	batch        bool
 	stdin        bool
+	showstack    bool
+	intermediate bool
+	notdone      bool // set to true as long as there are items left in the eval loop
 	stack        *Stack
 	history      []string
 	completer    readline.AutoCompleter
 	interpreter  *Interpreter
 	Space        *regexp.Regexp
+	Comment      *regexp.Regexp
+	Register     *regexp.Regexp
 	Constants    []string
 	LuaFunctions []string
 
 	Funcalls      Funcalls
 	BatchFuncalls Funcalls
+
+	Vars map[string]float64
 }
 
 // help for lua functions will be added dynamically
 const Help string = `Available commands:
-batch                toggle batch mode
-debug                toggle debug output
+batch                toggle batch mode (nobatch turns it off)
+debug                toggle debug output (nodebug turns it off)
+showstack            toggle show last 5 items of the stack (noshowtack turns it off)
 dump                 display the stack contents
 clear                clear the whole stack
 shift                remove the last element of the stack
 reverse              reverse the stack elements
 swap                 exchange the last two elements
+vars                 show list of variables
 history              display calculation history
 help|?               show this message
 quit|exit|c-d|c-c    exit program
@@ -76,12 +85,16 @@ 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`
+median               median of all values
+
+Register variables:
+>NAME                Put last stack element into variable NAME
+<NAME                Retrieve variable NAME and put onto stack`
 
 // 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 manual exit quit swap`
+	Commands  string = `dump reverse clear shift undo help history manual exit quit swap debug undebug nodebug batch nobatch showstack noshowstack vars`
 	Constants string = `Pi Phi Sqrt2 SqrtE SqrtPi SqrtPhi Ln2 Log2E Ln10 Log10E`
 )
 
@@ -123,6 +136,7 @@ func NewCalc() *Calc {
 
 	c.Funcalls = DefineFunctions()
 	c.BatchFuncalls = DefineBatchFunctions()
+	c.Vars = map[string]float64{}
 
 	c.completer = readline.NewPrefixCompleter(
 		// custom lua functions
@@ -131,20 +145,22 @@ func NewCalc() *Calc {
 	)
 
 	c.Space = regexp.MustCompile(`\s+`)
+	c.Comment = regexp.MustCompile(`#.*`) // ignore everything after #
+	c.Register = regexp.MustCompile(`^([<>])([A-Z][A-Z0-9]*)`)
 
 	// pre-calculate mode switching arrays
 	c.Constants = strings.Split(Constants, " ")
 
-	for name := range LuaFuncs {
-		c.LuaFunctions = append(c.LuaFunctions, name)
-	}
-
 	return &c
 }
 
-// setup the interpreter, called from main()
+// setup the interpreter, called from main(), import lua functions
 func (c *Calc) SetInt(I *Interpreter) {
 	c.interpreter = I
+
+	for name := range LuaFuncs {
+		c.LuaFunctions = append(c.LuaFunctions, name)
+	}
 }
 
 func (c *Calc) ToggleDebug() {
@@ -162,14 +178,21 @@ func (c *Calc) ToggleStdin() {
 	c.stdin = !c.stdin
 }
 
+func (c *Calc) ToggleShow() {
+	c.showstack = !c.showstack
+}
+
 func (c *Calc) Prompt() string {
 	p := "\033[31m»\033[0m "
 	b := ""
+
 	if c.batch {
 		b = "->batch"
 	}
+
 	d := ""
 	v := ""
+
 	if c.debug {
 		d = "->debug"
 		v = fmt.Sprintf("/rev%d", c.stack.rev)
@@ -180,13 +203,22 @@ func (c *Calc) Prompt() string {
 
 // the actual work horse, evaluate a line of calc command[s]
 func (c *Calc) Eval(line string) {
-	line = strings.TrimSpace(line)
+	// remove surrounding whitespace and comments, if any
+	line = strings.TrimSpace(c.Comment.ReplaceAllString(line, ""))
 
 	if line == "" {
 		return
 	}
 
-	for _, item := range c.Space.Split(line, -1) {
+	items := c.Space.Split(line, -1)
+
+	for pos, item := range items {
+		if pos+1 < len(items) {
+			c.notdone = true
+		} else {
+			c.notdone = false
+		}
+
 		num, err := strconv.ParseFloat(item, 64)
 
 		if err == nil {
@@ -227,7 +259,18 @@ func (c *Calc) Eval(line string) {
 
 			if contains(c.LuaFunctions, item) {
 				// user provided custom lua functions
-				c.luafunc(item)
+				c.EvalLuaFunction(item)
+				continue
+			}
+
+			regmatches := c.Register.FindStringSubmatch(item)
+			if len(regmatches) == 3 {
+				switch regmatches[1] {
+				case ">":
+					c.PutVar(regmatches[2])
+				case "<":
+					c.GetVar(regmatches[2])
+				}
 				continue
 			}
 
@@ -237,18 +280,25 @@ func (c *Calc) Eval(line string) {
 				fallthrough
 			case "help":
 				fmt.Println(Help)
-				fmt.Println("Lua functions:")
-				for name, function := range LuaFuncs {
-					fmt.Printf("%-20s %s\n", name, function.help)
+				if len(LuaFuncs) > 0 {
+					fmt.Println("Lua functions:")
+					for name, function := range LuaFuncs {
+						fmt.Printf("%-20s %s\n", name, function.help)
+					}
 				}
 			case "dump":
 				c.stack.Dump()
 			case "debug":
 				c.ToggleDebug()
+			case "nodebug":
+				fallthrough
 			case "undebug":
 				c.debug = false
+				c.stack.debug = false
 			case "batch":
 				c.ToggleBatch()
+			case "nobatch":
+				c.batch = false
 			case "clear":
 				c.stack.Backup()
 				c.stack.Clear()
@@ -271,17 +321,43 @@ func (c *Calc) Eval(line string) {
 				for _, entry := range c.history {
 					fmt.Println(entry)
 				}
+			case "showstack":
+				fallthrough
+			case "show":
+				c.ToggleShow()
+			case "noshowstack":
+				c.showstack = false
 			case "exit":
 				fallthrough
 			case "quit":
 				os.Exit(0)
 			case "manual":
 				man()
+			case "vars":
+				if len(c.Vars) > 0 {
+					fmt.Printf("%-20s     %s\n", "VARIABLE", "VALUE")
+					for k, v := range c.Vars {
+						fmt.Printf("%-20s  -> %.2f\n", k, v)
+					}
+				} else {
+					fmt.Println("no vars registered")
+				}
+
 			default:
 				fmt.Println("unknown command or operator!")
 			}
 		}
 	}
+
+	if c.showstack && !c.stdin {
+		dots := ""
+
+		if c.stack.Len() > 5 {
+			dots = "... "
+		}
+		last := c.stack.Last(5)
+		fmt.Printf("stack: %s%s\n", dots, list2str(last))
+	}
 }
 
 // Execute a math function, check if it is defined just in case
@@ -326,6 +402,10 @@ func (c *Calc) DoFuncall(funcname string) error {
 		return R.Err
 	}
 
+	// don't forget to backup!
+	c.stack.Backup()
+
+	// "pop"
 	if batch {
 		// get rid of stack
 		c.stack.Clear()
@@ -355,11 +435,16 @@ func (c *Calc) History(format string, args ...any) {
 
 // print the result
 func (c *Calc) Result() float64 {
-	if !c.stdin {
-		fmt.Print("= ")
-	}
+	// we only  print the result if it's either  a final result or
+	// (if it is intermediate) if -i has been given
+	if c.intermediate || !c.notdone {
+		// only needed in repl
+		if !c.stdin {
+			fmt.Print("= ")
+		}
 
-	fmt.Println(c.stack.Last()[0])
+		fmt.Println(c.stack.Last()[0])
+	}
 
 	return c.stack.Last()[0]
 }
@@ -370,12 +455,14 @@ func (c *Calc) Debug(msg string) {
 	}
 }
 
-func (c *Calc) luafunc(funcname string) {
+func (c *Calc) EvalLuaFunction(funcname string) {
 	// called from calc loop
 	var x float64
 	var err error
 
 	switch c.interpreter.FuncNumArgs(funcname) {
+	case 0:
+		fallthrough
 	case 1:
 		x, err = c.interpreter.CallLuaFunc(funcname, c.stack.Last())
 	case 2:
@@ -393,7 +480,15 @@ func (c *Calc) luafunc(funcname string) {
 
 	c.stack.Backup()
 
+	dopush := true
+
 	switch c.interpreter.FuncNumArgs(funcname) {
+	case 0:
+		a := c.stack.Last()
+		if len(a) == 1 {
+			c.History("%s(%f) = %f", funcname, a, x)
+		}
+		dopush = false
 	case 1:
 		a := c.stack.Pop()
 		c.History("%s(%f) = %f", funcname, a, x)
@@ -406,7 +501,30 @@ func (c *Calc) luafunc(funcname string) {
 		c.History("%s(*) = %f", funcname, x)
 	}
 
-	c.stack.Push(x)
+	if dopush {
+		c.stack.Push(x)
+	}
 
 	c.Result()
 }
+
+func (c *Calc) PutVar(name string) {
+	last := c.stack.Last()
+
+	if len(last) == 1 {
+		c.Debug(fmt.Sprintf("register %.2f in %s", last[0], name))
+		c.Vars[name] = last[0]
+	} else {
+		fmt.Println("empty stack")
+	}
+}
+
+func (c *Calc) GetVar(name string) {
+	if _, ok := c.Vars[name]; ok {
+		c.Debug(fmt.Sprintf("retrieve %.2f from %s", c.Vars[name], name))
+		c.stack.Backup()
+		c.stack.Push(c.Vars[name])
+	} else {
+		fmt.Println("variable doesn't exist")
+	}
+}

calc_test.go

@@ -20,8 +20,83 @@ package main
 import (
 	"fmt"
 	"testing"
+
+	lua "github.com/yuin/gopher-lua"
 )
 
+func TestCommentsAndWhitespace(t *testing.T) {
+	calc := NewCalc()
+
+	var tests = []struct {
+		name string
+		cmd  []string
+		exp  float64 // last element of the stack
+	}{
+		{
+			name: "whitespace prefix",
+			cmd:  []string{"  5"},
+			exp:  5.0,
+		},
+		{
+			name: "whitespace postfix",
+			cmd:  []string{"5  "},
+			exp:  5.0,
+		},
+		{
+			name: "whitespace both",
+			cmd:  []string{"  5   "},
+			exp:  5.0,
+		},
+		{
+			name: "comment line w/ spaces",
+			cmd:  []string{"5", "   #   19"},
+			exp:  5.0,
+		},
+		{
+			name: "comment line w/o spaces",
+			cmd:  []string{"5", `#19`},
+			exp:  5.0,
+		},
+		{
+			name: "inline comment w/ spaces",
+			cmd:  []string{"5   #   19"},
+			exp:  5.0,
+		},
+		{
+			name: "inline comment w/o spaces",
+			cmd:  []string{"5#19"},
+			exp:  5.0,
+		},
+	}
+
+	for _, tt := range tests {
+		testname := fmt.Sprintf("%s .(expect %.2f)",
+			tt.name, tt.exp)
+
+		t.Run(testname, func(t *testing.T) {
+			for _, line := range tt.cmd {
+				calc.Eval(line)
+			}
+			got := calc.stack.Last()
+
+			if len(got) > 0 {
+				if got[0] != tt.exp {
+					t.Errorf("parsing failed:\n+++  got: %f\n--- want: %f",
+						got, tt.exp)
+				}
+			}
+
+			if calc.stack.Len() != 1 {
+				t.Errorf("invalid stack size:\n+++  got: %d\n--- want: 1",
+					calc.stack.Len())
+			}
+
+		})
+
+		calc.stack.Clear()
+	}
+}
+
 func TestCalc(t *testing.T) {
 	calc := NewCalc()
 
@@ -31,6 +106,7 @@ func TestCalc(t *testing.T) {
 		exp   float64
 		batch bool
 	}{
+		// ops
 		{
 			name: "plus",
 			cmd:  `15 15 +`,
@@ -71,6 +147,8 @@ func TestCalc(t *testing.T) {
 			cmd:  `400 20 %+`,
 			exp:  480,
 		},
+
+		// math tests
 		{
 			name: "mod",
 			cmd:  `9 2 mod`,
@@ -91,6 +169,20 @@ func TestCalc(t *testing.T) {
 			cmd:  `6 4 dim`,
 			exp:  2,
 		},
+
+		// constants tests
+		{
+			name: "pitimes2",
+			cmd:  `Pi 2 *`,
+			exp:  6.283185307179586,
+		},
+		{
+			name: "pi+sqrt2",
+			cmd:  `Pi Sqrt2 +`,
+			exp:  4.555806215962888,
+		},
+
+		// batch tests
 		{
 			name:  "batch-sum",
 			cmd:   `2 2 2 2 sum`,
@@ -121,6 +213,34 @@ func TestCalc(t *testing.T) {
 			exp:   5,
 			batch: true,
 		},
+
+		// stack tests
+		{
+			name: "use-vars",
+			cmd:  `10 >TEN clear 5 <TEN *`,
+			exp:  50,
+		},
+		{
+			name: "reverse",
+			cmd:  `100 500 reverse -`,
+			exp:  400,
+		},
+		{
+			name: "swap",
+			cmd:  `2 16 swap /`,
+			exp:  8,
+		},
+		{
+			name:  "clear batch",
+			cmd:   "1 1 1 1 1 clear 1 1 sum",
+			exp:   2,
+			batch: true,
+		},
+		{
+			name: "undo",
+			cmd:  `4 4 + undo *`,
+			exp:  16,
+		},
 	}
 
 	for _, tt := range tests {
@@ -139,3 +259,55 @@ func TestCalc(t *testing.T) {
 		})
 	}
 }
+
+func TestCalcLua(t *testing.T) {
+	var tests = []struct {
+		function string
+		stack    []float64
+		exp      float64
+	}{
+		{
+			function: "lower",
+			stack:    []float64{5, 6},
+			exp:      5.0,
+		},
+		{
+			function: "parallelresistance",
+			stack:    []float64{100, 200, 300},
+			exp:      54.54545454545455,
+		},
+	}
+
+	calc := NewCalc()
+	L = lua.NewState(lua.Options{SkipOpenLibs: true})
+	defer L.Close()
+
+	luarunner := NewInterpreter("example.lua", false)
+	luarunner.InitLua()
+	calc.SetInt(luarunner)
+
+	for _, tt := range tests {
+		testname := fmt.Sprintf("lua-%s", tt.function)
+
+		t.Run(testname, func(t *testing.T) {
+			calc.stack.Clear()
+			for _, item := range tt.stack {
+				calc.stack.Push(item)
+			}
+
+			calc.EvalLuaFunction(tt.function)
+
+			got := calc.stack.Last()
+
+			if calc.stack.Len() != 1 {
+				t.Errorf("invalid stack size:\n+++  got: %d\n--- want: 1",
+					calc.stack.Len())
+			}
+
+			if got[0] != tt.exp {
+				t.Errorf("lua function %s failed:\n+++  got: %f\n--- want: %f",
+					tt.function, got, tt.exp)
+			}
+		})
+	}
+}

demo/Makefile

@@ -0,0 +1,7 @@
+#
+
+
+all:
+	asciinema rec --cols 80 --row 25 -c "env - PS1='> ' PATH=..:$PATH /bin/bash --norc --noprofile" --overwrite demo.cast
+	agg demo.cast demo.gif
+

demo/demo.cast

@@ -0,0 +1,3 @@
+{"version": 2, "width": 80, "height": 25, "timestamp": 1699358215, "env": {"SHELL": "/bin/bash", "TERM": "tmux-256color"}}
+[0.005628, "o", "> "]
+[0.941195, "o", "exit\r\n"]

demo/sessions.txt

@@ -0,0 +1,18 @@
+# demo sessions, used to create an interactive rpn recording
+
+# part 1: interactive
+
+# put some numbers onto the stack
+2 4 6
+8
+10
+
+# take a look at the stack
+dump
+
+# add the last 2
++
+
+# multiply the result and the previous
+*
+

example.lua

@@ -0,0 +1,38 @@
+-- simple function, return the lower number of the two operands
+function lower(a,b)
+    if a < b then
+        return a
+    else
+        return b
+    end
+end
+
+-- calculate parallel resistance. Batch  function (registered with -1,
+-- see below). Takes a table as parameter.
+--
+-- Formula: 1/( (1/R1) + (1/R2) + ...)
+function parallelresistance(list)
+    sumres = 0
+    
+    for i, value in ipairs(list) do
+        sumres = sumres + 1 / value
+    end
+
+    return 1 / sumres
+end
+
+-- converter example
+function inch2centimeter(inches)
+    return inches * 2.54
+end
+
+function init()
+    -- expects 2 args
+    register("lower", 2, "lower")
+
+    -- expects a list of all numbers on the stack, batch mode
+    register("parallelresistance", -1, "parallel resistance")
+
+    -- expects 1 arg, but doesn't pop()
+    register("inch2centimeter", 0)
+end  

interpreter.go

@@ -25,7 +25,8 @@ import (
 )
 
 type Interpreter struct {
-	debug bool
+	debug  bool
+	script string
 }
 
 // LUA interpreter, instanciated in main()
@@ -42,8 +43,12 @@ type LuaFunction struct {
 // have access to the interpreter instance
 var LuaFuncs map[string]LuaFunction
 
+func NewInterpreter(script string, debug bool) *Interpreter {
+	return &Interpreter{debug: debug, script: script}
+}
+
 // initialize the lua environment properly
-func InitLua(config string, debug bool) *Interpreter {
+func (i *Interpreter) InitLua() {
 	// we only  load a subset of lua Open  modules and don't allow
 	// net, system or io stuff
 	for _, pair := range []struct {
@@ -66,7 +71,7 @@ func InitLua(config string, debug bool) *Interpreter {
 	}
 
 	// load the lua config (which we expect to contain init() and math functions)
-	if err := L.DoFile(config); err != nil {
+	if err := L.DoFile(i.script); err != nil {
 		panic(err)
 	}
 
@@ -84,8 +89,6 @@ func InitLua(config string, debug bool) *Interpreter {
 	}); err != nil {
 		panic(err)
 	}
-
-	return &Interpreter{debug: debug}
 }
 
 func (i *Interpreter) Debug(msg string) {
@@ -113,6 +116,8 @@ func (i *Interpreter) CallLuaFunc(funcname string, items []float64) (float64, er
 		funcname, LuaFuncs[funcname].numargs))
 
 	switch LuaFuncs[funcname].numargs {
+	case 0:
+		fallthrough
 	case 1:
 		// 1 arg variant
 		if err := L.CallByParam(lua.P{

main.go

@@ -30,18 +30,20 @@ import (
 	lua "github.com/yuin/gopher-lua"
 )
 
-const VERSION string = "2.0.2"
+const VERSION string = "2.0.8"
 
 const Usage string = `This is rpn, a reverse polish notation calculator cli.
 
 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
+  -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 +
@@ -58,6 +60,9 @@ func main() {
 	configfile := ""
 
 	flag.BoolVarP(&calc.batch, "batchmode", "b", false, "batch mode")
+	flag.BoolVarP(&calc.showstack, "show-stack", "s", false, "show stack")
+	flag.BoolVarP(&calc.intermediate, "showin-termediate", "i", false,
+		"show intermediate results")
 	flag.BoolVarP(&enabledebug, "debug", "d", false, "debug mode")
 	flag.BoolVarP(&showversion, "version", "v", false, "show version")
 	flag.BoolVarP(&showhelp, "help", "h", false, "show usage")
@@ -93,8 +98,9 @@ func main() {
 	// our config file is interpreted  as lua code, only functions can
 	// be defined, init() will be called by InitLua().
 	if _, err := os.Stat(configfile); err == nil {
-		I := InitLua(configfile, enabledebug)
-		calc.SetInt(I)
+		luarunner := NewInterpreter(configfile, enabledebug)
+		luarunner.InitLua()
+		calc.SetInt(luarunner)
 	}
 
 	if len(flag.Args()) > 1 {

rpn.go

@@ -2,16 +2,19 @@ package main
 
 var manpage = `
 NAME
-    rpn - Reverse Polish Notation Calculator for the commandline
+    rpn - Programmable command-line calculator using reverse polish notation
 
 SYNOPSIS
         Usage: rpn [-bdvh] [<operator>]
     
         Options:
-          -b, --batchmode   enable batch mode
-          -d, --debug       enable debug mode
-          -v, --version     show version
-          -h, --help        show help
+          -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 +
@@ -111,7 +114,9 @@ DESCRIPTION
     switch or debug toggle command), then the backup stack is also being
     displayed.
 
-    The stack can be reversed using the reverse command.
+    The stack can be reversed using the reverse command. However, sometimes
+    only the last two values are in the wrong order. Use the swap command to
+    exchange them.
 
     You can use the shift command to remove the last number from the stack.
 
@@ -145,8 +150,74 @@ DESCRIPTION
         log10 log1p log2 logb pow round roundtoeven sin sinh tan tanh trunc y0
         y1 copysign dim hypot
 
+    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)
+        dump                 display the stack contents
+        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
+        history              display calculation history
+        help|?               show this message
+        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.
 
+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 "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:
+
+    ctrl-c + ctrl-d
+        Exit interactive rpn
+
+    ctrl-z
+        Send rpn to the backgound.
+
+    ctrl-a
+        Beginning of line.
+
+    ctrl-e
+        End of line.
+
+    ctrl-l
+        Clear the screen.
+
+    ctrl-r
+        Search through history.
+
+COMMENTS
+    Lines starting with "#" 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.
+
+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 vars can be used to get a list of all variables.
+
 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
@@ -173,8 +244,13 @@ EXTENDING RPN USING LUA
 
     *   function name
 
-    *   number of arguments expected (1,2 or -1 allowed), -1 means batch
-        mode.
+    *   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
 
     *   help text
 

rpn.pod

@@ -1,16 +1,19 @@
 =head1 NAME 
 
-rpn - Reverse Polish Notation Calculator for the commandline
+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
-      -v, --version     show version
-      -h, --help        show help
+      -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 +
@@ -154,8 +157,89 @@ Math functions:
     log10 log1p log2 logb pow round roundtoeven sin sinh tan tanh trunc y0
     y1 copysign dim hypot
 
+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)
+    dump                 display the stack contents
+    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
+    history              display calculation history
+    help|?               show this message
+    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.
 
+=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
@@ -189,8 +273,13 @@ function name
 
 =item *
 
-number of arguments expected (1,2 or -1 allowed), -1 means batch
-mode.
+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 *
 

stack.go

@@ -195,14 +195,24 @@ func (s *Stack) Backup() {
 	// make a backup, because the elements in list.List{} are pointers
 	// and lead to unexpected  results. The methid here works reliably
 	// at least.
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+
+	s.Debug(fmt.Sprintf("backing up %d items from rev %d",
+		s.linklist.Len(), s.rev))
+
 	s.backup = list.List{}
 	for e := s.linklist.Front(); e != nil; e = e.Next() {
-		s.backup.PushBack(e.Value)
+		s.backup.PushBack(e.Value.(float64))
 	}
+
 	s.backuprev = s.rev
 }
 
 func (s *Stack) Restore() {
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+
 	if s.rev == 0 {
 		fmt.Println("error: stack is empty.")
 		return
@@ -211,15 +221,26 @@ func (s *Stack) Restore() {
 	s.Debug(fmt.Sprintf("restoring stack to revision %d", s.backuprev))
 
 	s.rev = s.backuprev
-	s.linklist = s.backup
+
+	s.linklist = list.List{}
+	for e := s.backup.Front(); e != nil; e = e.Next() {
+		s.linklist.PushBack(e.Value.(float64))
+	}
 }
 
 func (s *Stack) Reverse() {
-	newstack := list.List{}
+	s.mutex.Lock()
+	defer s.mutex.Unlock()
+
+	items := []float64{}
 
 	for e := s.linklist.Front(); e != nil; e = e.Next() {
-		newstack.PushFront(e.Value)
+		tail := s.linklist.Back()
+		items = append(items, tail.Value.(float64))
+		s.linklist.Remove(tail)
 	}
 
-	s.linklist = newstack
+	for i := len(items) - 1; i >= 0; i-- {
+		s.linklist.PushFront(items[i])
+	}
 }

test.lua

@@ -1,17 +0,0 @@
-function add(a,b)
-  return a + b
-end
-
-function test(a)
-  return a
-end  
-
-function parallelresistance(a,b)
-  return 1.0 / (a * b)
-end
-
-function init()
-  register("add", 2, "addition")
-  register("test", 1, "test")
-  register("parallelresistance", 2, "parallel resistance")
-end