Miroirs/rpn
1
0
Fork 0
mirror of https://github.com/louisrubet/rpn synced 2024-11-17 07:47:50 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
rpn/MANUAL.md
Louis Rubet c0813c9307 Correct manual
2022-02-28 18:10:25 +01:00

390 lines
20 KiB
Markdown
Raw Blame History

# **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**,
- 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
rpn> help
rpn v2.4.0, (c) 2022 <louis@rubet.fr>
Reverse Polish Notation CLI calculator
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
rpn> 1 2 +
3
rpn> 2 sqrt
2> 3
1> 1.4142135623730950488016887242096980786
```
### **Programs** and **variables**
```rpn
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
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
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).
```rpn
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](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
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 (even)", "toward zero", "toward +inf", "toward -inf", "away from zero", "faithful rounding", "nearest (away from zero)"` |
| `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` | used with do |
| `while` | `while (test-instruction) repeat (loop-instructions) end` |
| `repeat` | 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.
- All tests are run each at each pull on a pull request branch. Memory tests (`valgrind`) are also executed on each tests.
- Test sheets syntax is
```shell
cat my_test_sheet.md
# Test sheet example
`default del`
## test step 1
`1 dup 1 +`
-> stack size should be 2
-> stack should be 1, 2
-> error should be 0
`del`
## test step 2
`2 4 / 0.5 ==`
-> stack should be 1
`del`
```
- Test sheet can be played with the command `test`
```rpn
rpn> "my_test_sheet.md" test
rpn version is v2.3.2-68-g60099e3
my_test_sheet.md: Test sheet example
## test step 1 PASSED
## test step 2 PASSED
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 del`
- 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
Reference in a new issue View git blame Copy permalink