AD

The RPN Calculator With An Extremely Clever Name

ad, as in, after bc, but also as in the first two letters of the common mathematical operation, add.

Usage

ad is a stack-based Reverse Polish Notation calculator application. If you're familiar with the command-line UNIX application dc, you'll understand how it works. There's also bc, which is not RPN and therefore not particularly germane, but is necessary for the pun to work.

Here's a sample line of dc input from Wikipedia:

12 _3 4 ^ + 11 / v 22 -
p 

This is interpreted as a series of commands for manipulating a stack of numbers, where values are pushed onto the top of the stack and then popped off the top of the stack later to be operated on, with the result being pushed back onto the top of the stack:

1. Push 12.
2. Push -3.
3. Push 4.
4. Pop 4 and -3, Raise -3 to the 4th power and push the result.
5. Pop the result of (4) and 12, add them, and push the result.
6. Push 11.
7. Pop 11 and the result of (5), divide (5) by 11 and push the result.
8. Pop (7), calculate the square root, and push the result.
9. Push 22.
10. Pop 22, pop (8), subtract 22 from (8).

Finally, the p command prints the top of the stack, which is now occupied by the result of the whole expression.

The same sequence of operations in ad is:

12 -3 4 ^ + 11 / sqrt 22 -
p

Where ^ can also be written as **.

Inputs

ad accepts commands on the command line or through stdin.

Command Line Arguments

Shell operators can be individually escaped or the whole input can be quoted.

; ad 12 -3 4 \^ + 11 / sqrt 22 -
-19.09232989241464
; ad '12 -3 4 ^ + 11 / sqrt 22 -'
-19.09232989241464

Pipes

; echo '12 -3 4 ^ + 11 / sqrt 22 -' | ad
-19.09232989241464

Interactive mode

By calling ad with no arguments, the user can enter the interactive shell.

; ad
> 12 -3 4 ^ + 11 / sqrt 22 -
> p
-19.09232989241464
> 

Entering the q command in the shell will display the topmost element of the stack and quit.

The stack will be represented as a space-separated list of number values between two square brackets, with the bottom-most/lowest element on the left.

There are some commands designed to make interactive use of ad slightly more powerful and convenient. Among them is the ?? or explain-all command, which we can also use to give an overview of the other commands available:

; ad
> 12 -3 4 ^ + 11 2.5
> ??
stack op peek:                     [peek at stack]
stack op quit:                              [quit]
stack op show:                        [show stack]
stack op clear:                      [clear stack]
stack op dup:                      [duplicate 2.5]
stack op swap:                   [swap 11 and 2.5]
stack op drop:                          [drop 2.5]
stack op pop:                 [print and drop 2.5]
stack op ?:                          [explain 2.5]
stack op ??:                       [explain stack]
stack op hist:                      [show history]
stack op =:                     [define 2.5 as 11]
stack op undef:         [remove definition of 2.5]
stack op vars:               [display variables]
unary op sqr:                    [93 11 (2.5 ^ 2)]
unary op abs:                      [93 11 (|2.5|)]
unary op neg:                       [93 11 (-2.5)]
unary op sqrt:        [93 11 (square root of 2.5)]
unary op !:                         [93 11 (2.5!)]
unary op floor:             [93 11 (floor of 2.5)]
unary op ceil:            [93 11 (ceiling of 2.5)]
unary op round:                [93 11 (round 2.5)]
binary op +:                       [93 (11 + 2.5)]
binary op -:                       [93 (11 - 2.5)]
binary op *:                       [93 (11 * 2.5)]
binary op /:                       [93 (11 / 2.5)]
binary op ^:                       [93 (11 ^ 2.5)]
binary op >:                       [93 (11 > 2.5)]
binary op <:                       [93 (11 < 2.5)]
binary op ==:                     [93 (11 == 2.5)]
trinary op cond:        [(if 93 then 11 else 2.5)]
> 

Binary Operations

+, -, *, /, ^: Ordinary arithmetic operations.

Unary Operations

sqr, abs, neg, sqrt, !, floor, ceil, round: Mathematic operations on the topmost element.

Stack Operations

peek, show, clear, dup, swap, drop, pop: These commands manipulate the stack, by printing it or mutating it.

hist: Displays the results of each operation so far.

> 12 -3 4 ^ + 11 2.5
> hist
2: 93
1: 81

Conditional Operations

<, >, ==: Evaluates relations between the top two elements on the stack. Pushes a 1 for true and a 0 for false.

cond: Evaluates the antepenultimate element on the stack for truth (0 is false, everything else is true) and returns the penultimate element to the stack if true, otherwise the ultimate one.

Variable Operations

Any command that starts with a or ' will be treated as a symbol rather than as a value. This allows the user to define variables. The unevaluated symbol will be pushed to the top of the stack, and then can be used as the argument to the =/def` command.

> 36 4 + 'lucky-number =
> s
[]
> 

(s is short for show) lucky-number is now defined as the result of 36 4 +.

> lucky-number 2 *
> .
80
> 

(. is short for pop)

vars: Display all currently assigned variables.

> vars
lucky-number: 40

undef: Remove the definition of a variable.

> `lucky-number undef
> vars
> lucky-number
Unrecognized token: lucky-number

Quoting a symbol can also be used with the ? command, which takes a quoted operator name as its argument.

?: Explain an operator.

> 4 5
> '+ ?
binary op +:                             [(4 + 5)]

How to Get it

ad is written in the Nim programming language. The easiest way to install is to use the nimble package manager:

nimble install ad