#import "t.typ" as t
#show: t.init

// begin document

#align(center, block(
  text(size: 2em, stack(
    spacing: 0.5em,
    [*User manual*],
    [*for*],
    [*RPX*]
  )),
  stroke: (top: white, bottom: white),
  inset: 1em,
  width: 80%
))

#align(horizon, outline())
#pagebreak()

= Modes
+ *Real Number Mode* (default)
  - Supports floating-point operations
  - Supports lambda functions
+ *Complex Number Mode*
  - Supports complex number operations
  - Supports matrix operations
  #t.note([Use `:tc` command to switch modes])

= Input Format
- Negative numbers: Use `m` function (e.g., `5 m` for $-5$)
- Decimal numbers are supported (e.g., `0.1 0.03 +`)
- Complex numbers: Use `i` function (e.g., `3m 4i +` for $-3+4i$)
- Constants: Use `\` prefix (e.g., `\P` for $pi$)
- Load Registers: Use `$` prefix (e.g., `$x $y +` for $x+y$)
- Store Registers: Use `&` prefix (e.g., `3 5 + &x` for $x=3+5$)
- Polar coordinates: Use `p` function (e.g., `1 \P p` for $-1$)
- Matrices: Use `[column; elements ...]` format (e.g., `[2; 1 2 3 4]` for $mat(1,2;3,4)$)
- Comments: Use `;`
- Spaces are required only to delimit numbers (e.g., `5 3m4i+` for $5-3+4i$)

= Operators
- `+`, `-`, `*`, `/`, `%` (basic arithmetic operators)
- `^` (exponentiation)
- `=`, `<`, `>` (comparison)

= Functions
- `A` (absolute value)
- `m` (negate)
- `i` (multiply by i, for complex mode)
== Trigonometric Functions
- `s` (sin), `c` (cos), `t` (tan)
- `as` (asin), `ac` (acos), `at` (atan)
- `hs` (sinh), `hc` (cosh), `ht` (tanh)
== Logarithmic Functions
- `l2` (log2), `lc` (log10), `le` (ln)
- `L` (custom base log)
== Rounding Functions
- `C` (ceil), `F` (floor), `R` (round)
== Angle Conversion Functions
- `r` (deg to rad), `d` (rad to deg)
== Matrix Operation Function
- `~` (inverse)
== Conditional Branch Function
- `?` (ternary operator)
#t.example(`<true case> <false case> <cond> ?`)

= Builtin Functions
- `@a` Reference to previous result (ANS)
- `@c` Set the number of arguments consumed by the current expression
- `@d` Display top value of stack
- `@h` Access to result history (e.g., `5 @h` for 5 previous history)
- `@n` Push nan
- `@p` Duplicate the top stack value
- `@r` Random number between 0 and 1
- `@s` Access specific stack value (e.g., `5 @s` for 5 previous stack value)

= Constants
- `\E` (Euler's number)
- `\P` ($pi$)

= Lambda Expressions
- `!` evaluate lambda function at the top of the stack
#t.note([The order of function arguments is descending order.])
#t.example(`... <$3> <$2> <$1> <lambda ($0)> !`)
== Recursive Functions (experimental)
Implementation limitation do not allow for deep recursion.

#t.example(
  ```
  {$1 {$1 1 - $f! $1 *} {1} ($1 1 >) ? !} &f
  5 $f! ; -> 120
  ```
)
Explaination of function that calculate factorials by recursion:
```
{
    $1 ; save current argument
    { ; lambda 1, for lazy evaluation
        $1 1 - $f! $1 * ; f(x - 1) * x
    }
    { ; lambda 2, base
        1
    }
    ($1 1 >) ? ; select lambda 1 or 2
    ! ; eval
}
```

= Matrix Input Details
- First element is the number of columns
- Elements separated by spaces
- End matrix with `,]`
  - Example: `[2; 1 2 3 4]` creates a 2x2 matrix $mat(1,2;3,4)$
- Ignore the overhang
  - Example: `[2; 5 3m 6i 1s 99]` create a 2x2 matrix $mat(5,-3;6i,sin(1))$
  - Example: `[3; 1 2 3 4 5]` creates a 1x3 matrix $mat(1,2,3)$

= Other
- `( )`: Specify the valid range of the operator
The operators, like lisp, support variable-length arguments, so unlike pure RPNs, they need parentheses.
tips: Parentheses do not specify priority. Operators are evaluated in definitive left-to-right order without exception and do not backtrack.
```
3 4 5 + 6 *   ; (3 + 4 + 5) * 6
------|+  |
----------|*

3 (4 5 +) 6 * ; 3 * (4 + 5) * 6
   ----|+   |
------------|*
```

= Commands
- `:tc`: Toggle between real and complex number mode
- `:tp`: Toggle between explicit and implicit function in plot
- `:o`: Optimize expression (e.g., remove unnecessary spaces)
- `:p`: Plot graph (argument is `$1`, multidimensional is not supported)

= CommandLine Options
- `-h`: Show help
- `-r`: Evaluate following argument as expression
- `-q`: Quit
#t.note([Arguments whose first letter is not '-' are interpreted as file name.])

= Examples
+ Basic arithmetic: `3 4 + 2 *` #math.arrow.r $14$
+ Using constants: `\P 2 / s` #math.arrow.r $sin(pi/2) = 1$ 
+ Complex expression: `2 3 ^ (4 5 *) + (6 7 /) -` #math.arrow.r $27.142857$
+ Using previous result: `5 @a +` #math.arrow.r Adds 5 to previous result
+ Complex mode: `3 4i +` #math.arrow.r $3 + 4i$
+ Matrix addition: `[2; 1 2 3 4][2; 4 5 6 7]+` #math.arrow.r $mat(5,7;9,11)$
+ Matrix inverse: `[3; 1 1 1m 2m 0 1 0 2 1]~` #math.arrow.r $mat(-0.5,-0.75,0.25;0.5,0.25,0.25;-1,-0.5,0.5)$
+ To Chuch Boolean: `{ {2 @c $1} {2 @c $2} $1 ? } &c`
+ Plot fn: `:p $1s` #math.arrow.r Graph of $sin(x)$
+ Plot implicit fn: `:p $12^($22^)+1-` #math.arrow.r Circle of radius $1$
+ Define fn: `{$1 2 ^} &f` #math.arrow.r $f(x) = x^2$
+ Define multi-arg fn: `{$1 $2 +} &g` #math.arrow.r $g(x, y) = x + y$
+ Call fn: `5 $f !` #math.arrow.r $f(5)$
+ Call multi-arg fn: `6 7 $g !` #math.arrow.r $g(7, 6)$
+ Lambda fn: `4 {$1 2 *} !` #math.arrow.r $8$
+ Lambda multi-arg fn: `5 6 {$1 $2 -} !` #math.arrow.r $1$
+ Conditional Branch: `3 4 (5 6 <) ?` #math.arrow.r $3$
+ higher-order fn: `{$1 3 *} {5 $1!}!` #math.arrow.r $15$
+ Display help and exit: `rpx -h -q`
+ One-shot calculator: `rpx -r "1 1 +" -q`
+ One-shot graph plottor: `rpx -r ":spr (\\P 2 /) (\\P 2 /)m 1 1m" -r ":p $1s" -q`
+ Run script files: `rpx sample1.rpx sample2.rpx sample3.rpx`