clac.1

.Dd May 3, 2017
.Dt CLAC 1
.
.Sh NAME
.
.Nm clac
.Nd A command line, stack-based calculator with postfix notation

.Sh SYNOPSIS
.
.Nm
.Op Ar expression
.
.Sh DESCRIPTION
.
.Nm
is a command line, stack-based calculator with postfix notation
that displays the stack contents at all times. As you type, the
stack changes are reflected immediately.
.Pp
In a stack-based postfix calculator, entering a number pushes it
on a stack, and arithmetic operations pop their arguments from the
stack and push the result. As all the operations take a fix number
of arguments, there's no room for ambiguity: parenthesis and operator
precedence are not needed. Postfix notation is also known as reverse
Polish notation, or RPN.
.
.Ss Non-interactive mode
.
If an
.Em expression
is provided, clac will process it and print each element in the
stack starting from the top. It will then exit immediately.
.
.Ss Commands
.
When a command requires an argument, it pops a value from the stack.
If the stack is empty, a zero is provided instead. In the descriptions
below, the top of the stack (and thus the first value popped) is
represented by the letter `a`, while the second value popped is
represented by the letter `b`. For example, if the stack is composed
of the number `1`, `2` and `3` (with `3` at the top of the stack),
when we describe the sum then `a` will be `3` and `b` will be `2`.
It is important to note that subtraction and division invert the
order of the arguments before performing the operation: with `1`,
`2` and `3` in the stack, when you type `-` it will pop the values
`3` and `2` and push the result of `2 - 3`. This is in the tradition
of other postfix calculators and programming languages.
.
A description of the available commands follows.
.
.Ss Arithmetic operations
.
.Bl -tag -width Fl
.It Ic +
Pop two values `a` and `b` and push the result of `a + b`.
.
.It Ic -
Pop two values `a` and `b` and push the result of `b - a`.
.
.It Ic *
Pop two values `a` and `b` and push the result of `a * b`.
.
.It Ic / 
Pop two values `a` and `b` and push the result of `b / a`.
.El
.
.Ss Modulo operation
.
.Bl -tag -width Fl
.It Ic %
Pop two values `a` and `b` and push the remainder of the Euclidean
division of `b` by `a`.
.El
.
.Ss Exponentiation
.
.Bl -tag -width Fl
.It Ic ^
Pop two values `a` and `b` and push the result of `b ^ a`.
.El
.
.Ss Logarithm
.
.Bl -tag -width Fl
.It Ic ln
Pop the value `a` and push its natural logarithm.
.It Ic log
Pop the value `a` and push its logarithm to base 10.
.El
.
.Ss Factorial
.
.Bl -tag -width Fl
.It Ic !
Pop the value `a` and push its factorial.
.El
.
.Ss Trigonometry
.
.Bl -tag -width Fl
.It Ic sin
Pop the value `a` and push its sine.
.It Ic cos
Pop the value `a` and push its cosine.
.It Ic tan
Pop the value `a` and push its tangent.
.El
.
.Ss Summation
.
.Bl -tag -width Fl
.It Ic sum
Pop all the values in the stack and push their sum.
.It Ic add
Pop the value `a` and remove that many items from the stack. Push
their sum.
.El
.
.Ss Rounding
.
.Bl -tag -width Fl
.It Ic ceil
Pop the value `a` and push smallest integral value greater than or
equal to `a`.
.It Ic floor
Pop the value `a` and push largest integral value less than or equal
to `a`.
.It Ic round
Pop the value `a` and push integral value nearest to `a`.
.El
.
.Ss Absolute value
.
.Bl -tag -width Fl
.It Ic abs
Pop the value `a` and push the non-negative value of `a`.
.El
.
.Ss Stack manipulation
.
.Bl -tag -width Fl
.It Ic swap
Pop two values `a` and `b` and push the values `a`, `b`.
.It Ic dup
Pop the value `a` and push the values `a`, `a`.
.It Ic roll
Pop two values `a` and `b` and rotate `b` elements in the stack `a`
times.
.It Ic drop
Remove the top of the stack.
.It Ic clear
Remove all the elements in the stack.
.It Ic count
Push the the number of items in the stack.
.It Ic _
Push on the stack the result of the last operation.
.El
.
.Ss Stashing
.
.Bl -tag -width Fl
.It Ic stash
Pop the value `a` and move that many items to the stash.
.It Ic fetch
Pop the value `a` and move that many items from the stash.
.It Ic .
Stash the top of the stack.
.It Ic ,
Fetch one stashed item.
.It Ic :
Stash all the items in the stack.
.It Ic ;
Fetch all stashed items.
.El
.
.Ss History
.
Use
.Aq Ic C-p
/
.Aq Ic C-n
or
.Aq Ic Up
/
.Aq Ic Down
to navigate the history.
.
.Ss User defined operations
.
It is possible to define operations (or
.Em words ,
as they are usually called in stack based programming languages)
by editing the
.Pa words
configuration file. It is not created by default, but clac will use
some environment variables in order to search for word definitions.
.
.Bl -tag -width X
.It Ic $CLAC_WORDS
If set, it should point to a file containing word definitions.
.It Ic $XDG_CONFIG_HOME
If set, clac will search for
.Pa $XDG_CONFIG_HOME/clac/words
.It Ic $HOME
If set, clac will search for
.Pa $HOME/.config/clac/words
.El
.
.Ss How to define words
.
Words are defined as aliases, with one alias on each line. Empty
lines are ignored. Here are some examples:
.Pp
.Dl Sy pi No 3.141592
.Dl Sy tau Qq "pi 2 *"
.Dl Sy sqrt Qq "0.5 ^"
.Pp
Note that an alias has two parts: a word to be defined and its
meaning. That's why the
.Sy tau
and
.Sy sqrt
definitions are enclosed in double quotes. If the double quotes are
removed, clac will complain that it can't parse the command. For
example, if we remove the double quotes from
.Sy sqrt
and start clac, we will get this error message:
.Pp
.Dl Incorrect definition: sqrt 0.5 ^
.Dl (~/.config/clac/words:3)
.Pp
User defined words can be used as if they were built-in commands:
.Pp
.Dl $ clac Qq "42 dup * pi *"
.Dl Sy 5541.76
.
.Ss How to list defined words
.
If you type `words` and hit enter, clac will list the defined words.
.
.Ss How to reload defined words
.
If you type `reload` and hit enter, clac will reload the words file.
.
.Sh EXAMPLES
.
While the most interesting aspect of clac is the ability to visualize
the stack as it is updated with each key press, at some point you
may want use clac just to get a quick result or call it from a
script. For that reason, clac can be used in non-interactive mode
by invoking it with an argument.
.Pp
Here are some examples of non-interactive invocations:
.Pp
.Dl $ clac Qq "3 4 +"
.Dl Sy 7
.Pp
.Dl $ clac Qq "2 3 4 +"
.Dl Sy 7
.Dl Sy 2
.Pp
When clac finishes evaluating the expression "2 3 4 +", there are
two elements in the stack: the number 7 at the top of the stack and
the number 2 at the bottom of the stack. The elements are printed
in order, one per line, starting from the top of the stack.
.Pp
This other example uses the stashing features. Let's say we want
to push two numbers and get the result of their multiplication plus
the square of the second number.
.Pp
.Dl $ clac Qq "4 3 dup dup * . * , +"
.Dl Sy 21
.Pp
Another example that uses the stash would be to get the average of
all the elements in the stack:
.Pp
.Dl $ clac Qq "1 2 3 4 count . sum , /"
.Dl Sy 2.5
.Pp
In fact, if you find yourself calculating averages very often, you can
define the word
.Sy avg
as
.Qq Sy "count . sum , /" .
.
.Sh AUTHOR
.An Michel Martens Aq mail@soveran.com