A RPN calculator with some useful features and an extremely clever name.

Switch branches/tags
Nothing to show

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

## Files

Failed to load latest commit information.
Type
Name
Commit time

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

A RPN calculator with some useful features and an extremely clever name.

0.7.2 Latest
Aug 9, 2017

## Packages 0

No packages published