rpn/MANUAL.md

# **rpn** - reference manual

**rpn**
- is a structured full-featured **math-oriented language** inspired by Hewlett-Packard **R**everse **P**olish **L**isp (**HP28S** and **HP48GX** user manuals are provided as references), including **real**, **complex**, **stack**, **store**, **branch**, **program**, **test**, **trig** and **logs** commands and more to come
- is implemented as a **command-line calculator** for most popular Linux distributions
- brings powerfull calculation facilities on floating point numbers with __arbitrary precision__ provided by **GNU MP** and **GNU MPFR** libraries
- uses that so cool **reverse polish notation**

## Doc overview

This page gives some examples and lists the commands currently implemented.

For a most complete help, please refer to HP28S and HP48GX manuals provided in the sources

A help command is provided by rpn:

```
rpn> help

rpn v2.3.2, (c) 2017 <louis@rubet.fr>, GNU LGPL v3

Reverse Polish Notation language

using GMP v6.1.2 under GNU LGPL
MPFR v4.0.1 under GNU LGPL
and linenoise-ng v1.0.0 under BSD


Syntax: rpn [command]
with optional command = list of commands
	
GENERAL
nop	no operation
help	this help message
(...)
```

## Quick examples

### easy calculation with **stacked results**
```
rpn> 1 2 +
3
rpn> 2 sqrt
2> 3
1> 1.4142135623730950488016887242096980786
```

### **programs** and **variables**
```
rpn> << rot * swap 2 / neg dup sq rot - sqrt >> 'quadratic_solution' sto
rpn> 1 2 -3 quadratic_solution
2> -1
1> 2
rpn> vars
var 1: name 'quadratic_solution', type program, value << rot * swap 2 / chs dup sq rot - sqrt  >>
```

### **local variables**
```
rpn> << -> x y << x y + ln >> >> 'P' sto
rpn> 1 2 P
rpn> 1.0986122886681096913952452369225257046
```

### **arbitrary precision**
The number of significant digits can be very large thanks to GNU MPFR

```
rpn> 256 prec
rpn> pi
3.1415926535897932384626433832795028841971693993751058209749445923078164062862
rpn> erase 10000 prec pi
3.141592653589793238462643383279502884197169399375105820974944592307816406286208998628034825342117067982148086513282306647093844609550582231725359408128481117450284102701938521105559644622948954930381964428810975665933446128475648233786783165271201909145648566923460348610454326648213393607260249141273724587006606315588174881520920962829254091715364367892590360011330530548820466521384146951941511609433057270365759591953092186117381932611793105118548074462379962749567351885752724891227938183011949129833673362440656643086021394946395224737190702179860943702770539217176293176752384674818467669405132000568127145263560827785771342757789609173637178721468440901224953430146549585371050792279689258923542019956112129021960864034418159813629774771309960518707211349999998372978049951059731732816096318595024459455346908302642522308253344685035261931188171010003137838752886587533208381420617177669147303598253490428755468731159562863882353787593751957781857780532171226806613001927876611195909216420198938095257201065485863278865936153381827968230301952035301852968995773622599413891249721775283479131515574857242454150695950829533116861727855889075098381754637464939319255060400927701671139009848824012858361603563707660104710181942955596198946767837449448255379774726847104047534646208046684259069491293313677028989152104752162056966024058038150193511253382430035587640247496473263914199272604269922796782354781636009341721641219924586315030286182974555706749838505494588586926995690927210797509302955321165344987202755960236480665499119881834797753566369807426542527862551818417574672890977772793800081647060016145249192173217214772350141441973568548161361157352552133475741849468438523323907394143334547762416862518983569485562099219222184272550254256887671790494601653466804988627232791786085784383827967976681454100953883786360950680064225125205117392984896084128488626945604241965285022210661186306744278622039194945047123713786960956364371917287467764657573962413890865832645995813390478027590099465764078951269468398352595709825822620522489407726719478268482601476990902640136394437455305068203496252451749399651431429809190659250937221696461515709858387410597885959772975498930161753928468138268683868942774155991855925245953959431049972524680845987273644695848653836736222626099124608051243884390451244136549762780797715691435997700129616089441694868555848406353422072225828488648158456028506016842739452267467678895252138522549954666727823986456596116354886230577456498035593634568174324112515076069479451096596094025228879710893145669136867228748940560101503308617928680920874760917824938589009714909675985261365549781893129784821682998948722658804857564014270477555132379641451523746234364542858444795265867821051141354735739523113427166102135969536231442952484937187110145765403590279934403742007310578539062198387447808478489683321445713868751943506430218453191048481005370614680674919278191197939952061419663428754440643745123718192179998391015919561814675142691239748940907186494231961567945208
rpn> 
```

### object types

