dc - reverse-polish desk calculator

dc supports unlimited precision arithmetic

\$> cat file a4.dc
3 k
2.54 sx
72.0 lx / 21.0 * p
72.0 lx / 29.4 * p

\$>  dc a4.dc

normally dc reads from the standard input; if any command arguments are given to it, they are filenames, and dc reads and executes the contents of the files BEFORE reading from standard input

a calculator stores numbers on a stack

entering any number pushes it on the stack

arithmetic operations pop arguments off the stack and push the result

to enter a number in dc, type the digits (using upper case letters A through F as "digits" when working with input bases greater than ten), with an optional decimal point. exponential notation is not supported. to enter a negative number, begin the number with "_"

to enter two numbers in succession, separate them with spaces or newlines

OPTIONS

-e script
--expression=script
add the commands in script to the set of commands to be run while processing the input

-f script-file
--file=script-file
add the commands contained in the file script-file to the set of commands to be run while processing the input

COMMANDS

+
pops two values off the stack, adds them, and pushes the result

-
pops two values, subtracts the first one popped from the second one popped, and pushes the result

*
pops two values, multiplies them, and pushes the result

/
pops two values, divides the second one popped from by the first one popped, and pushes the result

%
pops two values, computes the remainder of the division that the / command would do, and pushes that

~
pops two values, divides the second one popped from by the first one popped
the quotient is pushed first, and the remainder is pushed next

^
pops two values and exponentiates, using the first value popped as the exponent and the second popped as the base

|
pops three values and computes a modular exponentiation
the first value popped is used as the reduction modulus; this value must be a integer non-zero number
the second popped is used as the exponent; this value must be a non-negative number, and any fractional part of this exponent will be ignored
the third value popped is the base which gets exponentiated, which should be an integer

v
pops one value, computes its square root, and pushes that

STACK CONTROL

p
prints the value on the top of the stack, without altering the stack
a newline is printed after the value

n
prints the value on the top of the stack, popping it off
it does not print a newline after

P
pops off the value on top of the stack
if it it a string, it is simply printed without a trailing newline
otherwise the integer portion of its absolute value is printed out as a byte stream

f
prints the entire contents of the stack without altering anything

c
clears the stack, rendering it empty

d
duplicates the value on the top of the stack, pushing another copy of it

r
reverses the order of (swaps) the top two values on the stack

REGISTERS

dc provides at least 256 memory registers, each named by a single character. you can store a number or a string in a register and retrieve it later

each register also contains its own stack. the current register value is the top of the register's stack

sr
pop the value off the top of the stack and store it into register r

lr
copy the value in register r and push it onto the stack

Sr
pop the value off the top of the (main) stack and push it onto the stack of register r
the previous value of the register becomes inaccessible

Lr
pop the value off the top of register r's stack and push it onto the main stack
the previous value in register r's stack, if any, is now accessible via the lr command

PARAMETERS

dc has three parameters that control its operation: the precision, the input radix, and the output radix

the input radix must be between 2 and 16 inclusive
the output radix must be at least 2
the precision must be zero or greater

i
pops the value off the top of the stack and uses it to set the input radix

o
pops the value off the top of the stack and uses it to set the output radix

k
pops the value off the top of the stack and uses it to set the precision

I
pushes the current input radix on the stack

O
pushes the current output radix on the stack

K
pushes the current precision on the stack

STRINGS and MACROS

dc allows you to define and call macros!

the only things you can do with strings are print them and execute them as macros

all registers and the stack can hold strings, and dc always knows whether any given object is a string or a number

[characters]
makes a string containing characters (between [ and ]), and pushes it on the stack

a
the top-of-stack is popped
if it was a number, then the low-order byte of this number is converted into a string and pushed onto the stack. otherwise the top-of-stack was a string, and the first character of that string is pushed back

x
pops a value off the stack and executes it as a macro ! WOW !
normally it should be a string; but if it is a number, it is simply pushed back onto the stack

macros are most often stored in registers;
for example [1p]sa stores a macro to print 1 into register 'a', and 'lax' invokes this macro

>r
pops two values off the stack and compares them assuming they are numbers, executing the contents of register r as a macro if the original top-of-stack is greater

!>r
similar but invokes the macro if the original top-of-stack is not greater than (less than or equal to) what was the second-to-top

<r
similar but invokes the macro if the original top-of-stack is less

!<r
similar but invokes the macro if the original top-of-stack is not less than (greater than or equal to) what was the second-to-top

=r
similar but invokes the macro if the two numbers popped are equal

!=r
similar but invokes the macro if the two numbers popped are not equal

?
reads a line from the terminal and executes it
this command allows a macro to request input from the user

q
exits from a macro and also from the macro which invoked it
if called from the top level, or from a macro which was called directly from the top level, the q command will cause dc to exit

Q
pops a value off the stack and uses it as a count of levels of macro execution to be exited
the Q command will never cause dc to exit

STATUS INQUIRY

Z
pops a value off the stack, calculates the number of digits it has (or number of characters, if it is a string) and pushes that number

X
pops a value off the stack, calculates the number of fraction digits it has, and pushes that number. for a string, the value pushed is 0

z
pushes the current stack depth: the number of objects on the stack before the execution of the z command

MISCELLANEOUS

!
will run the rest of the line as a system command
note that parsing of the !<, !=, and !> commands take precedence, so if you want to run a command starting with <, =, or > you will need to add a space after the !

#
will interpret the rest of the line as a comment

:r
will pop the top two values off of the stack
the old second-to-top value will be stored in the array r, indexed by the old top-of-stack value

;r
pops the top-of-stack and uses it as an index into the array r
the selected value is then pushed onto the stack

example

# file a4.d
3 k
[72.0 lx / 21.0 * p] sw
[72.0 lx / 29.4 * p] sh
[width  in pixels: ]P
2.54 sx
lw x
[height in pixels: ]P
lh x

\$> dc -f a4.d