.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.TH "spigot" "1" "2014\(hy12\(hy17" "Simon\ Tatham" "Simon\ Tatham"
.SH "NAME"
.PP
\fBspigot\fP - command-line exact real calculator
.SH "SYNOPSIS"
.PP
.nf
\fBspigot\fP\ [\ \fIoptions\fP\ ]\ \fIexpression\fP
.fi
.SH "DESCRIPTION"
.PP
\fBspigot\fP 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.
.PP
\fBspigot\fP 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.
.PP
This man page gives only a brief summary of \fBspigot\fP\*(Aqs functionality. For full detail, you should read the main manual \fBspigot.html\fP; if that is not installed on your system, you can find it on the web at
.PP
\fBhttp://www.chiark.greenend.org.uk/~sgtatham/spigot/spigot.html\fP
.SH "OPTIONS"
.PP
The following options control \fBspigot\fP\*(Aqs basic output format:
.IP "\fB-b\fP \fIbase\fP, \fB-B\fP \fIbase\fP"
Output the number in base \fIbase\fP, 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 \fB-b\fP and \fB-B\fP respectively. The default is \fB-b\fP\ \fB10\fP.
.IP "\fB-c\fP"
Output the number as a list of continued fraction coefficients, as decimal integers, by default one per line.
.IP "\fB-C\fP"
Output the number's continued fraction convergents, one per line, in the form of two decimal integers with a \fB/\fP between them.
.IP "\fB-R\fP"
Output the number's value as a rational, in the form of two decimal integers with a \fB/\fP between them, or just one decimal integer if the number is a rational. If \fBspigot\fP 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 \fBspigot\fP will compute for ever.
.IP "\fB-S\fP, \fB-D\fP, \fB-Q\fP, \fB-H\fP"
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.
.IP "\fB--printf\fP \fIformat\fP, \fB--printf=\fP\fIformat\fP"
Format the number in the same way that \fBprintf\fP(\fI3\fP) would, given the formatting directive \fIformat\fP. \fIformat\fP must begin with a \fB%\fP and end with the associated conversion specifier, which must be a floating-point one (one of \fBefgaEFGA\fP).
.PP
The following options modify the details of those output formats:
.IP "\fB-d\fP \fIlimit\fP"
Limit the amount of data output. In \fB-b\fP mode, no more than \fIlimit\fP digits after the decimal point are printed. In \fB-c\fP or \fB-C\fP mode, no more than \fIlimit\fP continued fraction coefficients or convergents are printed, not counting the initial one representing the number\*(Aqs integer part. In the IEEE 754 output modes, no more than \fIlimit\fP additional bits of precision are generated after the end of the official mantissa. \fIlimit\fP may be negative.
.IP "\fB-l\fP"
In \fB-c\fP mode, output continued fraction terms all on one line, separated by a \fB;\fP after the first term and \fB,\fP after each subsequent term.
.IP "\fB-w\fP \fImin-int-digits\fP"
In \fB-b\fP mode, output at least \fImin-int-digits\fP of the number\*(Aqs integer part, by printing leading zeroes if necessary.
.IP "\fB--nibble\fP"
In \fB--printf\fP mode with the `\fBa\fP' or `\fBA\fP' 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.
.IP "\fB-n\fP"
In any mode where \fBspigot\fP prints output on a single line, suppress the usual trailing newline if \fBspigot\fP\*(Aqs output terminates.
.PP
The following options control rounding, when \fBspigot\fP\*(Aqs output is limited by the \fB-d\fP option. (Rounding does not occur in continued fraction modes.)
.IP "\fB--rz\fP"
Round towards zero. This is the default.
.IP "\fB--ri\fP"
Round away from zero.
.IP "\fB--ru\fP"
Round up (towards positive infinity).
.IP "\fB--rd\fP"
Round down (towards negative infinity).
.IP "\fB--rn\fP, \fB--rne\fP"
Round to nearest, breaking ties toward an even last digit.
.IP "\fB--rno\fP"
Round to nearest, breaking ties toward an odd last digit.
.IP "\fB--rnz\fP, \fB--rni\fP, \fB--rnu\fP, \fB--rnd\fP"
Round to nearest, breaking ties as if rounding via \fB--rz\fP, \fB--ri\fP, \fB--ru\fP or \fB--rd\fP respectively.
.PP
Miscellaneous options:
.IP "\fB--tentative=\fP\fIstate\fP"
Control the printing of `tentative output'. Tentative output is printed when \fBspigot\fP does not know for sure what the next digit of the number is because it\*(Aqs starting to look as if it\*(Aqs exactly on a digit boundary. Tentative output is in red, and followed by an indication of about how many digits \fBspigot\fP has examined beyond that point (i.e. how close to exact that digit is known to be); \fBspigot\fP will retract it later if it finds out something definite.
.RS
.PP
\fIstate\fP can be `\fBon\fP', `\fBoff\fP' or `\fBauto\fP'. `\fBauto\fP' is the default, and means that \fBspigot\fP should only print tentative output if its output is directed to a terminal device.
.RE
.IP "\fB-T\fP"
If instructed to read from a file descriptor which points to a terminal, put the terminal into raw mode (turning off \fBICANON\fP and \fBECHO\fP modes) while doing so.
.SH "EXPRESSIONS"
.PP
\fBspigot\fP\*(Aqs expression language supports the following options, in order of priority from lowest to highest:
.IP "\fB+\fP and \fB-\fP"
Addition and subtraction. (Left-associative.)
.IP "\fB*\fP, \fB/\fP, \fB%\fP, \fBmod\fP, \fBrem\fP"
Multiplication, division and remainder. (Left-associative.) \fB%\fP and \fBmod\fP are synonyms, which both return a remainder between 0 and the denominator; \fBrem\fP 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.
.IP "Unary \fB-\fP and \fB+\fP"
Negation and no-op.
.IP "\fB^\fP, \fB**\fP"
Power. (Right-associative.)
.PP
You can define variables and functions of your own in subexpressions using the \fBlet\fP expression, as follows:
.IP "\fBlet\fP\ \fIvar\fP\fB=\fP\fIvalue\fP\ \fBin\fP\ \fIexpression\fP"
Defines the name \fIvar\fP to refer to the value of the expression \fIvalue\fP. The definition is in scope within \fIexpression\fP, but not in any other parts of the \fBspigot\fP input.
.IP "\fBlet\fP\ \fIfn\fP\fB(\fP\fIparams\fP\fB)=\fP\fIdefn\fP\ \fBin\fP\ \fIexpression\fP"
Defines the syntax \fIfn\fP\fB(\fP\fIargs\fP\fB)\fP to refer to the expression \fIdefn\fP with the arguments substituted in for the parameters. \fIparams\fP must be a comma-separated list of identifiers; \fIargs\fP is a comma-separated list of expressions.
.PP
A \fBlet\fP expression can contain multiple definitions, separated by commas, e.g. `\fBlet x=1,y=2 in x+y\fP'. Each definition is in scope for subsequent definitions, so you can write `\fBlet x=1,y=x+1 in\fP'\ \fIexpr\fP. But definitions are not in scope for \fIthemselves\fP; in particular, functions may not be recursive.
.PP
\fBspigot\fP also provides the following built-in functions:
.IP "\fBsqrt\fP, \fBcbrt\fP"
Square and cube roots.
.IP "\fBhypot\fP, \fBatan2\fP (two arguments)"
Rectangular to polar coordinate conversions: the hypotenuse function (square root of the sum of the squared arguments), and two-variable inverse tangent.
.IP "\fBsin\fP, \fBcos\fP, \fBtan\fP, \fBasin\fP, \fBacos\fP, \fBatan\fP"
Trigonometric functions and their inverses.
.IP "\fBsind\fP, \fBcosd\fP, \fBtand\fP, \fBasind\fP, \fBacosd\fP, \fBatand\fP, \fBatan2d\fP"
Trigonometric functions and their inverses, equivalent to the versions without `\fBd\fP' on the end except that angles are measured in degrees.
.IP "\fBsinh\fP, \fBcosh\fP, \fBtanh\fP, \fBasinh\fP, \fBacosh\fP, \fBatanh\fP"
Hyperbolic functions and their inverses.
.IP "\fBexp\fP, \fBexp2\fP, \fBexp10\fP, \fBlog\fP, \fBlog2\fP, \fBlog10\fP"
Exponential and logarithmic functions: raise \fIe\fP, 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 \fBlog\fP.
.IP "\fBexpm1\fP, \fBlog1p\fP"
Shorthands for \fBexp(x)-1\fP and \fBlog(1+x)\fP.
.IP "\fBpow\fP (two arguments)"
Synonym for the \fB^\fP operator.
.IP "\fBgamma\fP, \fBtgamma\fP, \fBlgamma\fP"
Gamma function (\fBgamma\fP and \fBtgamma\fP are synonyms for this), and the log of the absolute value of the gamma function.
.IP "\fBerf\fP, \fBerfc\fP, \fBPhi\fP, \fBnorm\fP"
Error-function relatives: the error function itself, 1 minus the error function, and \fBPhi\fP and \fBnorm\fP are synonyms for the cumulative normal distribution function.
.IP "\fBerfinv\fP, \fBerfcinv\fP, \fBPhiinv\fP, \fBnorminv\fP"
Inverses of the above error-function relatives.
.IP "\fBW\fP, \fBWn\fP"
The Lambert W function, i.e. the inverse of \fBx\fP\ \fBexp(x)\fP. \fBW\fP is the branch with value at least \fB-1\fP, and \fBWn\fP is the branch with value at most \fB-1\fP.
.IP "\fBEi\fP, \fBEn\fP (two arguments), \fBE1\fP, \fBEin\fP"
Exponential integrals, i.e. integrals of things like \fBexp(x)/x\fP. \fBEi(x)\fP is the indefinite integral of \fBexp(x)/x\fP itself; \fBEn(n,x)\fP (for non-negative integer \fBn\fP) is the result of integrating \fBexp(-x)/x\fP \fBn\fP times, flipping the sign each time; \fBE1(x)\fP is shorthand for \fBEn(1,x)\fP; and \fBEin(x)\fP is the integral of \fB(1-exp(-x))/x\fP.
.IP "\fBLi\fP, \fBli\fP"
Logarithmic integrals, i.e. integrals of \fB1/log(x)\fP. \fBLi(x)\fP and \fBli(x)\fP are both the indefinite integral of \fB1/log(x)\fP; only their constants differ, in that \fBLi(2)\fP and \fBli(0)\fP are each defined to be zero.
.IP "\fBSi\fP, \fBsi\fP, \fBCi\fP, \fBCin\fP"
Sine and cosine integrals, i.e. integrals of \fBsin(x)/x\fP and \fBcos(x)/x\fP. \fBSi(x)\fP and \fBsi(x)\fP are both the indefinite integral of \fBsin(x)/x\fP, differing only in the constant: \fBSi(0)=0\fP, but \fBsi(x)\fP has limit 0 as \fBx\fP tends to positive infinity. \fBCi(x)\fP is the indefinite integral of \fBcos(x)/x\fP, also with limit 0 at positive infinity; \fBCin(x)\fP is the indefinite integral of \fB(1-cos(x))/x\fP, with \fBCin(0)=0\fP.
.IP "\fBUFresnelS\fP, \fBUFresnelC\fP, \fBFresnelS\fP, \fBFresnelC\fP"
Fresnel integrals. \fBUFresnelS\fP and \fBUFresnelC\fP are the indefinite integrals of \fBsin(x^2)\fP and \fBcos(x^2)\fP; \fBFresnelS\fP and \fBFresnelC\fP are the `normalised' versions, i.e. integrals of \fBsin(\fP\fI\(*p\fP\ \fBx^2/2)\fP and \fBcos(\fP\fI\(*p\fP\ \fBx^2/2)\fP. All are zero at the origin.
.IP "\fBzeta\fP"
The Riemann zeta function (restricted to the real numbers).
.IP "\fBabs\fP"
Absolute value.
.IP "\fBceil\fP, \fBfloor\fP"
Ceiling and floor: smallest integer at least \fIx\fP, and largest integer at most \fIx\fP.
.IP "\fBfrac\fP"
Fractional part, i.e. \fBx\fP\ \fB-\fP\ \fBfloor(x)\fP.
.IP "\fBalgebraic\fP (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.
.PP
\fBspigot\fP supports the following names for built-in constants:
.IP "\fBpi\fP, \fBtau\fP"
The circle constant \fI\(*p\fP, and the often more useful 2 \fI\(*p\fP.
.IP "\fBe\fP"
The base of natural logarithms.
.IP "\fBphi\fP"
The golden ratio, \fB(1+sqrt(5))/2\fP.
.IP "\fBeulergamma\fP"
The Euler-Mascheroni constant: the limiting difference between the sum and the integral of \fB1/n\fP.
.IP "\fBapery\fP"
Apery's constant: the sum of the reciprocals of the cubes.
.PP
Numbers can be input in the following formats:
.IP "\fB\(bu\fP"
Decimal, with an optional C-style \fBe+\fP\fIexponent\fP or \fBe-\fP\fIexponent\fP for scientific notation
.IP "\fB\(bu\fP"
Hex, with the prefix \fB0x\fP, and an optional C99-style \fBp+\fP\fIexponent\fP or \fBp-\fP\fIexponent\fP representing a power of 2 multiplier
.IP "\fB\(bu\fP"
In any base between 2 and 36, with a prefix of the form \fBbase\fP\fIN\fP\fB:\fP, e.g. \fBbase7:0.123456\fP
.IP "\fB\(bu\fP"
As an IEEE 754 hex bit pattern, consisting of exactly 4, 8, 16 or 32 hex digits with the prefix \fBieee:\fP, followed by optional decimal point and extra mantissa digits
.IP "\fB\(bu\fP"
From a file in base notation, by writing \fBbase\fP\fIN\fP\fBfile:\fP followed by a filename, e.g. \fBbase10fd:pi.txt\fP. The filename is taken to be the maximal sequence of non-space characters following the prefix, unless it starts with \fB\*(Aq\fP or \fB"\fP, 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.
.IP "\fB\(bu\fP"
From a file in continued fraction notation, by writing \fBcfracfile:\fP followed by a filename.
.IP "\fB\(bu\fP"
Either of the above, but with \fBfile:\fP replaced by \fBxfile:\fP to indicate that end of file should be taken as the number being exactly represented rather than running out of precision.
.IP "\fB\(bu\fP"
From a file descriptor in any of those notations, by writing \fBbase\fP\fIN\fP\fBfd:\fP or \fBcfracfd:\fP followed by an fd number, e.g. \fBbase10fd:0\fP to read from standard input.
.SH "RETURN VALUE"
.PP
\fBspigot\fP returns 0 if its output terminates (because the result is exact, or because it reached the specified \fB-d\fP limit) with no problems.
.PP
In case of a parse error, or an invalid operand to a function, or any other kind of fatal error, \fBspigot\fP returns 1.
.PP
If \fBspigot\fP is unable to generate output to the desired precision because more precision was needed from a number read from an input file using \fBbase\fP\fIN\fP\fBfile:\fP or \fBcfracfile:\fP, then \fBspigot\fP returns 2, and prints an error message indicating which input file (in case there was more than one) ran out first.
.SH "LIMITATIONS"
.PP
Due to inherent limitations of its exact real arithmetic strategy, \fBspigot\fP is generally unable to recognise when a number it is computing is exactly equal to a specific boundary value.
.PP
One effect of this is that \fBspigot\fP will not behave as you\*(Aqd like if the output number has a terminating representation in the selected base. For example, asking for \fBsin(asin(0.12345))\fP will not be able to print \fB0.12345\fP and exit. Instead, \fBspigot\fP will get as far as printing `\fB0.1234\fP', and then print tentative output (mentioned above) to indicate that it thinks the next digit \fImight\fP be exactly 5, but it will never reach a point where it\*(Aqs \fIsure\fP of that.
.PP
Another effect is that if you ask \fBspigot\fP 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 \fIstart\fP producing output. For example, \fBspigot\fP will hang completely if you ask it for \fBfloor(sin(pi))\fP, since \fBsin(pi)\fP\ \fB=\fP\ \fB0\fP is a point of discontinuity of the \fBfloor\fP function, and \fBspigot\fP will never be able to work out that the value of the input to \fBfloor\fP is \fIexactly\fP zero, only that it seems to be closer and closer to zero the more it computes.
.PP
(An exception is numbers that \fBspigot\fP knows from first principles to be rational. For example, if you ask \fBspigot\fP to evaluate the simpler expressions `\fB0.12345\fP' or `\fBfloor(0)\fP', it will print the complete output and terminate successfully, in both cases.)
.SH "LICENCE"
.PP
\fBspigot\fP is free software, distributed under the MIT licence. Type `\fBspigot --licence\fP' to see the full licence text.