The following objects are managed: **floating numbers**, **complexes**, **symbols**, **strings**, **programs**, plus language **keywords** (commands and flow controls)
```
5> 12.3456
4> (1,-2.33)
3> 'symbol'
2> "string"
1> << -> n << 0 1 n for i i 2 * inv + next >> >>
rpn> 
```

### structured programming

Provided loop keywords **for|start..next|step**, **do..until**, **while..repeat** and control keywords **if..then..[else]..end**, **ift**, **ifte** allow you to program powerfull algorithms

### command line

**rpn** is a cli interface with an **interactive editor** with autocompletion provided by **linenoise-ng**, see https://github.com/arangodb/linenoise-ng

Autocompletion works like those in Linux shells, with keys \<tab\>, Ctrl-R \<search pattern\> etc.

## entry

**reals** can be entered in decimal, binary, hexadecimal or arbitrary base from 2 to 62

binaries (base 2) are entered as `0b<number>` or `0B<number>`

hexadecimals (base 16) are entered as `0x<number>` or `0X<number>`

arbitrary base numbers are entered as `<base>b<number>`

representation can be individualy changed with keywords `dec`, `bin`, `hex` and `<n> base`

ex:
```
rpn> 5.6 0xaabb 0b1101 7b1252
4> 5.6
3> 0xaabb
2> 0b1101
1> 7b1252

rpn> 7b1252 dec
1> 478
```

## keywords

### general

|keyword|description|
|-|-|
|`nop` | no operation
|`help` `h` `?` | this help message
|`quit` `q` `exit` | quit software
|`version` | show rpn version
|`uname` | show rpn complete identification string
|`history`| see commands history

### usual operations - real and complex

|keyword|description|
|-|-|
|`+`| addition
|`-`| substraction
|`neg` `chs`| negation
|`*`| multiplication
|`/`| division
|`inv`| inverse
|`^` `pow`| power
|`sqrt`| square root
|`sq` `sqr`| square
|`abs`| absolute value for a number or `sqrt(re*re+im*im)` for a complex
|`dec`| decimal representation
|`hex`| hexadecimal representation
|`bin`| binary representation
|`base`| arbitrary base representation
|`sign`| sign of a real, unary vector in the same direction for a complex

### operations on reals

|keyword|description|
|-|-|
|`%`| purcent
|`%CH`| inverse purcent
|`mod`| modulo
|`fact`| n! for integer n or Gamma(x+1) for fractional x
|`mant`| mantissa of a real number
|`xpon`| exponant of a real number
|`floor`| largest number <=
|`ceil`| smallest number >=
|`ip`| integer part
|`fp`| fractional part
|`min`| min of 2 real numbers
|`max`| max of 2 real numbers

### operations on complexes

|keyword|description|
|-|-|
|`re`| complex real part
|`im`| complex imaginary part
|`conj`| complex conjugate
|`arg`| complex argument in radians
|`r->p`| rectangular to polar coordinates
|`p->r`| polar to rectangular coordinates
|`r->c`| transform 2 reals in a complex
|`c->r`| transform a complex in 2 reals

### mode

|keyword|description|
|-|-|
|`std`| standard floating numbers representation. ex: `std`
|`fix`| fixed point representation. ex: `6 fix`
|`sci`| scientific floating point representation. ex: `20 sci`
|`prec`| set float precision in bits. ex: `256 prec`
|`round`| set float rounding mode. Authorized values are: `"nearest"` `"toward zero"` `"toward +inf"` `"toward -inf"` `"away from zero"`. ex: `"nearest" round`
|`default` | set float representation and precision to default
|`type` | show type of stack first entry

### test

|keyword|description|
|-|-|
|`>`| binary operator >
|`>=`| binary operator >=
|`<`| binary operator <
|`<=`| binary operator <=
|`!=`| binary operator != (different)
|`==`| binary operator == (equal)
|`and`| boolean operator and
|`or`| boolean operator or
|`xor`| boolean operator xor
|`not`| boolean operator not
|`same`| boolean operator same (equal)

### stack

|keyword|description|
|-|-|
|`swap`| swap 2 first stack entries
|`drop`| drop first stack entry
|`drop2`| drop 2 first stack entries
|`dropn`| drop n first stack entries
|`del` `erase`| drop all stack entries
|`rot`| rotate 3 first stack entries
|`dup`| duplicate first stack entry
|`dup2`| duplicate 2 first stack entries
|`dupn`| duplicate n first stack entries
|`pick`| push a copy of  the given stack level onto the stack
|`depth`| give stack depth
|`roll`| move a stack entry to the top of the stack
|`rolld`| move the element on top of the stack to a higher stack position
|`over`| push a copy of the element in stack level 2 onto the stack

### string

|keyword|description|
|-|-|
|`->str`| convert an object into a string
|`str->`| convert a string into an object
|`chr`| convert ASCII character code in stack level 1 into a string
|`num`| return ASCII code of the first character of the string in stack level 1 as a real number
|`size`| return the length of the string
|`pos`| seach for the string in level 1 within the string in level 2
|`sub`| return a substring of the string in level 3

