= rpn_rs
:!webfonts:
:source-highlighter: rouge
:rouge-style: molokai

== Intro

=== What is this?

A TUI link:https://en.wikipedia.org/wiki/Reverse_Polish_notation[RPN] calculator, with inspiration taken from link:https://en.wikipedia.org/wiki/HP_calculators[HP RPN Calculators] and link:https://github.com/mawww/kakoune[Kakoune] that works like link:https://github.com/pelzlpj/orpie[Orpie].

It uses link:https://github.com/fdehau/tui-rs[tui-rs] for the UI and link:https://serde.rs/[serde]+link:https://github.com/rust-cli/confy[confy] for configuration loading and saving.

=== Comparison with existing tools

* `orpie` (`ocaml`): has more features at the moment. Matrices, units, more default constants, etc, but I don't think it allows for custom macros
* `dc` (`c`): allows for different input/output radix, no TUI and does not show the stack

== Setup

[source,sh,title='bash']
----
cargo install --git [this url]

# Run it!
~/.cargo/bin/rpn_rs

# Or if "${HOME}/.cargo/bin" is in your PATH
rpn_rs
----

=== Development setup

[source,sh,title='bash']
----
git clone [this url]
cargo build

# For docs
gem install --user-install rouge
asciidoctor REAMDE.adoc
----

== Usage

* `h`: Help menu - shows all keys
* `@`: Show calculator settings like degree/radian, scientific/engineering/separated mode
* `<ret> / <CR>`: Push number or Dup
* `<ctrl+s>`: Save the configuration. On Linux this will be `~/.config/rpn_rs/rpn_rs.toml`
* `<ctrl+l>`: Load the configuration. This runs by default when you start the calculator. Yes *I know* this should be redraw but not sure what else to use.
* `m`: Show macro menu. Define custom macros in your config
* `<tab>`: Show constants menu. Define constants in your config
* `R`: Store bottom of stack in next char's register
* `r`: Recall next char's register
* `e`: When entering a number, applies `* 10^`

=== Custom constants and macros

If you have not done this before, open the calculator and press `<ctrl+s>` to save the basic config.

Edit the config file (in Linux, edit `~/.config/rpn_rs/rpn_rs.toml` and add any constants or macros and press `<ctrl+l>` or reopen the calculator.

Sample Macros:

[toml, title='~/.config/rpn_rs/rpn_rs.toml']
----
# Push a, then b, then c, then mQ
[macros.Q]
macro = 'CalculatorMacro'
help = 'Quadratic Formula'
value = 'RcRbRarbnrb2^4rarc**-v+2ra*/rbnrb2^4rarc**-v-2ra*/'
----

Sample Constants (you can copy paste the ones you want into your config file):

[toml, title='~/.config/rpn_rs/rpn_rs.toml']
----
[constants.E]
macro = 'CalculatorConstant'
help = 'Earth Mass (kg)'
value = 5.972e24

[constants.S]
macro = 'CalculatorConstant'
help = 'Sun Mass (kg)'
value = 1.989e30

[constants.a]
macro = 'CalculatorConstant'
help = '''Avogadro's Number (mol^-1)'''
value = 6.022e23

[constants.G]
macro = 'CalculatorConstant'
help = 'Gravitational Constant (Nm^2kg^-2)'
value = 6.67e-11

[constants.c]
macro = 'CalculatorConstant'
help = 'Speed of light (m/s)'
value = 2.9979e8

[constants.h]
macro = 'CalculatorConstant'
help = 'Planck constant (Js)'
value = 6.626e-34
----

== Lore

=== Why?

. I am aware of no good terminal RPN calculators on linux. `dc` is neat but not fun to work with, `orpie` is written in ocaml (but really because Void Linux currently does not have a package in default repos for orpie).
. I wanted to learn Rust. This seemed like a good first project that was actually useful, and the link:https://github.com/fdehau/tui-rs/blob/master/assets/demo.gif[GIF on tui-rs's homepage] make it look really cool.
. I wanted to write or port an HP calculator emulator for terminal/linux, but they seem to all be written for Wandows and porting is hard. Also I would have to figure out how to convert a 131x80 pixel display to terminal.
. I play Minecraft (FTB; PO3) and lots of recipes require exorbitant quantities of items. I wanted an RPN calculator that was programmable (most used recipe being x\64 x%64 to see how many stacks+remainder are required). I wrote this calculator with programability in mind.

=== Inspiration?

* link:https://github.com/mawww/kakoune[Kakoune] is my current editor. I like that the programming language *is* the user language. There is no command `line-down`. It's `j`. So when you script in it, you write commands as they are typed.
* Similarly, link:https://en.wikipedia.org/wiki/HP_calculators[HP Calculators] work the same way. The language RPL is the language you use to calculate. Also RPN is really nice to use and you should use it if you don't.
* link:https://github.com/pelzlpj/orpie[Orpie] was the calculator I used 

=== Missing features

Will I implement these features? I don't know. Lots of these could be done by setting the base type to something complex and not `f64`. But no plans for that.

* [ ] Pick (generally the up key): I will implement this
* [ ] More accurate digits: I want to do this. `f64`s imprecision is ugly
* Complex numbers: Not sure if I'll implement this
* Matrices: Maybe
* Units: This could be cool
* Bases: Not yet
* Different math operators like `!` or `sum`: If someone asks me to, I guess
* Conditionals: If someone asks me to, I guess