rpn/MANUAL.md

rpn - reference manual

rpn

• is a structured full-featured math-oriented language inspired by Hewlett-Packard Reverse Polish Lisp (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, (c) 2017 <louis@rubet.fr>, GNU LGPL v3

Reverse Polish Notation language

using GMP v6.1.2 under GNU LGPL
MPFR v3.1.5-p8 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

Precision can be really high, up to 0x7FFFFFFFFFFFFFFF bits with GNU MPFR

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

object types

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"] round. 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	if (test-instruction) 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
for	(start) (end) for (variable) (instructions) next
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
exp	exponential
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

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 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