\title \spigot: an exact real calculator

This manual documents \spigot, a command-line exact real calculator.

\C{introduction} What is \spigot?

\spigot is a calculating program. It supports the usual arithmetic
operations, square and cube roots, trigonometric and exponential
functions, and a few other special functions such as \cw{erf}.

\spigot differs from the average calculating program in that it is an
\e{exact real} calculator. This means that it does not suffer from
rounding errors; in principle, it can keep generating more and more
digits of the number you asked for until it runs out of memory.

In particular, if you ask for a complex expression such as
\cw{sin(sqrt(pi))}, then most calculating systems would compute first
\cw{pi}, then \cw{sqrt(pi)} and finally \cw{sin(sqrt(pi))},
accumulating a rounding error at each step, so that the final result
had a build-up of error and you would have to do some additional error
analysis to decide how much of the output you could trust.

\spigot, on the other hand, does not output any digit until it is sure
that digit is correct, so if you ask for (say) 100 digits of
\cw{sin(sqrt(pi))} then you can be sure they are the \e{right} 100
digits.

(The downside of doing this is that \spigot is \e{slow}, compared to
the more usual methods of computer arithmetic. You wouldn't want to
use even its individual arithmetic operations and functions for any
kind of bulk computation. And because it evaluates a complicated
expression as a whole, it's especially unsuited to any iterative
algorithm which involves looking at the first result you get and then
deciding what further arithmetic to do on it: normal arithmetic
systems can do the next step of the algorithm with only the cost of
the extra operations, but \spigot would have to re-evaluate the entire
thing from the start every time. So \spigot can be useful if you
really do need a lot of digits, or if you're doing a computation prone
to numerical error, or as a cross-check on other calculating systems,
but it wouldn't be usable outside that kind of specialist niche.)

\spigot can evaluate expressions starting from numbers it can
construct internally (integers, rationals, \pi, etc), and it can also
read a number from a file or a pipe. In the latter mode, it operates
\q{on-line}, i.e. it writes output as it goes along, and once it has
read enough digits of an input number to know some of the output, it
will print it.

\C{examples} Examples of using \spigot

The simplest thing \spigot can do is to compute well-known
mathematical constants such as \pi. For example, try running this
command:

\c $ spigot pi
\e   bbbbbbbbb
\c 3.1415926535897932384626433832795028841971693993751058209749445923078164
\c 062862089986280348253421170679821480865132823066470938446095505822317253
\c 594081284811174502841027019385211055596446229489549303819644288109756659
\c (and so on)
\e iiiiiiiiiii

In this default mode, \spigot generates unbounded output: it will
continue writing digits of \pi to the terminal until you interrupt it
(e.g. by pressing Ctrl-C).

As \spigot generates more digits, it will slow gradually down and
consume more and more memory to keep track of where it's got to, and
one of time and memory will ultimately be the limit to how much data
it can generate. But in principle, given unlimited time and memory, it
could just keep on going.

\spigot can also evaluate more complicated mathematical expressions.
(Some will be much slower than others.) You could try some of these,
for example:

\c $ spigot pi*e
\e   bbbbbbbbbbb
\c $ spigot pi/e
\e   bbbbbbbbbbb
\c $ spigot pi^e
\e   bbbbbbbbbbb
\c $ spigot -- '-pi^2'
\e   bbbbbbbbbbbbbbbbb
\c $ spigot 'sin(sqrt(pi))'
\e   bbbbbbbbbbbbbbbbbbbbbb
\c $ spigot 'exp(pi*sqrt(163))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbb

(The above command lines assume that you are invoking \spigot from a
POSIX shell, so that expressions containing parentheses need to be
single-quoted in order for \spigot to receive them unmodified without
the shell interfering. On other shells or operating systems, quoting
conventions may vary.)

Since \spigot supports a variety of command-line options beginning
with \c{-}, if your expression also begins with a \c{-} (as one of the
examples above does), then you need to precede it with the special
argument word \c{--}, which instructs \spigot to treat further
command-line arguments as an expression rather than an option.

See \k{expr} for a full description of the range of expressions you
can give to \spigot.

\H{rounding} Digit limits and rounding

In its default mode, \spigot keeps generating digits until you
interrupt it, or until it determines that it has output the exactly
correct answer and needs no more digits at all.

You can limit \spigot to a finite number of digits by using the
\cw{-d} option. For example:

\c $ spigot -d40 pi
\e   bbbbbbbbbbbbbb
\c 3.1415926535897932384626433832795028841971

(The argument to \cw{-d} counts decimal places, rather than
significant figures. So here, there are 40 digits after the decimal
point.)

By default, \spigot does no rounding, i.e. it simply truncates the
full decimal expansion of the number you asked for. (This is
equivalent to rounding towards zero in all cases.)

If you want to change that, there's a variety of rounding-mode
options, detailed in \k{rmodeopts}. For example, you can ask \spigot to
round the final digit towards whichever value is nearer to the true
result using \cw{--rn}:

\c $ spigot --rn -d40 pi
\e   bbbbbbbbbbbbbbbbbbb
\c 3.1415926535897932384626433832795028841972

(This example rounds up, because the next digit following the 1 is a
6.)

\H{bases} Generating output in different bases

By default, \spigot's output is in base 10. You can use the \cw{-b}
option to output in another base instead:

\c $ spigot -b2 -d40 pi
\e   bbbbbbbbbbbbbbbbbb
\c 11.0010010000111111011010101000100010000101
\c $ spigot -b3 -d40 pi
\e   bbbbbbbbbbbbbbbbbb
\c 10.0102110122220102110021111102212222201112
\c $ spigot -b16 -d40 pi
\e   bbbbbbbbbbbbbbbbbbb
\c 3.243f6a8885a308d313198a2e03707344a4093822
\c $ spigot -b36 -d40 pi
\e   bbbbbbbbbbbbbbbbbbb
\c 3.53i5ab8p5fsa5jhk72i8asc47wwzlacljj9zn98l

For bases larger than 10, letters of the alphabet are used as
additional digits. If you use the \cw{-B} option in place of \cw{-b},
those letters will be displayed in upper case:

\c $ spigot -B16 -d40 pi
\e   bbbbbbbbbbbbbbbbbbb
\c 3.243F6A8885A308D313198A2E03707344A4093822

\H{cfrac} Generating continued fractions of numbers

As well as generating numbers in ordinary base notation, \spigot can
also generate them in the form of continued fractions. You can
generate the continued fraction terms of a number, one per line, using
the \cw{-c} option:

\c $ spigot -c pi
\e   bbbbbbbbbbbb
\c 3
\c 7
\c 15
\c 1
\c 292
\c 1
\c (and so on)
\e iiiiiiiiiii

(For those unfamiliar with continued fractions, this is equivalent to
saying that \pi is equal to \cw{3 + 1 / (7 + 1 / (15 + 1 / ...))}.)

This one-per-line format is useful for applications which are
consuming the numbers automatically, but for readability, you might
prefer to add \cw{-l} to replace the newlines with commas, so that you
can see many more terms at once:

\c $ spigot -c -l pi
\e   bbbbbbbbbbbbbbb
\c 3;7,15,1,292,1,1,1,2,1,3,1,14,2,1,1,2,2,2,2,1,84,2,1,1,15,3,13,1,4,2,6,6
\c ,99,1,2,2,6,3,5,1,1,6,8,1,7,1,2,3,7,1,2,1,1,12,1,1,1,3,1,1,8,1,1,2,1,6,1
\c ,1,5,2,2,3,1,2,4,4,16,1,161,45,1,22,1,2,2,1,4,1,2,24,1,2,1,3,1,2,1,1,10,
\c (and so on)
\e iiiiiiiiiii

(The semicolon emphasises that the first number is the integer part.)

Finally, you can use \cw{-C} to output the continued fraction
\e{convergents} (that is, the rational numbers obtained by evaluating
successive truncations of the continued fraction, which are the best
approximations to the target number by a particular metric):

\c $ spigot -C pi
\e   bbbbbbbbbbbb
\c 3/1
\c 22/7
\c 333/106
\c 355/113
\c 103993/33102
\c 104348/33215
\c (and so on)
\e iiiiiiiiiii

In any of these modes, the \cw{-d} option allows you to limit the
number of continued fraction terms or convergents that \spigot
outputs. Again, the integer part is not counted, so that for example
\cw{-d3} gives you three terms or convergents \e{as well} as the
integer one:

\c $ spigot -c -d3 pi
\e   bbbbbbbbbbbbbbbb
\c 3
\c 7
\c 15
\c 1

\c $ spigot -C -d3 pi
\e   bbbbbbbbbbbbbbbb
\c 3/1
\c 22/7
\c 333/106
\c 355/113

\H{input} Reading input numbers from a file or another program

As well as applying its collection of mathematical operators and
functions to real numbers that it has derived itself from first
principles, \spigot can also apply the same operations to numbers
received as input from elsewhere, which makes it at least
theoretically able to operate on \e{any} real number.

To begin with, you can write a number into a file in ordinary decimal
notation, and use a special syntax in the \spigot expression language
to read from that file:

\c $ echo 1.12358132134558914423337761098715972584418167651094617711 > z
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c $ spigot -d30 'sin( base10file:z )'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c 0.901654985409730168388244848164

You might wonder why \spigot needs a feature like this: since the file
contains only a finite amount of data, you surely could just have
pasted the same number on to \spigot's command line directly. The
difference is that if you write a decimal number on \spigot's command
line, \spigot will assume it is \e{exact}, i.e. that the precise
number you meant is the rational number with that terminating decimal
expansion. But if you read from a file like this, \spigot will treat
it as a prefix of some longer decimal expansion, and if it reaches the
end of the file then it will report a special error saying that it
can't compute any more output digits because it ran out of input. So
this permits you to compute with imperfectly known inputs, without the
risk of generating any incorrect digits of output due to the input
imprecision.

You can also tell \spigot to read from a file in number bases other
than 10, or in continued fraction format. See \k{filefd} for full
details of all the available options.

But \spigot can also read input from a Unix file \e{descriptor}
(assuming it's compiled on a system where that facility exists), which
can point at an unbounded data source such as a pipe. So if you invoke
\spigot with a file descriptor pointing at such a pipe, with a program
at the other end of the pipe prepared to generate as many digits of
the number as requested, then you need only use another special piece
of expression syntax to tell \spigot to read a real number from it, as
far as is necessary.

For example, let's generate
\W{http://en.wikipedia.org/wiki/Champernowne_constant}{the
Champernowne constant}, which you get by concatenating all the
positive integers in order immediately after the decimal point, with
no leading zeroes. Here's a piece of Perl which generates that:

\c $ perl -e 'print"0.";print while++$_'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c 0.1234567891011121314151617181920212223242526272829303132333435363738394
\c 041424344454647484950515253545556575859606162636465666768697071727374757
\c 677787980818283848586878889909192939495969798991001011021031041051061071
\c (and so on)
\e iiiiiiiiiii

Now we can use \spigot to compute with this number (or any other input
real), by piping that script's output into \spigot, and telling
\spigot to expect to read a base-10 number from file descriptor 0 (its
standard input). As a really simple example, let's ask for \spigot to
output the same number, but in continued fraction form:

\c $ perl -e 'print"0.";print while++$_' | spigot -c -l base10fd:0
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c 0;8,9,1,149083,1,1,1,4,1,1,1,3,4,1,1,1,15,457540111391031076483646628242
\c 956118599603939710457555000662004393090262659256314937953207747128656313
\c 8641209375503552094607183089984575801469863148833592141783010987,6,1,1,2
\c 1,1,9,1,1,2,3,1,7,2,1,83,1,156,4,58,8,54,4457353800911178833959067671634
\c 293788437292958096324947188556700067877659324583930837874799958333344441
\c (and so on)
\e iiiiiiiiiii

(Apart from it being very easy to generate, another reason I chose
this example constant is because it has interestingly large numbers in
its continued fraction \dash the huge number spanning the first three
lines occurs because there's an extremely good rational approximation
to the constant at the point where numbers change from 2 to 3 digits.
The number starting on the fourth line is the corresponding term at
the 3/4 digit boundary, and goes on for far longer!)

You can also use the expression \cw{base10fd:0} as part of a larger
expression, so that you could compute mathematical functions of an
input number, or add it to things (perhaps another input pipe, if you
execute \spigot in such a way as to assign multiple input fds).

\C{expr} \spigot's expression language

This section gives a full specification of the language \spigot uses
for mathematical expressions.

\spigot's expression language is semantically simpler than most such
languages. In deference to the limitations of efficient computing,
most expression languages have to carefully distinguish a collection
of numeric types representing different subsets of the real numbers
with different tradeoffs between range, precision and performance. But
\spigot, because its whole purpose is to deal in exact real numbers
regardless of performance, does not have to do this. Every expression
and subexpression in \spigot has the same type: \s{real}.

So you don't have to remember to avoid writing \cw{1/2} for a half
(which in, say, \cw{gnuplot}, would be interpreted as \e{integer}
division and yield a rounded-down quotient of zero), or include any
explicit syntax to change between formats as appropriate. Just write
what looks like the obvious thing, and it will probably mean what you
wanted.

\H{operators} Operators

\spigot's expression language provides the following mathematical
operators:

\b Addition, written as \e{a}\_\cw{+}\_\e{b} (for two subexpressions
\e{a} and \e{b}).

\b Subtraction, written as \e{a}\_\cw{-}\_\e{b}.

\b Multiplication, written as \e{a}\_\cw{*}\_\e{b}. You can also write
this by juxtaposition, i.e. just write \e{a}\_\e{b}. For example,
\cw{(pi+2)(pi+3)} is a valid \spigot expression, synonymous with
\cw{(pi+2)*(pi+3)}.

\b Division, written as \e{a}\_\cw{/}\_\e{b}. As mentioned in the
previous section, this is the real-number division operation, with no
implicit rounding to integers in any circumstances. It is an error to
use this operator with \e{b}\_\cw{=}\_\cw{0}.

\b Modulus, written as \e{a}\_\cw{%}\_\e{b} or \e{a}\_\cw{mod}\_\e{b}
(the two syntaxes are synonymous). This returns a value of the form
\e{a}\_\cw{-}\_\e{nb}, with \e{n} chosen to be whichever integer
puts the result in the range \cw{[0,}\e{b}\cw{)} (if \e{b} is positive)
or \cw{(}\e{b}\cw{,0]} (if \e{b} is negative).

\b Remainder, written as \e{a}\_\cw{rem}\_\e{b}. This also returns a
value of the form \e{a}\_\cw{-}\_\e{nb}, but with slightly different
semantics: this operation chooses \e{n} to be whichever integer puts
the result in the range \cw{[-}\e{b}\cw{/2,+}\e{b}\cw{/2]}. In case of
a tie (if the result is precisely half way between two integer
multiples of \e{b}, so that two different values of \e{n} meet that
constraint), the answer is chosen to also make \e{n} an even number.
(This is the same semantics as the IEEE 754 remainder operation.)

\b Power, written as \e{a}\_\cw{^}\_\e{b} or \e{a}\_\cw{**}\_\e{b} (the
two syntaxes are synonymous).

\b Negation, written as \cw{-}\_\e{a}.

\b The construction \cw{+}\_\e{a} is supported for symmetry with
\cw{-}\_\e{a}, but does nothing (just returns \e{a} unchanged).

The priorities and associativity of these operators, from lowest to
highest, are as follows.

\b The addition and subtraction operators \c{+} and \c{-} have lowest
priority, and associate left to right. (E.g. an expression such as
\e{a}\cw{-}\e{b}\cw{+}\e{c}\cw{-}\e{d} is treated as if it were
\cw{(((}\e{a}\cw{-}\e{b}\cw{)+}\e{c}\cw{)-}\e{d}\cw{)}.)

\b The multiplication and division operators \c{*}, \c{/}, \c{%} and
its synonym \c{mod}, and \c{rem} have the next higher priority, and
also associate left to right. Multiplication by juxtaposition is
included in this: when two numbers or parenthesised expressions appear
adjacent in an expression, the parser imagines a \c{*} between them,
and treats that \c{*} with the same priority as if it had been
explicit.

\b The negation and no-op operators \c{-} and \c{+} have the next
higher priority. Since these are unary operators, there is no question
of which way they associate: \cw{--}\e{a} has only one possible parse
in any case, namely \cw{-(-}\e{a}\cw{)}.

\b \c{^} and its synonym \c{**} have the highest priority. These
operators associate right to left, i.e. \e{a}\cw{^}\e{b}\cw{^}\e{c}
parses as if it had been \e{a}\cw{^(}\e{b}\cw{^}\e{c}\cw{)}. Note that
since these operators have higher priority than the unary operators,
\cw{-}\e{a}\cw{^}\e{b} parses as \cw{-(}\e{a}\cw{^}\e{b}\cw{)}, rather than
the usually less helpful \cw{(-}\e{a}\cw{)^}\e{b}.

\H{functions} Functions

As well as infix and prefix operators, \spigot also supports a range
of mathematical functions, all written in the style
\cw{function(}\e{argument}\cw{)} or
\cw{function(}\e{argument1}\cw{,}\e{argument2}\cw{)}. The following
functions are provided:

\b \cw{sqrt(}\e{x}\cw{)} returns the square root of \e{x}. It is an
error to use this function with \e{x}\_\cw{<}\_\cw{0}.

\b \cw{cbrt(}\e{x}\cw{)} returns the cube root of \e{x}.

\b \cw{hypot(}\e{x}\cw{,}\e{y}\cw{)} returns the hypotenuse of a right
triangle with legs \e{x} and \e{y}, or equivalently, the square root
of \e{x}\cw{^2}\_\cw{+}\_\e{y}\cw{^2}.

\b \cw{sin(}\e{x}\cw{)} returns the sine of \e{x}, interpreted in
radians.

\b \cw{cos(}\e{x}\cw{)} returns the cosine of \e{x}, interpreted in
radians.

\b \cw{tan(}\e{x}\cw{)} returns the tangent of \e{x}, interpreted in
radians. In theory, it would be an error to use this function with
\e{x} being an odd integer multiple of \pi\cw{/2}; in practice, \spigot
will never actually notice. (See \k{hazards} for some discussion of
this.)

\b \cw{asin(}\e{x}\cw{)} returns an angle \theta in radians, in the
range \cw{[-}\pi\cw{/2,+}\pi\cw{/2]}, such that
\cw{sin(}\theta\cw{)}\_\cw{=}\_\e{x}. It is an error to use this function
if \e{x} is not in the range \cw{[-1,+1]}.

\b \cw{acos(}\e{x}\cw{)} returns an angle \theta in radians, in the
range \cw{[0,+}\pi\cw{]}, such that \cw{cos(}\theta\cw{)}\_\cw{=}\_\e{x}.
It is an error to use this function if \e{x} is not in the range
\cw{[-1,+1]}.

\b \cw{atan(}\e{x}\cw{)} returns an angle \theta in radians, in the
range \cw{[-}\pi\cw{/2,+}\pi\cw{/2]}, such that
\cw{tan(}\theta\cw{)}\_\cw{=}\_\e{x}.

\b \cw{atan2(}\e{y}\cw{,}\e{x}\cw{)} returns an angle \theta in radians,
in the range \cw{(-}\pi\cw{,+}\pi\cw{]}, such that the vector
\cw{(sin(}\theta\cw{),cos(}\theta\cw{))} is a positive real multiple of the
input vector \cw{(}\e{y}\cw{,}\e{x}\cw{)}. It is an error to use this
function with \e{y}\_\cw{=}\_\e{x}\_\cw{=}\_\cw{0}.

\b \cw{sind(}\e{x}\cw{)} returns the sine of \e{x}, interpreted in
degrees.

\b \cw{cosd(}\e{x}\cw{)} returns the cosine of \e{x}, interpreted in
degrees.

\b \cw{tand(}\e{x}\cw{)} returns the tangent of \e{x}, interpreted in
degrees. It is an error to use this function with \e{x} being an odd
integer multiple of 90.

\b \cw{asind(}\e{x}\cw{)} returns an angle \theta in degrees, in the
range \cw{[-90,+90]}, such that \cw{sind(}\theta\cw{)}\_\cw{=}\_\e{x}.
It is an error to use this function if \e{x} is not in the range
\cw{[-1,+1]}.

\b \cw{acosd(}\e{x}\cw{)} returns an angle \theta in degrees, in the
range \cw{[0,+180]}, such that \cw{cosd(}\theta\cw{)}\_\cw{=}\_\e{x}.
It is an error to use this function if \e{x} is not in the range
\cw{[-1,+1]}.

\b \cw{atand(}\e{x}\cw{)} returns an angle \theta in degrees, in the
range \cw{[-90,+90]}, such that \cw{tand(}\theta\cw{)}\_\cw{=}\_\e{x}.

\b \cw{atan2d(}\e{y}\cw{,}\e{x}\cw{)} returns an angle \theta in
degrees, in the range \cw{(-180,+180]}, such that the vector
\cw{(sind(}\theta\cw{),cosd(}\theta\cw{))} is a positive real multiple
of the input vector \cw{(}\e{y}\cw{,}\e{x}\cw{)}. It is an error to
use this function with \e{y}\_\cw{=}\_\e{x}\_\cw{=}\_\cw{0}.

\b \cw{exp(}\e{x}\cw{)} returns \e{e} to the power of \e{x}.

\b \cw{exp2(}\e{x}\cw{)} returns 2 to the power of \e{x}.

\b \cw{exp10(}\e{x}\cw{)} returns 10 to the power of \e{x}.

\b \cw{log(}\e{x}\cw{)} returns the natural logarithm of \e{x}. It is an
error to use this function if \e{x}\_\cw{<=}\_\cw{0}.

\b \cw{log(}\e{x}\cw{,}\e{b}\cw{)} returns the logarithm of \e{x} to
the base \e{b}. It is an error to use this form of the \c{log}
function if \e{x}\_\cw{<=}\_\cw{0}, or if \e{b}\_\cw{<=}\_\cw{0}, or
if \e{b}\_\cw{=}\_\cw{1}.

\b \cw{log2(}\e{x}\cw{)} returns the logarithm of \e{x} to the base 2.
It is an error to use this function if \e{x}\_\cw{<=}\_\cw{0}.

\b \cw{log10(}\e{x}\cw{)} returns the logarithm of \e{x} to the base 10.
It is an error to use this function if \e{x}\_\cw{<=}\_\cw{0}.

\b \cw{expm1(}\e{x}\cw{)} returns the same as
\cw{exp(}\e{x}\cw{)}\_\cw{-}\_\cw{1}.

\b \cw{log1p(}\e{x}\cw{)} returns the same as
\cw{log(1}\_\cw{+}\_\e{x}\cw{)}. It is an error to use this function if
\e{x}\_\cw{<=}\_\cw{-1}.

\b \cw{pow(}\e{x}\cw{,}\e{y}\cw{)} returns \e{x} raised to the power
\e{y}. This is synonymous with the \c{^} and \c{**} operators
described in \k{operators}, and included for convenience if pasting
expressions out of languages such as C.

\b \cw{sinh(}\e{x}\cw{)} returns the hyperbolic sine of \e{x}.

\b \cw{cosh(}\e{x}\cw{)} returns the hyperbolic cosine of \e{x}.

\b \cw{tanh(}\e{x}\cw{)} returns the hyperbolic tangent of \e{x}.

\b \cw{asinh(}\e{x}\cw{)} returns the value \e{y} such that
\cw{sinh(}\e{y}\cw{)}\_\cw{=}\_\e{x}.

\b \cw{acosh(}\e{x}\cw{)} returns the non-negative value \e{y} such that
\cw{cosh(}\e{y}\cw{)}\_\cw{=}\_\e{x}. It is an error to use this function
if \e{x}\_\cw{<}\_\cw{1}.

\b \cw{atanh(}\e{x}\cw{)} returns the value \e{y} such that
\cw{tanh(}\e{y}\cw{)}\_\cw{=}\_\e{x}. It is an error to use this function
if \e{x} is not in the range \cw{[-1,+1]}.

\b \cw{gamma(}\e{x}\cw{)} and \cw{tgamma(}\e{x}\cw{)} return the gamma
function of \e{x}. (The two function names are synonymous \dash
\cw{tgamma} is provided for convenience if pasting expressions out of
C.) It is an error to use this function if \e{x} is a negative integer
or zero.

\b \cw{lgamma(}\e{x}\cw{)} returns the logarithm of
\cw{gamma(}\e{x}\cw{)}, or the logarithm of \cw{-gamma(}\e{x}\cw{)} if
\cw{gamma(}\e{x}\cw{)}\_\cw{<}\_\cw{0}. It is an error to use this
function if \e{x} is a negative integer or zero.

\b \cw{erf(}\e{x}\cw{)} returns the error function of \e{x}.

\b \cw{erfc(}\e{x}\cw{)} returns the same as
\cw{1}\_\cw{-}\_\cw{erf(}\e{x}\cw{)}.

\b \cw{Phi(}\e{x}\cw{)} and \cw{norm(}\e{x}\cw{)} return the cumulative
normal distribution function of \e{x}. (The two names are synonymous.)

\b \cw{erfinv(}\e{x}\cw{)} and \cw{inverf(}\e{x}\cw{)} both return the
value \e{y} such that \cw{erf(}\e{y}\cw{)}\_\cw{=}\_\e{x}. It is an
error to use this function if \e{x} is not in the range \cw{(-1,+1)}.

\b \cw{erfcinv(}\e{x}\cw{)} and \cw{inverfc(}\e{x}\cw{)} both return
the value \e{y} such that \cw{erfc(}\e{y}\cw{)}\_\cw{=}\_\e{x}. It is
an error to use this function if \e{x} is not in the range \cw{(0,2)}.

\b \cw{Phiinv(}\e{x}\cw{)}, \cw{norminv(}\e{x}\cw{)},
\cw{invPhi(}\e{x}\cw{)} and \cw{invnorm(}\e{x}\cw{)} all return the
value \e{y} such that \cw{Phi(}\e{y}\cw{)}\_\cw{=}\_\e{x}. It is an
error to use this function if \e{x} is not in the range \cw{(0,1)}.

\b \cw{W(}\e{x}\cw{)} and \cw{Wn(}\e{x}\cw{)} are the two branches of
the Lambert W function. Each of them returns a value \e{y} such that
\e{y}\_\cw{exp(}\e{y}\cw{)}\_\cw{=}\_\e{x}. \cw{W(}\e{x}\cw{)} returns
\e{y}\_\cw{>=}\_\cw{-1}, and it is an error to use it if
\e{x}\_\cw{<}\_\cw{-1/e}; \cw{Wn(}\e{x}\cw{)} returns
\e{y}\_\cw{<=}\_\cw{-1}, and it is an error to use it if \e{x} is not
in the range \cw{[-1/e,0)}.

\b \cw{Ei(}\e{x}\cw{)} is the indefinite integral of
\cw{exp(}\e{x}\cw{)/}\e{x}, defined in the negative domain so that its
limit at negative infinity is zero, and defined in the positive domain
(to deal with the pole at \e{x}\_\cw{=}\_\cw{0}) so that the limit of
\cw{Ei(-}\epsilon\cw{)-Ei(+}\epsilon\cw{)} is zero as
\epsilon\_\tendsto\_\cw{0}. It is an error to use this function with
\e{x}\_\cw{=}\_\cw{0}.

\b \cw{En(}\e{n}\cw{,}\e{x}\cw{)} is defined for non-negative integer
\e{n}, and is the \e{n}-times-iterated indefinite integral of
\cw{exp(-}\e{x}\cw{)/}\e{x}. That is, \cw{En(0,}\e{x}\cw{)} is just
equal to \cw{exp(-}\e{x}\cw{)/}\e{x}; and for all larger \e{n},
\cw{En(}\e{n}\cw{,}\e{x}\cw{)} is the indefinite integral of
\cw{-En(}\e{n}\cw{-1,}\e{x}\cw{)}, defined so that its limit at
infinity is zero. (The sign is flipped each time so that the function
is positive for all \e{n}.) It is an error to use this function with
\e{x}\_\cw{<}\_\cw{0}, or with \e{x}\_\cw{=}\_\cw{0} and \e{n} equal
to either \cw{0} or \cw{1}.

\b \cw{E1(}\e{x}\cw{)} is a shorthand for \cw{En(1,}\e{x}\e{)}, and is
also equal to \cw{-Ei(-}\e{x}\cw{)}. It is an error to use this
function with \e{x}\_\cw{<=}\_\cw{0}.

\b \cw{Ein(}\e{x}\cw{)} is the indefinite integral of
\cw{(1-exp(-}\e{x}\cw{))/}\e{x}, defined so that
\cw{Ein(0)}\_\cw{=}\_\cw{0}. (This is the only one of the exponential
integral family which is actually defined everywhere.)

\b \cw{li(}\e{x}\cw{)} is the indefinite integral of
\cw{1/log(}\e{x}\cw{)}, defined so that \cw{li(0)}\_\cw{=}\_\cw{0},
and dealing with the pole at \e{x}\_\cw{=}\_\cw{1} by defining the
limit of \cw{li(1-}\epsilon\cw{)-li(1+}\epsilon\cw{)} to be zero as
\epsilon\_\tendsto\_\cw{0} (the same trick as \cw{Ei} above). It is an
error to use this function with \e{x}\_\cw{<}\_\cw{0}, or with
\e{x}\_\cw{=}\_\cw{1}.

\b \cw{Li(}\e{x}\cw{)} is also the indefinite integral of
\cw{1/log(}\e{x}\cw{)}, but this time, defined so that
\cw{Li(2)}\_\cw{=}\_\cw{0}. (That is, \cw{Li} and \cw{li} only differ
by a constant.) Again, it is an error to use this function with
\e{x}\_\cw{<}\_\cw{0} or with \e{x}\_\cw{=}\_\cw{1}.

\b \cw{Si(}\e{x}\cw{)} is the indefinite integral of
\cw{sin(}\e{x}\cw{)/}\e{x}, defined so that \cw{Si(0)}\_\cw{=}\_\cw{0}.

\b \cw{si(}\e{x}\cw{)} is also the indefinite integral of
\cw{sin(}\e{x}\cw{)/}\e{x}, defined so that its limit at positive
infinity is zero.

\b \cw{Ci(}\e{x}\cw{)} is the indefinite integral of
\cw{cos(}\e{x}\cw{)/}\e{x}, defined so that its limit at positive
infinity is zero.

\b \cw{Cin(}\e{x}\cw{)} is the indefinite integral of
\cw{(1-cos(}\e{x}\cw{))/}\e{x}, defined so that
\cw{Cin(0)}\_\cw{=}\_\cw{0}.

\b \cw{FresnelS(}\e{x}\cw{)} and \cw{FresnelC(}\e{x}\cw{)} are the
normalised Fresnel integrals: the indefinite integral of
\cw{sin(}\pi\_\e{x}\cw{^2/2)} and \cw{cos(}\pi\_\e{x}\cw{^2/2)}
respectively, both defined to be zero at zero.

\b \cw{UFresnelS(}\e{x}\cw{)} and \cw{UFresnelC(}\e{x}\cw{)} are the
\q{unnormalised} Fresnel integrals, i.e. the integrals of
\cw{sin(}\e{x}\cw{^2)} and \cw{cos(}\e{x}\cw{^2)}, also defined to be
zero at zero.

\b \cw{zeta(}\e{s}\cw{)} is the Riemann zeta function for real
arguments. That is, for \e{s}\_\cw{>}\_\cw{1}, \cw{zeta(}\e{s}\cw{)}
is the infinite sum of \e{n}\cw{^-}\e{s} over all natural numbers
\e{n}. For \e{s}\_\cw{<}\_\cw{1}, the function is defined by analytic
continuation. It is an error to use this function with
\e{s}\_\cw{=}\_\cw{1}.

\b \cw{abs(}\e{x}\cw{)} returns the absolute value of \e{x}, i.e. either
\e{x} or \cw{-}\e{x}, whichever is non-negative.

\b \cw{ceil(}\e{x}\cw{)} returns the smallest integer \e{n} such that
\e{n}\_\cw{>=}\_\e{x}.

\b \cw{floor(}\e{x}\cw{)} returns the largest integer \e{n} such that
\e{n}\_\cw{<=}\_\e{x}.

\b \cw{frac(}\e{x}\cw{)} returns the fractional part of \e{x}. This is
always positive, even if \e{x} is negative; i.e. this is the same as
\e{x}\_\cw{-}\_\cw{floor(}\e{x}\cw{)}.

\b \cw{algebraic(}\e{lo}\cw{,}\e{hi}\cw{,}\e{a0}\cw{,}\e{a1}\cw{,}\hdots\cw{,}\e{an}\cw{)}
returns a root of the polynomial
\e{a0}\_\cw{+}\_\e{a1}\_\cw{x}\_\cw{+}\_\hdots\_\cw{+}\_\e{an}\_\cw{x^n}
which lies within the interval \cw{(}\e{lo}\cw{,}\e{hi}\cw{)}. It is
an error (which \spigot will not \e{reliably} detect) to use this
function if the specified polynomial does not have a unique real root
within that interval, and also an error if either of \e{lo} or \e{hi}
is not obviously rational or any polynomial coefficient is not
obviously an integer.

Some of these functions are considerably slower than others. The
inverses of \cw{erf} and \c{Phi} and the \cw{W} functions, in
particular, are implemented by laborious interval-bisection and are
very slow indeed.

\H{literals} Numeric literals

You can write actual numbers in \spigot expressions, of course. By
default a string of digits, or a string of digits with a decimal point
somewhere in it, will be interpreted in decimal.

\spigot supports C-style scientific notation, in which a decimal
number (with or without a decimal point) is suffixed with \c{e}
followed by an optional \c{+} or \c{-} and then another decimal
integer; this denotes the first number times 10 to the power of the
second. For example, \c{1.2} means 1.2, but \c{1.2e10} (or
\c{1.2e+10}) means 12000000000, and \c{1.2e-10} means 0.00000000012.

\spigot also supports hex numbers, by prefixing \c{0x} or \c{0X} to a
number, e.g. \c{0xabc} means 2748. Hex numbers can be suffixed with an
exponent part similar to the decimal one described above, only using
\c{p} in place of \c{e} as the separator character; this means the hex
number should be multiplied by the specified power of \e{two}. For
example, \c{0x1.2} means 1.125 (one and an eighth); then \c{0x1.2p1}
(or \c{0x1.2p+1}) means twice that, i.e. 2.25, and \c{0x1.2p-1} means
half of it, i.e. 0.5625.

If you want to input numbers in bases other than 10 and 16, you can
prefix a numeric literal with \c{base2:}, \c{base3:}, \hdots,
\c{base36:}. For example, you could write \c{base2:11.011}, or
\c{base36:ZYX.WVU}. No exponent suffix is recognised in this mode,
because there's no solid convention for what it should look like or
even what should be raised to the specified power (since the usual
exponent-bases for bases 10 and 16 are 10 and 2 respectively). If you
want to specify a number in scientific notation and an arbitrary base,
write the exponent as an explicit power of something, e.g.
\c{base7:1.234}\_\c{*}\_\c{7^13}.

A final way you can specify literal numbers to \spigot is by
specifying them as a hex number interpreted according to IEEE 754. You
do this by writing \c{ieee:} followed by a number of hex digits, which
must be exactly 4, 8, 16 or 32. These lengths correspond to the
following formats:

\b 8 hex digits means IEEE 754 single precision: a 32-bit format
consisting of 1 sign bit, 8 exponent bits, and 23 mantissa bits.

\b 16 hex digits means IEEE 754 double precision: a 64-bit format
consisting of 1 sign bit, 11 exponent bits, and 52 mantissa bits.

\b 32 hex digits means the \q{quad precision} or \q{binary128} format
defined in the 2008 revision of IEEE 754: a 128-bit format consisting
of 1 sign bit, 15 exponent bits, and 112 mantissa bits.

\b 4 hex digits means the \q{half precision} or \q{binary16} format
defined in the 2008 revision of IEEE 754: a terribly cute 16-bit
format consisting of 1 sign bit, 5 exponent bits, and 10 mantissa
bits.

An IEEE hex bit pattern can be followed by a \c{.} and further hex
digits, in which case those digits are treated as an extension to the
mantissa field. For example, \c{ieee:3f800000} represents 1 (in IEEE
single precision); \c{ieee:3f800001} is the next representable number,
namely \cw{1+2^-23}; and \spigot will interpret \c{ieee:3f800000.8} as
the number half way between those two, i.e. \cw{1+2^-24}.

Infinities and NaNs are not permitted as IEEE format input.

\H{constants} Built-in constants

\spigot also supports a few mathematical constants under built-in
names.

\b \c{pi} means \pi, the ratio between a circle's radius and half its
circumference.

\b \c{tau} is a shorthand for \c{2*pi}: the ratio between a circle's
radius and its circumference. (See the
\W{http://www.tauday.com/tau-manifesto}{Tau Manifesto}.)

\b \c{e} means \e{e}, the base of natural logarithms.

\b \c{phi} means the golden ratio, i.e. \cw{(1+sqrt(5))/2}.

\b \c{eulergamma} means the Euler-Mascheroni constant, i.e. the limit
of the difference between \cw{log(}\e{n}\cw{)} and the sum of the
reciprocals of the first \e{n} integers, as \e{n} tends to infinity.

\b \c{apery} means Ap\u00E9{e}ry's constant, i.e. the sum of the
reciprocals of the cubes of the natural numbers.

(All of these numbers can be generated by other methods, such as
\c{4*atan(1)} or \c{exp(1)}, but it's more convenient to have them
available as predefined constants.)

\H{filefd} Numbers read from files and file descriptors

\spigot can read a number from a file in various formats, and use it
as input to its range of mathematical operations and functions (or
just output it directly in a different format).

To read a number from a file in ordinary decimal, write
\c{base10file:} followed by the file name. Any sequence of non-space
characters following the \c{:} will be assumed to be the file name
\dash even if they're punctuation or delimiters, e.g. if you write
\c{sin(base10file:myfile)} then \spigot will interpret the \c{)} as
part of the file name, and (even if a file with that strange name does
exist) will complain that the expression is incomplete.

If you need to read a file that does have a space in its name, there's
a quoting syntax to permit it. If the first character after the \c{:}
is either \c{'} or \c{"}, then \spigot will look for the next
occurrence of the same character, and treat all characters in between
as the file name. A doubled quote character will be treated as a
literal quote. For example:

\b \c{base10file:'my file'} will load the file \cq{my file}.

\b \c{base10file:"my file"} will do the same.

\b \c{base10file:'this isn''t sensible'} will load the file \cq{this
isn't sensible} (the doubled \c{'} turns into a single one and does
not terminate the quoted name).

\b \c{base10file:"this isn't sensible"} is a neater way to specify the
same name (since the \c{'} is not special in a filename quoted with
\c{"}).

If your file contains the number in a base other than 10, you can
prefix its name with \c{base2file:}, \c{base3file:}, \hdots,
\c{base36file:}. Bases larger than 36 are not supported, because after
that the letters of the alphabet run out.

When \spigot reads a file in base notation, it ignores newlines and
white space interspersed between the digits.

You can also prefix a file name with \c{cfracfile:}, in which case
\spigot will expect it to contain a sequence of continued fraction
coefficients (written in decimal). The coefficients can be separated
by any non-digit characters you like (including newlines, like
\spigot's \cw{-c} output mode, or \c{;} and \c{,} like \spigot's
\cw{-c}\_\cw{-l} output mode); a minus sign is permitted before the
very first coefficient to indicate a negative number, but ignored
thereafter.

As mentioned in \k{input}, \spigot will treat numbers read from files
using any of the above keywords as if they are not an exact
representation of a rational number, but a prefix of an infinitely
long expansion of an irrational. So \spigot will compute the output
value as far as the input precision permits, and if it reaches the
point where it can't generate any further output without more input
precision, it will stop, print an error message indicating which input
file ran out first, and return a special exit status 2.

If you really did want the contents of a file to be interpreted as the
\e{exact} terminating expansion of a rational number, you can use the
keywords \c{base10xfile:} (or likewise with bases other than 10) and
\c{cfracxfile}, where the \c{x} stands for \q{exact}. The advantage of
doing this rather than just specifying your expansion on \spigot's
command line directly is performance: if your input file is extremely
large, then \spigot will only have to read enough of it to generate
the amount of output you asked for, whereas if you put the same number
directly on the command line then \spigot would have to parse all of
it before starting.

If \spigot has been compiled with the feature enabled (which it
typically will have been on Unix systems; use \c{spigot --version} to
check), you can also read from a file descriptor in place of a file,
by writing \c{base10fd:}\e{n} (or another base, as above) or
\c{cfracfd:}\e{n}. If you do this, \spigot will expect its own file
descriptor numbered \e{n} to already be open and readable, and will
expect to read a number from there in the appropriate format. For
example, if you write \c{base10fd:0}, then \spigot will expect to read
a number in base 10 from its own standard input (so you might pipe the
output of another program into it). To use other file descriptors, you
could invoke \spigot with a shell redirection operator such as
\c{3<filename} (where \c{filename}, in turn, could point at something
interesting such as a named pipe, not necessarily a regular file), and
then write (say) \c{base10fd:3} to refer to that number.

Numbers read from file descriptors are always treated as exact if the
file descriptor signals EOF. (The expectation is that the whole point
of using a file descriptor is so that you can connect it to a program
that just keeps generating data.)

(If \spigot is told to read from one or more file descriptors which
refer to Unix terminal devices, you can use the \c{-T} option to set
those terminals into raw mode. See \k{miscopts} for more detail.)

\H{let} User-defined variables and functions

Sometimes, it's convenient to define your own variables or functions
in a \spigot expression. For example, suppose you want to evaluate a
polynomial at some particular value. You could write something like
this:

\c $ spigot 'sin(1.1)^3 - 2*sin(1.1)^2 + 5*sin(1.1) - 7'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

but you probably got annoyed at the repetitiveness just \e{reading}
that. So instead you could define a variable to have the repeated
value:

\c $ spigot 'let x=sin(1.1) in x^3 - 2*x^2 + 5*x - 7'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

or alternatively define a function to represent the polynomial:

\c $ spigot 'let f(x) = x^3 - 2*x^2 + 5*x - 7 in f(sin(1.1))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

In this example, it's more or less a matter of taste which of those
you prefer, but the function syntax becomes more useful if you want to
evaluate the function multiple times, e.g.

\c $ spigot 'let f(x) = x^3 - 2*x^2 + 5*x - 7 in f(f(sin(1.1)))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

The full syntax of the \c{let} statement is as follows:

\dd \cw{let}\_\e{definitions}\_\cw{in}\_\e{expression}

where \e{definitions} is a comma-separated list of definitions, each
in one of the following forms:

\dd \e{variable}\_\cw{=}\_\e{expression}

\dd \e{function}\cw{(}\e{parameters}\cw{)}\_\cw{=}\_\e{expression}

In the latter case, \e{parameters} is in turn a comma-separated list
of identifiers, and \e{expression} is allowed to refer to those
identifiers as if they were variables.

Each definition comes into scope as soon as it is complete, but not
before. So a sequence of definitions can refer back to each other:

\c $ spigot 'let x=pi/2, y=x^3, z=exp(y) in sin(z)'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
\c $ spigot 'let f(x)=x+1, g(x)=sin(f(x)) in g(3)'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

but a definition cannot refer to \e{itself} \dash in particular,
functions cannot be defined recursively. (This is a fundamental
limitation of \spigot's evaluation system.)

\C{options} Full list of \spigot's command line options

\H{outputopts} Output format options

\spigot supports the following options to control the format in which
numbers are output:

\b \c{-b} and \c{-B}, followed by a number between 2 and 36 inclusive,
tell \spigot to output in that number base. (Bases above 36 are not
supported because the alphabet runs out.) In bases above 10, the Latin
alphabet is used for extra digits, in lower case if \c{-b} was used or
upper case if \c{-B} was used. The default is \c{-b 10}.

\b In the above modes, \c{-w}, followed by a positive number, tells
\spigot to output at least that many digits of the number's integer
part, by writing leading zeroes if necessary.

\b \c{-c} tells \spigot to output the number as a list of continued
fraction convergents, separated by newlines.

\b \c{-l} is only effective in \c{-c} mode, and tells \spigot to
output the continued fraction convergents all on one long line,
separated by \c{,}, except that the initial integer part is separated
from the rest by \c{;}.

\b \c{-C} tells \spigot to output the continued fraction convergents
of the number. The convergents are separated by newlines, and each one
is in the form of two decimal integers with a \c{/} between them.

\b \c{-S}, \c{-D}, \c{-Q} and \c{-H} tell \spigot to output the number
in the form of its IEEE 754 bit pattern, translated into hex. The four
options specify single, double, quad and half precision respectively;
see \k{literals} for more information on those formats. If the number
is not exactly representable in the specified format, then the
normal-length IEEE bit pattern will be followed by a \c{.} and further
hex digits extending the mantissa field. If the number is too small,
it will underflow to denormals or to zero; if it is too big, \spigot
will output the IEEE bit pattern of the appropriate sign of infinity.

\b In any of the above modes, \c{-d} followed by a number tells
\spigot to limit the number of digits or continued fraction terms it
outputs. In the ordinary base output modes, the number counts digits
after the integer part (i.e. decimal places); in continued fraction
mode, it counts coefficients or convergents not including the initial
one (which is conceptually the integer part, again); in IEEE mode, it
counts extra \e{bits} of mantissa generated after the \cq{.}. \c{-d}
is only an upper limit: if the number is exactly representable with
fewer digits than specified, then \spigot will not output extra
trailing zeroes. The argument to \c{-d} can be negative, in which case
(in base or IEEE mode) rounding will occur at the specified distance
\e{before} the point.

\b \c{-R} tells \spigot to output the number's value as a rational. If
the number is not rational, \spigot will compute for ever without
working that out, because some numbers it handles do turn out to be
rational after some computation.

\b \c{--printf}, followed by a C-style \cw{printf} format string, tells
\spigot to format the number in the way the C \cw{printf} function
would. The format string must consist of a single floating-point
formatting directive (i.e. it must begin with \c{%} and end with the
subsequent \c{e}, \c{f}, \c{g} or \c{a} conversion specifier). Most
\cw{printf} formatting modes also limit the number of digits, except
for \c{%a} with no precision specification, which will continue to
output digits until the number has been exactly represented \dash and
if that is never (i.e. if the number does not have a terminating
representation in binary) then \spigot will continue to print mantissa
digits for ever and never print the trailing exponent.

\b In \c{--printf} mode with the \c{a} or \c{A} conversion specifier,
\c{--nibble} adjusts the choice of exponent. \spigot's default
behaviour in hex \cw{printf} mode is to choose the largest possible
exponent, so that the leading hex digit of the output is always 1
(unless the number is exactly zero). \c{--nibble} changes the
behaviour so that the exponent is always a multiple of 4, so that any
leading digit is possible, and so that the hex digits always align to
the digits that would be output in ordinary \c{-b16} mode.

\H{rmodeopts} Rounding mode options

When \spigot is given a digit limit via \c{-d}, and is not in
continued fraction output mode, it defaults to printing only digits
from the real expansion of the number, i.e. it always truncates toward
zero and never rounds up.

You can make \spigot round the output at the last digit position in
various modes, using one of the following options:

\b \c{--rz} tells \spigot to always round towards zero. This is the default.

\b \c{--ri} tells \spigot to always round away from zero, i.e. the
final digit is always incremented (unless the number was exact).

\b \c{--ru} tells \spigot to always round \e{up}, i.e. towards
positive infinity. This behaves like \c{--rz} for negative numbers,
and like \c{--ri} for positive numbers.

\b \c{--rd} tells \spigot to always round down, i.e. towards
negative infinity. This behaves like \c{--ri} for negative numbers,
and like \c{--rz} for positive numbers.

\b \c{--rn} tells \spigot to round to nearest, i.e. the final digit
will be incremented or not depending on which of the output numbers is
closer in value to the true mathematical result. If there is an exact
tie (the output is exactly half way between two representable numbers,
e.g. asking for 0.25 to one decimal place) then \spigot will break the
tie by choosing whichever of the two outputs is an even multiple of
the place-value of the final digit. Another name for this option is
\c{--rne} (for \q{round to \s{n}earest, tie-breaking to \s{e}ven}).

\lcont{

(In an even base, this rounding rule is the same as the IEEE 754
round-to-nearest rule, which specifies breaking ties by choosing the
output in which the \e{final digit itself} is even. In an odd base,
the IEEE rule as written doesn't quite make sense, because in the case
where rounding up causes a carry, \e{both} of the candidate values
have an even final digit. But if you reinterpret the IEEE wording as
meaning an even \e{multiple of the final digit's place value}, which
is equivalent in an even base, then that version of the rule does
generalise to odd bases and give an unambiguous answer in all cases.)

}

\b \c{--rno} tells \spigot to round to nearest, but this time,
tie-break to an odd multiple of the place value of the final digit.

\b \c{--rnz}, \c{--rni}, \c{--rnu} and \c{--rnd} tell \spigot to round
to nearest, and break ties by rounding them according to the
corresponding directed-rounding option: \c{--rz}, \c{--ri}, \c{--ru},
or \c{--rd} respectively.

If \spigot is told to print a limited number of digits via
\c{--printf} rather than \c{-d}, then it defaults to rounding to
nearest and tiebreaking to even (i.e. equivalent to \c{--rn}), because
that's the default behaviour of the C \cw{printf} function which
\spigot is imitating. This is done by making the \cw{--printf} option
behave as if \c{--rn} had been specified alongside it. So if you want
to use a different rounding mode in \cw{printf}-format output, you
will need to specify the rounding-mode option \e{second}, or else the
implicit one in the \cw{--printf} will override it. For example,
\cw{--printf}\_\cw{--ru} will work, but \cw{--ru}\_\cw{--printf} will
revert to the \cw{--rn} implied by the \cw{--printf} option.

\H{miscopts} Miscellaneous options

Here are some options which didn't fit nicely into the above
categories.

\b \c{-T} tells \spigot to set Unix terminal devices into raw mode, if
it is told to read from any by the \cw{base}\e{N}\cw{fd:} or
\cw{cfracfd:} literal syntaxes (see \k{filefd}). Specifically, \q{raw
mode} means clearing the \cw{ICANON} and \cw{ECHO} bits. For example,
you could run \cq{spigot -T -b2 base10fd:0}, and then type a decimal
number at the keyboard, and \spigot will output the same number in
binary, printing each bit as soon as it has enough information to know
it; the use of \c{-T} means that your keystrokes are received
instantly (without waiting for Return), and are not echoed to the
screen to confuse the output.

\b \c{-n} tells \spigot not to print a trailing newline, in base
output mode (\c{-b} or \c{-B}), \c{--printf} mode, or one-line
continued fraction mode (\c{-c}\_\c{-l}). Normally, if the output
terminates, \spigot will print a newline character before exiting.

\b \c{--tentative=off}, \c{--tentative=on} and \c{--tentative=auto}
control the printing of \q{tentative output}. Tentative output
consists of digits that \spigot is not completely certain of yet, but
is displaying temporarily in case it never manages to compute
something better. The default is \cq{auto}, meaning that tentative
output is printed only when \spigot's standard output points to a
terminal device. For more detail, see \k{hazards}.

\b \c{--version} tells \spigot to report its version number, and also
any other build options, such as whether file descriptor input is
supported, and which library is being used to provide the big-integer
computation that \spigot depends on.

\b \c{--help} displays an abbreviated list of \spigot's command line
options.

\b \c{--licence} displays \spigot's copyright notice and licence text.

\C{hazards} Hazards to computation

So far, this manual has more or less portrayed \spigot as a magic
device that can compute anything it likes. Perhaps some expressions
are evaluated more slowly than others, but it'll get there in the end.

Well \hdots not quite, sorry.

\spigot's core algorithm works by finding an interval of rationals
bracketing the target number, and gradually narrowing that interval
further and further as more information is received or computed. Its
various output modes work by waiting until the interval has narrowed
to the point that the next digit is uniquely determined, and then
writing that digit out.

The problem is: suppose that in order to work out the right output
value, \spigot has to decide whether a number falls on one side or the
other of some boundary value. (This can happen in several different
kinds of situation, which I categorise below.) It will do this by
narrowing its interval until the boundary value doesn't fall inside it
any more, and then it knows which side the number is on.

So the closer to the boundary the number is, the longer \spigot will
take before its interval narrows enough to work out which side it's
on. And here's the problem: if the number it's trying to compute is
\e{exactly} on the boundary value, then \spigot may very well \e{not
ever notice} \dash it will just keep narrowing its interval further
and further, and the boundary value will still be inside the interval
no matter how much it does that, so it will never manage to make a
decision.

It's not standard terminology in exact real computation, but I've
tended to call this sort of problem an \q{exactness hazard}. The
general rule of thumb is that \spigot is good at generating
\e{difficult} output \dash complicated and fiddly irrational numbers
\dash but can get confused if the answer to any computation is too
\e{easy}, in particular if it's zero, or an integer, or has a finite
number of digits in the output representation. So if you're computing
any kind of long and fiddly expression, you need to watch out for
too-simple exact numbers cropping up anywhere in it, because if you're
unlucky, they can cause problems that prevent the expression as a
whole from being computed.

In the following subsections, I list some possible effects of this
kind of problem, and go into more detail about what numbers can
trigger it.

\H{hazards-output} Exactness hazards on output

One obvious situation in which \spigot has to determine which side of
a boundary a number falls is during final output, if the entire result
of the computation has a terminating representation in the output base
or number system. For example, suppose you run this command:

\c $ spigot 'sin(asin(0.12345))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbb

Obviously, \e{we} can see that the true answer is \cw{0.12345}
exactly. But \spigot, with no symbolic algebra system, can't see that.
So what can it do? It will manage to print \cq{0.1234} easily enough,
but then its interval of possible output values will narrow for ever
without allowing it to be certain of the next digit \dash no matter
how much the interval narrows, it will still have one end looking like
\q{\cw{0.123449999}\hdots} and the other like
\q{\cw{0.123450000}\hdots}, and any further work will just add more 9s
to the former and more 0s to the latter, so there will never be a
point at which it can be sure of that fifth digit.

\spigot mitigates this situation by means of its \e{tentative output}
feature. (See \k{miscopts} for options to control this.) What will
actually happen if you run the above command, at least on a default
Unix terminal, is that \spigot will print \cq{0.1234} in the normal
way, then follow that by printing the next digit \cq{5} \e{in red}.
The red text indicates that the output is tentative, i.e. it might be
retracted if more information comes along. So you might see a display
along these lines:

\# The italic text in the below code snippet will be turned into red
text by some disgusting ad-hoc Perl in Makefile.am. In fact so will
\e{any} italic text matching a pattern that looks like a tentative
output suffix (specifically, a space, an open paren, some digits, then
^).

\c $ spigot 'sin(asin(0.12345))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbb
\c 0.12345 (10^-205)
\e       iiiiiiiiiii

This should be read as \spigot saying: \q{The number definitely starts
with \cw{0.1234}, and it \e{looks} as if it's exactly \cw{0.12345},
but I've only looked as far as 205 digits beyond that point, so there
might still be surprises as I go further.} As \spigot computes more
and more digits without finding a divergence from \cw{0.12345}, the
power of 10 in the suffix will keep growing. And the red tentative
text can be retracted if further information is discovered: if you had
instead asked \spigot to compute a number that was not exactly equal
to \cw{0.12345} but merely very very close to it, then \e{eventually}
\spigot would find that out, delete the red text, and print normal
text in its place once it knew what it should be.

So if you see this kind of tentative output from \spigot, that's your
cue to have a closer look at the expression you asked it to compute,
and see if you can see some mathematical reason why the answer is
\e{exactly} what \spigot is suggesting it might be. In this example
case above, of course, that reason is pretty obvious \dash that's what
\c{asin} \e{means}.

One exceptional case in which this kind of thing \e{will} work is that
\spigot makes a special case for numbers it knows from first
principles to be rational. So while the above expression with answer
\cw{0.12345} ran into trouble, the following much simpler thing does
work sensibly, and just prints the right answer immediately:

\c $ spigot 12345/100000
\e   bbbbbbbbbbbbbbbbbbb
\c 0.12345

because this time, \spigot can remember that the number being output
is the same as the known-rational number it got as input, so it
\e{can} spot that it's an exact digit boundary and output it
correctly.

(The special case for rationals is the only reason why \k{rmodeopts}
needs to have all those different options for methods of tie-breaking
in round-to-nearest mode \dash if no terminating representation could
ever be successfully generated, then no tie-breaking options would be
required, because \spigot could never recognise a tie anyway.)

\H{hazards-intermediate} Exactness hazards in subexpressions

A more difficult case arises when \spigot has the same problem of
locating a number on one side or another of a boundary value, but in
an \e{intermediate} result in a complex expression. For example,
suppose you run one of these commands:

\c $ spigot 'tan(pi/2)'
\e   bbbbbbbbbbbbbbbbbb
\c $ spigot 'floor(sin(pi))'
\e   bbbbbbbbbbbbbbbbbbbbbbb

In each of these situations, \spigot will hang completely, and never
manage to print any output at all. This is because, in each case, the
value of a subexpression (respectively \cw{pi/2} and \cw{sin(pi)}) is
exactly on a point of discontinuity of the function it's being fed to
next. In order to even \e{start} outputting the value of \cw{tan(x)},
\spigot first needs to know whether it's positive or negative \dash
and it can't find that out until it knows whether \cw{x} is on one
side or the other of \pi\cw{/2}, which in this case it will never
manage to decide. Similarly with \cw{floor(sin(pi))}: to compute
\cw{floor(x)}, \spigot needs to know whether \cw{x}\_\cw{<}\_\cw{0} or
\cw{x}\_\cw{>=}\_\cw{0}, and again, it can't work that out in the case
where \cw{x} is \e{exactly} 0.

In this kind of situation, there really is nothing \spigot can do but
hang; even tentative output can't mitigate the situation.

As in the previous section, if the number is \e{obviously} a rational,
then \spigot can do better. If you actually ask it for \cw{floor(0)},
then it will handle that fine. But in the example above, the input to
\cq{floor} is \e{non-obviously} zero, in the sense that in order to
know it \spigot would have to actually \e{think about maths} rather
than just computing.

Therefore, if this happens to you, you can sometimes debug it by
pulling out subexpressions and trying to evaluate them on their own;
when you find one with a simple rational answer (probably signalled in
turn by some red tentative output), see if you can prove that to be
exactly the number you wanted, and substitute it in. For example:

\c $ spigot 'floor(sin(pi))'
\e   bbbbbbbbbbbbbbbbbbbbbbb
\c (spigot hangs)
\e iiiiiiiiiiiiii
\c $ spigot 'sin(pi)'
\e   bbbbbbbbbbbbbbbb
\c 0 (10^-951)
\e iiiiiiiiiii
\c $ spigot 'floor(0)'
\e   bbbbbbbbbbbbbbbbb
\c 0

Here, the user observes \spigot hanging, and suspects an exactness
hazard somewhere in their expression. The only interesting
subexpression is \cw{sin(pi)}, so the user evaluates that on its own,
and gets back tentative output suggesting that the answer is exactly
zero. The user thinks about it, realises that of course the answer
\e{is} exactly zero, and simplifies the original expression by
substituting a literal zero in place of the needlessly complicated
\cw{sin(pi)}.

(Of course, in this simple example case, once the user had spotted the
exact zero it hardly needed to ask \spigot for floor of it! But if
something more complicated were being done after the difficult point,
it might well be easiest to substitute in the simple answer and try
again with \spigot.)

However, this debugging technique can only work in cases where the
troublesome intermediate result is \e{rational}, because it's only
rationals for which \spigot has a special-case handler. There would be
no equivalent way to debug the \cw{tan(pi/2)} example above \dash
\spigot actually \e{cannot} recognise an input value to \cq{tan} as
being an odd multiple of \cw{pi/2}.

(This is the reason, mentioned in \k{functions}, why the \c{tan}
function can never return an error, even if you try to pass it an
invalid input value. Because \e{all} the values where \c{tan} has no
finite answer are irrational, so \spigot will always run into this
exactness hazard which prevents it attempting to compute an infinity.)

\H{hazards-internal} Internal exactness hazards

A third place where this same problem can occur, potentially, is
internal to \spigot itself. \spigot's internal implementation of its
various functions will often need to locate the input value on one or
other side of some boundary value, and if \spigot does that without
sufficient caution, then it might hang forever when passed exactly the
boundary value.

\# When there are known exactness hazards, uncomment the commented
pieces of text below :-) Also it would probably be friendly to replace
this historical example with whatever one we find out actually still
goes wrong.

This \e{should} never happen. Exactness hazards internal to \spigot
itself are \e{bugs}. I've found and fixed \#{nearly} all the ones I
know of, but \#{unfortunately not quite all. The currently known
remaining ones are listed below so you know to avoid them; also,} in
case any more turn up, this section demonstrates how to recognise one,
so that you can report it as a bug.

Here's an example of an exactness hazard that \e{used} to exist.
\spigot computes the power function \cw{a^b} by computing
\cw{exp(b*log(a))}, in most cases. But if \cw{a}\_\cw{<}\_\cw{0}, then
the right answer will have \e{magnitude} \cw{exp(b*log(abs(a)))}, but
could be positive, negative or undefined depending on what kind of
number \cw{b} is. So the implementation of \cw{pow}, having first
ruled out a variety of special cases that don't require taking logs at
all, would test the sign of \cw{a}, and run straight into a hazard if
\cw{a} was non-obviously zero. For example, this could happen:

\c $ spigot '0^pi'
\e   bbbbbbbbbbbbb
\c 0
\c $ spigot 'sin(pi)'
\e   bbbbbbbbbbbbbbbb
\c 0 (10^-951)
\e iiiiiiiiiii
\c $ spigot 'sin(pi)^pi'
\e   bbbbbbbbbbbbbbbbbbb
\c (spigot used to just hang)
\e iiiiiiiiiiiiiiiiiiiiiiiiii

If spigot \e{knew} that \cw{a} was zero, then it could easily decide
that zero to any power is zero. And it's at least capable of realising
that \cw{sin(pi)} is \e{arbitrarily close} to zero \dash but it wasn't
able to produce even tentative output for \cw{sin(pi)^pi}, because
that internal sign test of \cw{a} hung forever trying to decide which
side of zero \cw{sin(pi)} fell on.

Now the bug is fixed, and the last of those commands produces
perfectly good tentative output:

\c $ spigot 'sin(pi)^pi'
\e   bbbbbbbbbbbbbbbbbbb
\c 0 (10^-807)
\e iiiiiiiiiii

So if you suspect you're in a situation like this, where some spigot
computation hangs (without even tentative output) for no reason you
can see, try this diagnostic procedure:

\b Narrow down to the smallest subexpression that exhibits the hang.

\b Whatever function \cw{f()} is the outermost one in that
subexpression, check that \spigot can evaluate each argument to \cw{f}
at least as far as producing tentative output. (\cw{f} might be a
literal \e{function}, written with brackets, such as \cw{sin(x)} or
\cw{atan2(y,x)}, or it might be a mathematical operator such as
addition or negation; the same procedure applies no matter how \cw{f}
is written.)

\b Think about whether the mathematical function represented by \cw{f}
is continuous at the point in question. If not, then this is an
unavoidable hang as described in \k{hazards-intermediate}, not an
internal exactness hazard.

\b If you think that \cw{f} is continuous at the specified point, and
that \spigot is producing at least tentative output for all the inputs
to \cw{f}, then please report it as a bug, including the exact \spigot
commands you ran to demonstrate the failing subexpression and the
successful evaluation of the outermost function's arguments.

For example, you might have reported the above example as follows:

\quote{

The following \spigot command hangs without even tentative output:

\c $ spigot 'sin(pi)^pi'
\e   bbbbbbbbbbbbbbbbbbb

I think this is an internal exactness hazard, because \spigot can
evaluate the two operands to the power function safely (the former
produces tentative output and the latter produces definite output):

\c $ spigot 'sin(pi)'
\e   bbbbbbbbbbbbbbbb
\c $ spigot 'pi'
\e   bbbbbbbbbbb

And the power function is mathematically continuous at the point
\cw{(0,}\pi\cw{)}, so I think \spigot should not hang in this case.

}

That example report contains everything needed to check the facts,
reproduce the failure, and decide whether it is indeed a bug.

\H{hazards-design} Design limitations

One last class of hang in \spigot is due not to a bug in the
implementation, but a lack of generality in the fundamental design,
which couldn't really be fixed without writing a totally different
program from scratch.

As mentioned above, \spigot works by narrowing an interval of
rationals bracketing the number. But sometimes you know that the
number is somewhere within one of \e{two} intervals of rationals, and
can keep narrowing both of those intervals without ever working out
which one contains the number. And sometimes, depending on what you
want to do with the number next, that ought in principle to be good
enough.

For example, it's possible to imagine a system that could cope with
this:

\c $ spigot 'abs(atan2(sin(pi),-1))'
\e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

because the more you compute the input values to \cw{atan2}, the
closer you know the output is to \e{one of} \cw{+}\pi and \cw{-}\pi,
even though you still don't know which \dash and since both of those
values come out the same once they've been through the subsequent
\cw{abs} function, you could imagine the system being clever enough to
cope with the expression as a whole. But \spigot's design
fundamentally is not.

\C{output} Output and return values of \spigot

Whatever output format you have chosen (see \k{outputopts}), \spigot
will write data in the specified format to its standard output
channel, i.e. Unix file descriptor 1.

If \spigot successfully generates all the precision you asked for, it
will print a terminating newline (if the output is any of the one-line
types and you did not specify \c{-n}; see \k{miscopts}), and then it
will terminate with exit status 0 (the usual signal for success).

If \spigot cannot generate enough output precision because it was
reading a number from an input file and that input file ran out, it
will still print its terminating newline (subject to the same
conditions as above) on standard output; it will also write an error
message to its standard error channel (Unix file descriptor 2)
indicating which input file ran out first (in case there was more than
one), and terminate with exit status 2.

If \spigot encounters any other failure to evaluate the expression, it
will print an error message to its standard error, and terminate with
exit status 1.

\A{refs} References

\spigot's central algorithm is derived from the paper \q{An unbounded
spigot algorithm for the digits of \pi}, by Jeremy Gibbons. (American
Mathematical Monthly, 113(4):318-328, 2006.) At the time of writing
this, Jeremy Gibbons's web site has a
\W{http://www.cs.ox.ac.uk/people/jeremy.gibbons/publications/spigot.pdf}{PDF
copy of the paper} available.

Gibbons's algorithm is readily adapted to produce a continued fraction
representation as output in place of base notation, and to accept
numbers other than \pi as input. It forms the core of everything
\spigot does, and hence it seemed appropriate to name the entire
program after it.

(Perhaps ironically, one part of Gibbons's algorithm that \spigot does
\e{not} use any more is his representation of \pi! It turned out that
once \spigot had grown the ability to compute arctangents and do
arithmetic, a representation based on Machin's formula was much
faster.)

My algorithm for basic arithmetic is a sort of hybrid of Gibbons's
spigot algorithm and William Gosper's algorithm for doing basic
arithmetic on continued fractions (which I formerly used unmodified,
but had to change it because using a continued fraction representation
introduces exactness hazards). Gosper's algorithm comes originally
from \q{HAKMEM}: Memo 239, Artificial Intelligence Laboratory,
Massachusetts Institute of Technology, Cambridge, Mass., 1972. HAKMEM
can also be \W{http://hdl.handle.net/1721.1/6086}{downloaded} at the
time of writing this. Also, I haven't checked with great care, but the
algorithm I constructed by combining both ideas may very well be the
same as the one used by Imperial College's exact real arithmetic
system (see the link below), in which case, they definitely had the
same idea before I did.

Other algorithms used in this program came from my own head (though
I'm not aware that any of them came from my head \e{first}).

\spigot is not the only exact real calculator around, and was not
really written with the aim of filling any particular gap in the
available software. (I mostly wrote it for the fun of playing with
Gibbons's elegant algorithm, and only realised some time later that it
had become useful enough to be worth publishing.) Hence, if \spigot is
of interest to you, other implementations might also be of interest.
Here are some that I managed to find:

\b Keith Briggs's \W{http://keithbriggs.info/xr.1.html}{xr}: a library
callable from C programs.

\b The \W{http://www.doc.ic.ac.uk/exact-computation/}{Imperial College
Exact Real Arithmetic Library}, also callable from C.

\b David Plume's \W{http://www.cs.bham.ac.uk/~mhe/research.html}{exact
real calculator}, written in Haskell.

\b Hans Boehm's
\W{http://www.hboehm.info/new_crcalc/CRCalc.html}{Constructive Reals
Calculator}, presented as a Java applet.

\A{licence} Copyright statement and licence

spigot is copyright 2007-2014 Simon Tatham. All rights reserved.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
