Provided by: spigot_0.2017-01-15.gdad1bbc6-1build1_amd64

**NAME**

spigot- command-line exact real calculator

**SYNOPSIS**

spigot[options]expression

**DESCRIPTION**

spigotis 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.spigotprovides 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 ofspigot's functionality. For full detail, you should read the main manualspigot.html; if that is not installed on your system, you can find it on the web athttp://www.chiark.greenend.org.uk/~sgtatham/spigot/spigot.html

**OPTIONS**

The following options controlspigot's basic output format:-bbase,-BbaseOutput the number in basebase, 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-band-Brespectively. The default is-b10.-cOutput the number as a list of continued fraction coefficients, as decimal integers, by default one per line.-COutput the number's continued fraction convergents, one per line, in the form of two decimal integers with a/between them.-ROutput 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. Ifspigotdoes 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 thenspigotwill compute for ever.-S,-D,-Q,-HOutput 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.--printfformat,--printf=formatFormat the number in the same way thatprintf(3) would, given the formatting directiveformat.formatmust begin with a%and end with the associated conversion specifier, which must be a floating-point one (one ofefgaEFGA). The following options modify the details of those output formats:-dlimitLimit the amount of data output. In-bmode, no more thanlimitdigits after the decimal point are printed. In-cor-Cmode, no more thanlimitcontinued 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 thanlimitadditional bits of precision are generated after the end of the official mantissa.limitmay be negative.-lIn-cmode, output continued fraction terms all on one line, separated by a;after the first term and,after each subsequent term.-wmin-int-digitsIn-bmode, output at leastmin-int-digitsof the number's integer part, by printing leading zeroes if necessary.--nibbleIn--printfmode 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.-nIn any mode wherespigotprints output on a single line, suppress the usual trailing newline ifspigot's output terminates. The following options control rounding, whenspigot's output is limited by the-doption. (Rounding does not occur in continued fraction modes.)--rzRound towards zero. This is the default.--riRound away from zero.--ruRound up (towards positive infinity).--rdRound down (towards negative infinity).--rn,--rneRound to nearest, breaking ties toward an even last digit.--rnoRound to nearest, breaking ties toward an odd last digit.--rnz,--rni,--rnu,--rndRound to nearest, breaking ties as if rounding via--rz,--ri,--ruor--rdrespectively. Miscellaneous options:--tentative=stateControl the printing of `tentative output'. Tentative output is printed whenspigotdoes 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 digitsspigothas examined beyond that point (i.e. how close to exact that digit is known to be);spigotwill retract it later if it finds out something definite.statecan be `on', `off' or `auto'. `auto' is the default, and means thatspigotshould only print tentative output if its output is directed to a terminal device.-TIf instructed to read from a file descriptor which points to a terminal, put the terminal into raw mode (turning offICANONandECHOmodes) 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,remMultiplication, division and remainder. (Left-associative.)%andmodare synonyms, which both return a remainder between 0 and the denominator;remreturns 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 theletexpression, as follows:letvar=valueinexpressionDefines the namevarto refer to the value of the expressionvalue. The definition is in scope withinexpression, but not in any other parts of thespigotinput.letfn(params)=defninexpressionDefines the syntaxfn(args)to refer to the expressiondefnwith the arguments substituted in for the parameters.paramsmust be a comma-separated list of identifiers;argsis a comma-separated list of expressions. Aletexpression can contain multiple definitions, separated by commas, e.g. `letx=1,y=2inx+y'. Each definition is in scope for subsequent definitions, so you can write `letx=1,y=x+1in'expr. But definitions are not in scope forthemselves; in particular, functions may not be recursive.spigotalso provides the following built-in functions:sqrt,cbrtSquare 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,atanTrigonometric functions and their inverses.sind,cosd,tand,asind,acosd,atand,atan2dTrigonometric 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,atanhHyperbolic functions and their inverses.exp,exp2,exp10,log,log2,log10Exponential and logarithmic functions: raisee, 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 tolog.expm1,log1pShorthands forexp(x)-1andlog(1+x).pow(two arguments) Synonym for the^operator.gamma,tgamma,lgammaGamma function (gammaandtgammaare synonyms for this), and the log of the absolute value of the gamma function.erf,erfc,Phi,normError-function relatives: the error function itself, 1 minus the error function, andPhiandnormare synonyms for the cumulative normal distribution function.erfinv,erfcinv,Phiinv,norminvInverses of the above error-function relatives.W,WnThe Lambert W function, i.e. the inverse ofxexp(x).Wis the branch with value at least-1, andWnis the branch with value at most-1.Ei,En(two arguments),E1,EinExponential integrals, i.e. integrals of things likeexp(x)/x.Ei(x)is the indefinite integral ofexp(x)/xitself;En(n,x)(for non-negative integern) is the result of integratingexp(-x)/xntimes, flipping the sign each time;E1(x)is shorthand forEn(1,x); andEin(x)is the integral of(1-exp(-x))/x.Li,liLogarithmic integrals, i.e. integrals of1/log(x).Li(x)andli(x)are both the indefinite integral of1/log(x); only their constants differ, in thatLi(2)andli(0)are each defined to be zero.Si,si,Ci,CinSine and cosine integrals, i.e. integrals ofsin(x)/xandcos(x)/x.Si(x)andsi(x)are both the indefinite integral ofsin(x)/x, differing only in the constant:Si(0)=0, butsi(x)has limit 0 asxtends to positive infinity.Ci(x)is the indefinite integral ofcos(x)/x, also with limit 0 at positive infinity;Cin(x)is the indefinite integral of(1-cos(x))/x, withCin(0)=0.UFresnelS,UFresnelC,FresnelS,FresnelCFresnel integrals.UFresnelSandUFresnelCare the indefinite integrals ofsin(x^2)andcos(x^2);FresnelSandFresnelCare the `normalised' versions, i.e. integrals ofsin(πx^2/2)andcos(πx^2/2). All are zero at the origin.zetaThe Riemann zeta function (restricted to the real numbers).absAbsolute value.ceil,floorCeiling and floor: smallest integer at leastx, and largest integer at mostx.fracFractional 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.spigotsupports the following names for built-in constants:pi,tauThe circle constantπ, and the often more useful 2π.eThe base of natural logarithms.phiThe golden ratio,(1+sqrt(5))/2.eulergammaThe Euler-Mascheroni constant: the limiting difference between the sum and the integral of1/n.aperyApery's constant: the sum of the reciprocals of the cubes. Numbers can be input in the following formats:·Decimal, with an optional C-stylee+exponentore-exponentfor scientific notation·Hex, with the prefix0x, and an optional C99-stylep+exponentorp-exponentrepresenting a power of 2 multiplier·In any base between 2 and 36, with a prefix of the formbaseN:, e.g.base7:0.123456·As an IEEE 754 hex bit pattern, consisting of exactly 4, 8, 16 or 32 hex digits with the prefixieee:, followed by optional decimal point and extra mantissa digits·From a file in base notation, by writingbaseNfile: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 writingcfracfile:followed by a filename.·Either of the above, but withfile:replaced byxfile: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 writingbaseNfd:orcfracfd:followed by an fd number, e.g.base10fd:0to read from standard input.

**RETURN** **VALUE**

spigotreturns 0 if its output terminates (because the result is exact, or because it reached the specified-dlimit) with no problems. In case of a parse error, or an invalid operand to a function, or any other kind of fatal error,spigotreturns 1. Ifspigotis unable to generate output to the desired precision because more precision was needed from a number read from an input file usingbaseNfile:orcfracfile:, thenspigotreturns 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,spigotis generally unable to recognise when a number it is computing is exactly equal to a specific boundary value. One effect of this is thatspigotwill not behave as you'd like if the output number has a terminating representation in the selected base. For example, asking forsin(asin(0.12345))will not be able to print0.12345and exit. Instead,spigotwill get as far as printing `0.1234', and then print tentative output (mentioned above) to indicate that it thinks the next digitmightbe exactly 5, but it will never reach a point where it'ssureof that. Another effect is that if you askspigotto 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 evenstartproducing output. For example,spigotwill hang completely if you ask it forfloor(sin(pi)), sincesin(pi)=0is a point of discontinuity of thefloorfunction, andspigotwill never be able to work out that the value of the input tofloorisexactlyzero, only that it seems to be closer and closer to zero the more it computes. (An exception is numbers thatspigotknows from first principles to be rational. For example, if you askspigotto evaluate the simpler expressions `0.12345' or `floor(0)', it will print the complete output and terminate successfully, in both cases.)

**LICENCE**

spigotis free software, distributed under the MIT licence. Type `spigot--licence' to see the full licence text.