### branch

|keyword|description|
|-|-|
|`if`| `(test-instruction) if then (true-instructions) else (false-instructions) end`
|`then`| used with if
|`else`| used with if
|`end`| used with various branch instructions
|`ift`| similar to if-then-end: `(test-instruction) (true-instruction) ift`
|`ifte`| similar to if-then-else-end: `(test-instruction) (true-instruction) (false-instruction) ifte`
|`start`| `(start) (end) start (instructions) [next,(step) step]`. ex: `10 20 30 1 2 start + next`
|`for`| `(start) (end) for (variable) (instructions) [next,(step) step]`. ex: `1 2 for i i 'a' sto+ 0.1 step`
|`next`| used with start and for
|`step`| used with start and for
|`do`| `do (instructions) until (condition) end`
|`until` `unti` | used with do
|`while` `whil`| `while (test-instruction) repeat (loop-instructions) end`
|`repeat` `repea`| used with while

### store

|keyword|description|
|-|-|
|`sto`| store a variable. ex: ```1 'name' sto```
|`rcl`| recall a variable. ex: ```'name' rcl```
|`purge`| delete a variable. ex: ```'name' purge```
|`vars`| list all variables
|`clusr`| erase all variables
|`edit`| edit a variable content
|`sto+`| add to a stored variable. ex: 1 'name' sto+ 'name' 2 sto+
|`sto-`| substract to a stored variable. ex: 1 'name' sto- 'name' 2 sto-
|`sto*`| multiply a stored variable. ex: 3 'name' sto* 'name' 2 sto*
|`sto/`| divide a stored variable. ex: 3 'name' sto/ 'name' 2 sto/
|`sneg`| negate a variable. ex: 'name' sneg
|`sinv`| inverse a variable. ex: 1 'name' sinv

### program

|keyword|description|
|-|-|
|`eval`| evaluate (run) a program, or recall a variable. ex: `'my_prog' eval`
|`->`| load program local variables. ex: `<< -> n m << 0 n m for i i + next >> >>`

### trig on reals and complexes

|keyword|description|
|-|-|
|`pi`| pi constant
|`sin`| sinus
|`asin`| arg sinus
|`cos`| cosinus
|`acos`| arg cosinus
|`tan`| tangent
|`atan`| arg tangent
|`d->r`| convert degrees to radians
|`r->d`| convert radians to degrees

### logs on reals and complexes

|keyword|description|
|-|-|
|`e`| Euler constant
|`ln` `log`| logarithm base e
|`lnp1`| ln(1+x) which is useful when x is close to 0
|`exp`| exponential
|`expm`| exp(x)-1 which is useful when x is close to 0
|`log10`| logarithm base 10
|`alog10` `exp10`| exponential base 10
|`log2`| logarithm base 2
|`alog2` `exp2`| exponential base 2
|`sinh`| hyperbolic sine
|`asinh`| inverse hyperbolic sine
|`cosh`| hyperbolic cosine
|`acosh`| inverse hyperbolic cosine
|`tanh`| hyperbolic tangent
|`atanh`| inverse hyperbolic tangent
|`time`| time in format HH.MMSSssssss
|`date`| date in format (M)M.DDYYYY
|`ticks`| system tick in µs

### default

Default float mode is 'std' with 39 digits

Default floating point precision is 128 bits

Default rounding mode is 'nearest' 

## Tests

- A set of complete test sheets are given in the [test](https://github.com/louisrubet/rpn/tree/master/test) subdirectory. Each version is fully tested before delivery

- Test sheets syntax is

    ```
    # cat my_test_sheet.txt

    ## Test sheet example
    default erase

    # test step 1
    1 dup 1 +
    -> stack size should be 2
    -> stack should be 1, 2
    -> error should be 0
    erase

    # test step 2
    2 4 / 0.5 ==
    -> stack should be 1
    erase
    ```

- Test sheet can be played with the command `test`

    ```
    rpn> "my_test_sheet.txt"
    "my_test_sheet.txt"
    rpn> test

    my_test_sheet.txt: Test sheet example
    # test step 1 PASSED
    # test step 2 PASSED
    my_test_sheet.txt: run 2 tests: 2 passed, 0 failed (4 steps: 4 passed, 0 failed)
    Total: run 2 tests: 2 passed, 0 failed (4 steps: 4 passed, 0 failed)
    rpn> 
    ```

- Please follow these rules to write correct test sheets:
  - make the test sheet begins by `default erase`

  - the 3 existing tests are `-> stack size should be (number)` `-> stack should be (values separated by commas)` `-> error should be (error number)`

  - put a command `erase` or even `default erase` after each test step

  - test output is done on stdout and is not stacked in rpn