From ddf7f9c3d311dc733745e01965df6bdcfdf49e08 Mon Sep 17 00:00:00 2001 From: Louis Rubet Date: Mon, 12 Jun 2017 19:32:26 +0200 Subject: [PATCH] #120: new doc for 2.1 --- GENERATION.md | 71 ++++++++++++ MANUAL.md | 271 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 297 ++++---------------------------------------------- 3 files changed, 361 insertions(+), 278 deletions(-) create mode 100644 GENERATION.md create mode 100644 MANUAL.md diff --git a/GENERATION.md b/GENERATION.md new file mode 100644 index 0000000..dd4e50f --- /dev/null +++ b/GENERATION.md @@ -0,0 +1,71 @@ +# **rpn** - Generation + +For now rpn is proposed only for **GNU/Linux** + +It can be generated following the steps below + +## version identification + +rpn v2.1 is statically linked against +- GNU MP v6.1.2 +- GNU MPFR v3.1.5 +- linenoise-ng v1.0.1 + +## GNU MP v6.1.2 + +- download and install **GNU MP v6.1.2** from https://gmplib.org/ + +## GNU MPFR v3.1.5 + +- download and install **GNU MPFR v3.1.5** from http://www.mpfr.org + +## linenoise-ng v1.0.1 + +- download **linenoise-ng v1.0.1** from https://github.com/arangodb/linenoise-ng + +- checkout the tag v1.0.1 + +- apply the following patch to the source code in order to have autocompletion even from a blank line + +``` +--- ../../../linenoise-ng/src/linenoise.cpp 2017-06-10 18:13:31.752976287 +0200 ++++ linenoise.cpp 2017-06-12 18:54:50.481794824 +0200 +@@ -2587,12 +2587,15 @@ + + // ctrl-I/tab, command completion, needs to be before switch statement + if (c == ctrlChar('I') && completionCallback) { ++ // lru for rpn ++ #if 0 + if (pos == 0) // SERVER-4967 -- in earlier versions, you could paste + // previous output + continue; // back into the shell ... this output may have leading + // tabs. + // This hack (i.e. what the old code did) prevents command completion + // on an empty line but lets users paste text with leading tabs. ++ #endif + + killRing.lastAction = KillRing::actionOther; + historyRecallMostRecent = false; +``` + +## rpn + +- clone this project or download a zipped version from [the release directory](https://github.com/louisrubet/rpn/releases) + ``` + # git clone https://github.com/louisrubet/rpn.git + ``` + +- make + + CMake must be installed on the generation machine + + ``` + # cd rpn/ + # mkdir build + # cd build && cmake .. && make + ``` + +- then install + ``` + # sudo make install + ``` diff --git a/MANUAL.md b/MANUAL.md new file mode 100644 index 0000000..cb1e0dd --- /dev/null +++ b/MANUAL.md @@ -0,0 +1,271 @@ +# **rpn** - Reference manual + +**rpn** +- is a **math-oriented language** inspired by Hewlett-Packard **R**everse **P**olish **L**isp (**HP28S** user manual is provided as a reference), it includes at least **stack**, **store**, **branch**, **test**, **trig** and **logs** commands +- is implemented as a a **command-line calculator** for GNU/Linux +- 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** + +## Quick examples + +### easy calculation with **stacked results** +``` +rpn> 1 2 + +3 +rpn> 2 sqrt +2> 3 +1> 1.4142135623730950488 +``` + +### **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.0986122886681096914 +``` + +### **arbitrary precision** +Precision can be really high, up to 0x7FFFFFFFFFFFFFFF bits with GNU MPFR +``` +rpn> 256 prec 200 std +rpn> pi 3 * 4 / cos +-0.70710678118654752440084436210484903928483593768847403658833986899536623923105962592591087473479525356117497671223960240783675485777817360566073272153486395308799122357513534343724299243077135552002446 +rpn> +``` + +### Objects + +Following objects are managed: **floating numbers**, **symbols**, **strings**, **programs**, plus language **keywords** (commands and flow controls) +``` +4> 'symbol' +3> "string" +2> 12.3456 +1> << -> n << 0 1 n for i i 2 * inv + next >> >> +rpn> +``` + +### Command line + +**rpn** is a cli interface with an **interactive editor** with autocompletion provided by **linenoise-ng**, see https://github.com/arangodb/linenoise-ng + +``` +rpn> +Display all 128 possibilities? (y or n) +!= -> > acosh atan cosh drop e exit for ifte max not pos r->d rot sinh sqrt sto+ tan unti xor +% ->str >= alog atanh d->r drop2 edit exp h inv min num pow rcl round sinv start sto- tanh until xpon +%CH / ? alog2 chr dec dropn else exp10 help ln mod or prec repea same size std sto/ test vars +* < ^ and chs default dup end exp2 hex log neg over purge repeat sci sneg step str-> then version ++ <= abs asin clusr depth dup2 erase fact if log2 next pi q roll sign sq sto sub type whil +- == acos asinh cos do dupn eval fix ift mant nop pick quit rolld sin sqr sto* swap uname while +rpn> +``` + +## keywords + +### general + +|keyword|description| +|-|-| +|nop | no operation | +|help | (or h or ?) this help message +|quit | (or q or exit) quit software +|version | show rpn version +|uname | show rpn complete identification string +|type | show type of stack first entry +|default | set float representation and precision to default + +### real + +|keyword|description| +|-|-| +|+| addition +|-| substraction +|neg| negation +|*| multiplication +|/| division +|inv| inverse +|%| purcent +|%|CH inverse purcent +|^| (or pow) power +|sqrt| square root +|sq| (or sqr) square +|mod| modulo +|abs| absolute value +|dec| decimal representation +|hex| hexadecimal representation +|prec| get float precision in bits when first stack is not a number, set float precision in bits when first stack entry is a number. ex: ```256 prec``` +|round| set float rounding mode. Authoerized values are: ```["nearest", "toward zero", "toward +inf", "toward -inf", "away from zero"] round```. ex: ```"nearest" round``` +|fact| n! for integer n or Gamma(x+1) for fractional x +|sign| 1 if number at stack level 1 is > 0, 0 if == 0, -1 if <= 0 +|mant| mantissa of a real number +|xpon| exponant of a real number +|min| min of 2 real numbers +|max| max of 2 real numbers + +### mode + +|keyword|description| +|-|-| +|std| standard floating numbers representation. ex: [25] std +|fix| fixed point representation. ex: 6 fix +|sci| scientific floating point representation. ex: 20 sci + +### 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 +|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 then else end +|then| used with if +|else| used with if +|end| used with various branch instructions +|ift| similar to if-then-end, ift" +|ifte| similar to if-then-else-end, ifte" +|start| start> start next| step +|for| start> for next| step +|next| used with start and for +|step| used with start and for +|do| do until end +|until | (or unti) used with do +|while| (or whil) while repeat end +|repeat| (or 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 + +|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 + +|keyword|description| +|-|-| +|e| exp(1) constant +|log| logarithm base 10 +|alog| (or exp10) exponential base 10 +|log2| logarithm base 2 +|alog2| (or exp2) exponential base 2 +|ln| logarithm base e +|exp| exponential +|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 20 digits + +Default floating point precision is 128 bits + +Default rounding mode is 'nearest' + +## Tests + +Unit tests are given as txt files in the test subdirectory. + +Use the command 'test' to run a test file, eg +``` +# cd src_directory/ +# rpn +rpn> "test/01-all.txt" +rpn> test +## ENTRY TEST +(...) +# real decimal PASSED +# real hex PASSED +# real binary PASSED +(...) +``` + +Test output is done on stdout and is not stacked in rpn. diff --git a/README.md b/README.md index 10ab21a..727e0df 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,27 @@ # **rpn** - **R**everse **P**olish **N**otation language -**rpn** -- is a **math-oriented language** inspired by Hewlett-Packard **R**everse **P**olish **L**isp (**HP28S** user manual is provided as a reference), it includes at least **stack**, **store**, **branch**, **test**, **trig** and **logs** commands -- is implemented as a a **command-line calculator** for GNU/Linux -- brings powerfull calculation facilities on floating point numbers with __arbitrary precision__, provided by **GNU MPFR** library -- uses that so cool **reverse polish notation** +### a lisp-based math language using polish notation -## Quick examples - -### easy calculation with **stacked results** ``` -rpn> 1 2 + -3 -rpn> 2 sqrt +rpn> 1 2 + 2 sqrt 2> 3 1> 1.4142135623730950488 ``` -### **programs** and **variables** -``` -rpn> << rot * swap 2 / chs 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.0986122886681096914 -``` - -### **arbitrary precision** -Precision can be really high, up to 0x7FFFFFFFFFFFFFFF bits with GNU MPFR +### with arbitrary precision ``` rpn> 256 prec 200 std rpn> pi 3 * 4 / cos -0.70710678118654752440084436210484903928483593768847403658833986899536623923105962592591087473479525356117497671223960240783675485777817360566073272153486395308799122357513534343724299243077135552002446 -rpn> ``` -### Objects - -Following objects are managed: **floating numbers**, **symbols**, **strings**, **programs**, plus language **keywords** (commands and flow controls) +### providing variables, programs ``` -4> 'symbol' -3> "string" -2> 12.3456 -1> << -> n << 0 1 n for i i 2 * inv + next >> >> -rpn> +rpn> << rot * swap 2 / chs dup sq rot - sqrt >> 'quad' sto +rpn> << -> x y << x y + ln >> >> 'P' sto ``` -### Command line - -**rpn** is a cli interface with an **interactive editor** with autocompletion provided by **linenoise-ng**, see https://github.com/arangodb/linenoise-ng - +### and a bunch of functions ``` rpn> Display all 128 possibilities? (y or n) @@ -70,249 +34,26 @@ Display all 128 possibilities? (y or n) rpn> ``` -## keywords +## Manual -### general +A reference manual is provided [here](MANUAL.md) -|keyword|description| -|-|-| -|nop | no operation | -|help | (or h or ?) this help message -|quit | (or q or exit) quit software -|version | show rpn version -|uname | show rpn complete identification string -|type | show type of stack first entry -|default | set float representation and precision to default +## Installation -### real +Installation packages are provided in deb, rpm and tar.bz2 formats -|keyword|description| -|-|-| -|+| addition -|-| substraction -|neg| negation -|*| multiplication -|/| division -|inv| inverse -|%| purcent -|%|CH inverse purcent -|^| (or pow) power -|sqrt| square root -|sq| (or sqr) square -|mod| modulo -|abs| absolute value -|dec| decimal representation -|hex| hexadecimal representation -|prec| get float precision in bits when first stack is not a number, set float precision in bits when first stack entry is a number. ex: ```256 prec``` -|round| set float rounding mode. Authoerized values are: ```["nearest", "toward zero", "toward +inf", "toward -inf", "away from zero"] round```. ex: ```"nearest" round``` -|fact| n! for integer n or Gamma(x+1) for fractional x -|sign| 1 if number at stack level 1 is > 0, 0 if == 0, -1 if <= 0 -|mant| mantissa of a real number -|xpon| exponant of a real number -|min| min of 2 real numbers -|max| max of 2 real numbers +[**download .deb**]() -### mode +[**download .rpm**]() -|keyword|description| -|-|-| -|std| standard floating numbers representation. ex: [25] std -|fix| fixed point representation. ex: 6 fix -|sci| scientific floating point representation. ex: 20 sci +[**download .tar.bz2**]() -### test +## Generation -|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) +Generation instructions can be found [here](GENERATION.md) -### stack +## Contact -|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 -|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 +Please email me at [louis@rubet.fr](mailto:louis@rubet.fr) -### 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 then else end -|then| used with if -|else| used with if -|end| used with various branch instructions -|ift| similar to if-then-end, ift" -|ifte| similar to if-then-else-end, ifte" -|start| start> start next| step -|for| start> for next| step -|next| used with start and for -|step| used with start and for -|do| do until end -|until | (or unti) used with do -|while| (or whil) while repeat end -|repeat| (or 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 - -|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 - -|keyword|description| -|-|-| -|e| exp(1) constant -|log| logarithm base 10 -|alog| (or exp10) exponential base 10 -|log2| logarithm base 2 -|alog2| (or exp2) exponential base 2 -|ln| logarithm base e -|exp| exponential -|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 20 digits - -Default floating point precision is 128 bits - -Default rounding mode is 'nearest' - -## Tests - -Unit tests are given as txt files in the test subdirectory. - -Use the command 'test' to run a test file, eg -``` -# cd src_directory/ -# rpn -rpn> "test/01-all.txt" -rpn> test -## ENTRY TEST -(...) -# real decimal PASSED -# real hex PASSED -# real binary PASSED -(...) -``` - -Test output is done on stdout and is not stacked in rpn. - -## generation and installation - -At this time the software is proposed for **GNU/Linux** only and provided as a source code. - -No binary package is provided, user must compile its version by following these 3 steps: - -#### Version identification - -rpn v2.1 uses -- GNU GMP v6.1.2 -- GNU MPFR v3.1.5 -- linenoise-ng v1.0.1 - -linenoise is included in rpn as source code. It can be found at https://github.com/arangodb/linenoise-ng - -GNU GMP and GNU MPFR must be downloaded and installed - -#### GNU GMP v6.1.2 - -- download and install **GNU GMP v6.1.2** from [https://gmplib.org/](https://gmplib.org/) - -#### GNU MPFR v3.1.5 - -- download and install **GNU MPFR v3.1.5** from [http://www.mpfr.org](http://www.mpfr.org) - -#### rpn - -- clone this project or download a zipped version from [the release directory](https://github.com/louisrubet/rpn/releases) - ``` - # git clone https://github.com/louisrubet/rpn.git - ``` - -- make - - CMake must be installed on the generation machine - - ``` - # cd rpn/ - # mkdir build - # cd build && cmake .. && make - ``` - -- then install - ``` - # sudo make install - ``` +You can use [github issues](https://github.com/louisrubet/rpn/issues) too