Provided by: spigot_0.2017-01-15.gdad1bbc6-1build2_amd64 
NAME
spigot - command-line exact real calculator
SYNOPSIS
spigot [ options ] expression
DESCRIPTION
spigot is an exact real calculator: that is, you give it a mathematical expression to evaluate, and it
computes it to any desired precision, by default simply printing digits to standard output until it is
interrupted.
spigot provides command-line options to control the format of the output, restrict it to a specified
number of digits, and apply rounding at the end of those digits. It can produce output in any base
between 2 and 36 (after that it runs out of digit characters), or as a continued fraction, and it can
read input numbers from files in any of those formats as well.
This man page gives only a brief summary of spigot's functionality. For full detail, you should read the
main manual spigot.html; if that is not installed on your system, you can find it on the web at
http://www.chiark.greenend.org.uk/~sgtatham/spigot/spigot.html
OPTIONS
The following options control spigot's basic output format:
-b base, -B base
Output the number in base base, which must be an integer between 2 and 36 inclusive. Digits above
9 are represented by lower case or upper case letters, for the options -b and -B respectively. The
default is -b 10.
-c Output the number as a list of continued fraction coefficients, as decimal integers, by default
one per line.
-C Output the number's continued fraction convergents, one per line, in the form of two decimal
integers with a / between them.
-R Output the number's value as a rational, in the form of two decimal integers with a / between
them, or just one decimal integer if the number is a rational. If spigot does not know the number
to be rational immediately, it will start evaluating it to see if it turns out rational later, so
if it is not rational then spigot will compute for ever.
-S, -D, -Q, -H
Output the number as a hex representation of an IEEE 754 bit pattern, in 32-bit single precision,
64-bit double, 128-bit quad or 16-bit half precision respectively. If that representation is not
exact, a decimal point will be printed followed by further mantissa digits.
--printf format, --printf=format
Format the number in the same way that printf(3) would, given the formatting directive format.
format must begin with a % and end with the associated conversion specifier, which must be a
floating-point one (one of efgaEFGA).
The following options modify the details of those output formats:
-d limit
Limit the amount of data output. In -b mode, no more than limit digits after the decimal point are
printed. In -c or -C mode, no more than limit continued fraction coefficients or convergents are
printed, not counting the initial one representing the number's integer part. In the IEEE 754
output modes, no more than limit additional bits of precision are generated after the end of the
official mantissa. limit may be negative.
-l In -c mode, output continued fraction terms all on one line, separated by a ; after the first term
and , after each subsequent term.
-w min-int-digits
In -b mode, output at least min-int-digits of the number's integer part, by printing leading
zeroes if necessary.
--nibble
In --printf mode with the `a' or `A' conversion specifier, choose the output exponent to always be
a multiple of 4, instead of the default behaviour of choosing it as large as possible.
-n In any mode where spigot prints output on a single line, suppress the usual trailing newline if
spigot's output terminates.
The following options control rounding, when spigot's output is limited by the -d option. (Rounding does
not occur in continued fraction modes.)
--rz Round towards zero. This is the default.
--ri Round away from zero.
--ru Round up (towards positive infinity).
--rd Round down (towards negative infinity).
--rn, --rne
Round to nearest, breaking ties toward an even last digit.
--rno Round to nearest, breaking ties toward an odd last digit.
--rnz, --rni, --rnu, --rnd
Round to nearest, breaking ties as if rounding via --rz, --ri, --ru or --rd respectively.
Miscellaneous options:
--tentative=state
Control the printing of `tentative output'. Tentative output is printed when spigot does not know
for sure what the next digit of the number is because it's starting to look as if it's exactly on
a digit boundary. Tentative output is in red, and followed by an indication of about how many
digits spigot has examined beyond that point (i.e. how close to exact that digit is known to be);
spigot will retract it later if it finds out something definite.
state can be `on', `off' or `auto'. `auto' is the default, and means that spigot should only print
tentative output if its output is directed to a terminal device.
-T If instructed to read from a file descriptor which points to a terminal, put the terminal into raw
mode (turning off ICANON and ECHO modes) while doing so.
EXPRESSIONS
spigot's expression language supports the following options, in order of priority from lowest to highest:
+ and -
Addition and subtraction. (Left-associative.)
*, /, %, mod, rem
Multiplication, division and remainder. (Left-associative.) % and mod are synonyms, which both
return a remainder between 0 and the denominator; rem returns a remainder of either sign, with
absolute value at most half that of the denominator, and ties broken by rounding to even in IEEE
754 style.
Unary - and +
Negation and no-op.
^, ** Power. (Right-associative.)
You can define variables and functions of your own in subexpressions using the let expression, as
follows:
let var=value in expression
Defines the name var to refer to the value of the expression value. The definition is in scope
within expression, but not in any other parts of the spigot input.
let fn(params)=defn in expression
Defines the syntax fn(args) to refer to the expression defn with the arguments substituted in for
the parameters. params must be a comma-separated list of identifiers; args is a comma-separated
list of expressions.
A let expression can contain multiple definitions, separated by commas, e.g. `let x=1,y=2 in x+y'. Each
definition is in scope for subsequent definitions, so you can write `let x=1,y=x+1 in' expr. But
definitions are not in scope for themselves; in particular, functions may not be recursive.
spigot also provides the following built-in functions:
sqrt, cbrt
Square and cube roots.
hypot, atan2 (two arguments)
Rectangular to polar coordinate conversions: the hypotenuse function (square root of the sum of
the squared arguments), and two-variable inverse tangent.
sin, cos, tan, asin, acos, atan
Trigonometric functions and their inverses.
sind, cosd, tand, asind, acosd, atand, atan2d
Trigonometric functions and their inverses, equivalent to the versions without `d' on the end
except that angles are measured in degrees.
sinh, cosh, tanh, asinh, acosh, atanh
Hyperbolic functions and their inverses.
exp, exp2, exp10, log, log2, log10
Exponential and logarithmic functions: raise e, 2 and 10 to a power, or take a log with the same
three bases. You can also provide a base of your choice as a second argument to log.
expm1, log1p
Shorthands for exp(x)-1 and log(1+x).
pow (two arguments)
Synonym for the ^ operator.
gamma, tgamma, lgamma
Gamma function (gamma and tgamma are synonyms for this), and the log of the absolute value of the
gamma function.
erf, erfc, Phi, norm
Error-function relatives: the error function itself, 1 minus the error function, and Phi and norm
are synonyms for the cumulative normal distribution function.
erfinv, erfcinv, Phiinv, norminv
Inverses of the above error-function relatives.
W, Wn The Lambert W function, i.e. the inverse of x exp(x). W is the branch with value at least -1, and
Wn is the branch with value at most -1.
Ei, En (two arguments), E1, Ein
Exponential integrals, i.e. integrals of things like exp(x)/x. Ei(x) is the indefinite integral of
exp(x)/x itself; En(n,x) (for non-negative integer n) is the result of integrating exp(-x)/x n
times, flipping the sign each time; E1(x) is shorthand for En(1,x); and Ein(x) is the integral of
(1-exp(-x))/x.
Li, li Logarithmic integrals, i.e. integrals of 1/log(x). Li(x) and li(x) are both the indefinite
integral of 1/log(x); only their constants differ, in that Li(2) and li(0) are each defined to be
zero.
Si, si, Ci, Cin
Sine and cosine integrals, i.e. integrals of sin(x)/x and cos(x)/x. Si(x) and si(x) are both the
indefinite integral of sin(x)/x, differing only in the constant: Si(0)=0, but si(x) has limit 0 as
x tends to positive infinity. Ci(x) is the indefinite integral of cos(x)/x, also with limit 0 at
positive infinity; Cin(x) is the indefinite integral of (1-cos(x))/x, with Cin(0)=0.
UFresnelS, UFresnelC, FresnelS, FresnelC
Fresnel integrals. UFresnelS and UFresnelC are the indefinite integrals of sin(x^2) and cos(x^2);
FresnelS and FresnelC are the `normalised' versions, i.e. integrals of sin(π x^2/2) and
cos(π x^2/2). All are zero at the origin.
zeta The Riemann zeta function (restricted to the real numbers).
abs Absolute value.
ceil, floor
Ceiling and floor: smallest integer at least x, and largest integer at most x.
frac Fractional part, i.e. x - floor(x).
algebraic (variable number of arguments)
Return a root of an arbitrary polynomial with integer coefficients. The first two arguments are
the rational bounds of an interval to search, and the rest give the polynomial's coefficients,
with constant term first.
spigot supports the following names for built-in constants:
pi, tau
The circle constant π, and the often more useful 2 π.
e The base of natural logarithms.
phi The golden ratio, (1+sqrt(5))/2.
eulergamma
The Euler-Mascheroni constant: the limiting difference between the sum and the integral of 1/n.
apery Apery's constant: the sum of the reciprocals of the cubes.
Numbers can be input in the following formats:
• Decimal, with an optional C-style e+exponent or e-exponent for scientific notation
• Hex, with the prefix 0x, and an optional C99-style p+exponent or p-exponent representing a power
of 2 multiplier
• In any base between 2 and 36, with a prefix of the form baseN:, e.g. base7:0.123456
• As an IEEE 754 hex bit pattern, consisting of exactly 4, 8, 16 or 32 hex digits with the prefix
ieee:, followed by optional decimal point and extra mantissa digits
• From a file in base notation, by writing baseNfile: followed by a filename, e.g. base10fd:pi.txt.
The filename is taken to be the maximal sequence of non-space characters following the prefix,
unless it starts with ' or ", in which case it is taken to be everything up to a matching closing
quote, with doubled quote marks in between representing a literal quote character.
• From a file in continued fraction notation, by writing cfracfile: followed by a filename.
• Either of the above, but with file: replaced by xfile: to indicate that end of file should be
taken as the number being exactly represented rather than running out of precision.
• From a file descriptor in any of those notations, by writing baseNfd: or cfracfd: followed by an
fd number, e.g. base10fd:0 to read from standard input.
RETURN VALUE
spigot returns 0 if its output terminates (because the result is exact, or because it reached the
specified -d limit) with no problems.
In case of a parse error, or an invalid operand to a function, or any other kind of fatal error, spigot
returns 1.
If spigot is unable to generate output to the desired precision because more precision was needed from a
number read from an input file using baseNfile: or cfracfile:, then spigot returns 2, and prints an error
message indicating which input file (in case there was more than one) ran out first.
LIMITATIONS
Due to inherent limitations of its exact real arithmetic strategy, spigot is generally unable to
recognise when a number it is computing is exactly equal to a specific boundary value.
One effect of this is that spigot will not behave as you'd like if the output number has a terminating
representation in the selected base. For example, asking for sin(asin(0.12345)) will not be able to print
0.12345 and exit. Instead, spigot will get as far as printing `0.1234', and then print tentative output
(mentioned above) to indicate that it thinks the next digit might be exactly 5, but it will never reach a
point where it's sure of that.
Another effect is that if you ask spigot to evaluate an expression in which an intermediate result is
precisely on a point of discontinuity of the function it is passed to, then it may never manage to even
start producing output. For example, spigot will hang completely if you ask it for floor(sin(pi)), since
sin(pi) = 0 is a point of discontinuity of the floor function, and spigot will never be able to work out
that the value of the input to floor is exactly zero, only that it seems to be closer and closer to zero
the more it computes.
(An exception is numbers that spigot knows from first principles to be rational. For example, if you ask
spigot to evaluate the simpler expressions `0.12345' or `floor(0)', it will print the complete output and
terminate successfully, in both cases.)
LICENCE
spigot is free software, distributed under the MIT licence. Type `spigot --licence' to see the full
licence text.
Simon Tatham 2014‐12‐17 spigot(1)