diff options
Diffstat (limited to 'contrib/bc/doc/dc.texi')
| -rw-r--r-- | contrib/bc/doc/dc.texi | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/contrib/bc/doc/dc.texi b/contrib/bc/doc/dc.texi new file mode 100644 index 0000000..e0ade80 --- /dev/null +++ b/contrib/bc/doc/dc.texi @@ -0,0 +1,497 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename dc.info +@settitle dc, an arbitrary precision calculator +@c %**end of header + +@c This file has the new style title page commands. +@c Run `makeinfo' rather than `texinfo-format-buffer'. + +@c smallbook + +@c tex +@c \overfullrule=0pt +@c end tex + +@c Combine indices. +@synindex cp fn +@syncodeindex vr fn +@syncodeindex ky fn +@syncodeindex pg fn +@syncodeindex tp fn + +@ifinfo +This file documents @sc{dc}, an arbitrary precision calculator. + +Published by the Free Software Foundation, +675 Massachusetts Avenue, +Cambridge, MA 02139 USA + +Copyright (C) 1984 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@setchapternewpage off + +@titlepage +@title dc, an arbitrary precision calculator + +@author by Ken Pizzini +@author original manual by Richard Stallman +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1994, 1997 Free Software Foundation, Inc. + +@sp 2 +Published by the Free Software Foundation, @* +675 Massachusetts Avenue, @* +Cambridge, MA 02139 USA + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. + +@end titlepage +@page + +@node Top, Introduction, (dir), (dir) + +@menu +* Introduction:: Introduction +* Invocation:: Invocation +* Printing Commands:: Printing Commands +* Arithmetic:: Arithmetic +* Stack Control:: Stack Control +* Registers:: Registers +* Parameters:: Parameters +* Strings:: Strings +* Status Inquiry:: Status Inquiry +* Miscellaneous:: Other commands +* Notes:: Notes +@end menu + +@node Introduction, Invocation, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +@sc{dc} is a reverse-polish desk calculator +which supports unlimited precision arithmetic. +It also allows you to define and call macros. +Normally @sc{dc} reads from the standard input; +if any command arguments are given to it, they are filenames, +and @sc{dc} reads and executes the contents of the files +instead of reading from standard input. +All normal output is to standard output; +all error messages are written to standard error. + +To exit, use @samp{q}. +@kbd{C-c} does not exit; +it is used to abort macros that are looping, etc. +(Currently this is not true; @kbd{C-c} does exit.) + +A reverse-polish calculator stores numbers on a stack. +Entering a number pushes it on the stack. +Arithmetic operations pop arguments off the stack and push the results. + +To enter a number in @sc{dc}, type the digits, +with an optional decimal point. +Exponential notation is not supported. +To enter a negative number, begin the number with @samp{_}. +@samp{-} cannot be used for this, as it is a binary operator +for subtraction instead. +To enter two numbers in succession, +separate them with spaces or newlines. +These have no meaning as commands. + +@node Invocation, Printing Commands, Introduction, Top +@chapter Invocation + +@sc{dc} may be invoked with the following command-line options: +@table @samp + +@item -e @var{expr} +@item --expression=@var{expr} +Evaluate @var{expr} as @sc{dc} commands. + +@item -f @var{file} +@item --file=@var{file} +Read and evaluate @sc{dc} commands from @var{file}. + +@item -h +@item --help +Print a usage message summarizing the command-line options, then exit. + +@item -V +@item --version +Print the version information for this program, then exit. +@end table + +If any command-line parameters remain after processing the options, +these parameters are interpreted as additional @var{file}s whose +contents are read and evaluated. +A file name of @code{-} refers to the standard input stream. +If no @code{-e} option was specified, and no files were specified, +then the standard input will be read for commands to evaluate. + +@node Printing Commands, Arithmetic, Invocation, Top +@chapter Printing Commands + +@table @samp +@item p +Prints the value on the top of the stack, +without altering the stack. +A newline is printed after the value. + +@item P +Prints the value on the top of the stack, popping it off, +and does not print a newline after. + +@item f +Prints the entire contents of the stack +@c and the contents of all of the registers, +without altering anything. +This is a good command to use if you are lost or want +to figure out what the effect of some command has been. +@end table + +@node Arithmetic, Stack Control, Printing Commands, Top +@chapter Arithmetic + +@table @samp +@item + +Pops two values off the stack, adds them, and pushes the result. +The precision of the result is determined only +by the values of the arguments, and is enough to be exact. + +@item - +Pops two values, subtracts the first one popped +from the second one popped, and pushes the result. + +@item * +Pops two values, multiplies them, and pushes the result. +The number of fraction digits in the result is controlled +by the current precision value (see below) and does not +depend on the values being multiplied. + +@item / +Pops two values, divides the second one popped +from the first one popped, and pushes the result. +The number of fraction digits is specified by the precision value. + +@item % +Pops two values, +computes the remainder of the division that +the @samp{/} command would do, +and pushes that. +The division is done with as many fraction digits +as the precision value specifies, +and the remainder is also computed with that many fraction digits. + +@item ~ +Pops two values, +divides the second one popped from the first one popped. +The quotient is pushed first, and the remainder is pushed next. +The number of fraction digits used in the division +is specified by the precision value. +(The sequence @code{SdSn lnld/ LnLd%} could also accomplish +this function, with slightly different error checking.) +(This command is a GNU extension.) + +@item ^ +Pops two values and exponentiates, +using the first value popped as the exponent +and the second popped as the base. +The fraction part of the exponent is ignored. +The precision value specifies the number of fraction +digits in the result. + +@item | +Pops three values and computes a modular exponentiation. +The first value popped is used as the reduction modulus; +this value must be a non-zero number, +and the result may not be accurate if the modulus +is not an integer. +The second popped is used as the exponent; +this value must be a non-negative number, +and any fractional part of this exponent will be ignored. +The third value popped is the base which gets exponentiated. +The precision value specifies the number of fraction +digits in the result. +For small numbers this is like the sequence @code{Sm lble^ Lm%}, +but, unlike @code{^}, this command will work with arbritrarily large exponents. + +@item v +Pops one value, computes its square root, and pushes that. +The precision value specifies the number of fraction digits +in the result. +@end table + +Most arithmetic operations are affected by the @emph{precision value}, +which you can set with the @samp{k} command. +The default precision value is zero, +which means that all arithmetic except for +addition and subtraction produces integer results. + +The remainder operation (@samp{%}) requires some explanation: +applied to arguments @samp{a} and @samp{b} +it produces @samp{a - (b * (a / b))}, +where @samp{a / b} is computed in the current precision. + +@node Stack Control, Registers, Arithmetic, Top +@chapter Stack Control + +@table @samp +@item c +Clears the stack, rendering it empty. + +@item d +Duplicates the value on the top of the stack, +pushing another copy of it. +Thus, @samp{4d*p} computes 4 squared and prints it. + +@item r +Reverses the order of (swaps) the top two values on the stack. +(This command is a GNU extension.) +@end table + +@node Registers, Parameters, Stack Control, Top +@chapter Registers + +@sc{dc} provides 256 memory registers, each named by a single character. +You can store a number in a register and retrieve it later. + +@table @samp +@item s@var{r} +Pop the value off the top of the stack and +store it into register @var{r}. + +@item l@var{r} +Copy the value in register @var{r}, +and push it onto the stack. +This does not alter the contents of @var{r}. + +Each register also contains its own stack. +The current register value is the top of the register's stack. + +@item S@var{r} +Pop the value off the top of the (main) stack and +push it onto the stack of register @var{r}. +The previous value of the register becomes inaccessible. + +@item L@var{r} +Pop the value off the top of register @var{r}'s stack +and push it onto the main stack. +The previous value in register @var{r}'s stack, if any, +is now accessible via the @samp{l@var{r}} command. +@end table +@c +@c The @samp{f} command prints a list of all registers that have contents +@c stored in them, together with their contents. +@c Only the current contents of each register (the top of its stack) +@c is printed. + +@node Parameters, Strings, Registers, Top +@chapter Parameters + +@sc{dc} has three parameters that control its operation: +the precision, the input radix, and the output radix. +The precision specifies the number of fraction digits +to keep in the result of most arithmetic operations. +The input radix controls the interpretation of numbers typed in; +@emph{all} numbers typed in use this radix. +The output radix is used for printing numbers. + +The input and output radices are separate parameters; +you can make them unequal, which can be useful or confusing. +The input radix must be between 2 and 36 inclusive. +The output radix must be at least 2. +The precision must be zero or greater. +The precision is always measured in decimal digits, +regardless of the current input or output radix. + +@table @samp +@item i +Pops the value off the top of the stack +and uses it to set the input radix. + +@item o +Pops the value off the top of the stack +and uses it to set the output radix. + +@item k +Pops the value off the top of the stack +and uses it to set the precision. + +@item I +Pushes the current input radix on the stack. + +@item O +Pushes the current output radix on the stack. + +@item K +Pushes the current precision on the stack. + +@end table + +@node Strings, Status Inquiry, Parameters, Top +@chapter Strings + +@sc{dc} can operate on strings as well as on numbers. +The only things you can do with strings are print them +and execute them as macros +(which means that the contents of the string are processed as @sc{dc} commands). +Both registers and the stack can hold strings, +and @sc{dc} always knows whether any given object is a string or a number. +Some commands such as arithmetic operations demand numbers +as arguments and print errors if given strings. +Other commands can accept either a number or a string; +for example, the @samp{p} command can accept either and prints the object +according to its type. + +@table @samp +@item [@var{characters}] +Makes a string containing @var{characters} and pushes it on the stack. +For example, @samp{[foo]P} prints the characters @samp{foo} +(with no newline). + +@item a +The mnemonic for this is somewhat erroneous: asciify. +The top-of-stack is popped. +If it was a number, then the low-order byte of this number +is converted into a string and pushed onto the stack. +Otherwise the top-of-stack was a string, +and the first character of that string is pushed back. +(This command is a GNU extension.) + +@item x +Pops a value off the stack and executes it as a macro. +Normally it should be a string; +if it is a number, it is simply pushed back onto the stack. +For example, @samp{[1p]x} executes the macro @samp{1p}, +which pushes 1 on the stack and prints @samp{1} on a separate line. + +Macros are most often stored in registers; +@samp{[1p]sa} stores a macro to print @samp{1} into register @samp{a}, +and @samp{lax} invokes the macro. + +@item >@var{r} +Pops two values off the stack and compares them +assuming they are numbers, +executing the contents of register @var{r} as a macro +if the original top-of-stack is greater. +Thus, @samp{1 2>a} will invoke register @samp{a}'s contents +and @samp{2 1>a} will not. + +@item <@var{r} +Similar but invokes the macro if the original top-of-stack is less. + +@item =@var{r} +Similar but invokes the macro if the two numbers popped are equal. +@c This can also be validly used to compare two strings for equality. + +@item ? +Reads a line from the terminal and executes it. +This command allows a macro to request input from the user. + +@item q +During the execution of a macro, +this command exits from the macro and also from the macro which invoked it. +If called from the top level, +or from a macro which was called directly from the top level, +the @samp{q} command will cause @sc{dc} to exit. + +@item Q +Pops a value off the stack and uses it as a count +of levels of macro execution to be exited. +Thus, @samp{3Q} exits three levels. +@end table + +@node Status Inquiry, Miscellaneous, Strings, Top +@chapter Status Inquiry + +@table @samp +@item Z +Pops a value off the stack, +calculates the number of digits it has +(or number of characters, if it is a string) +and pushes that number. + +@item X +Pops a value off the stack, +calculates the number of fraction digits it has, +and pushes that number. +For a string, the value pushed is +@c -1. +0. + +@item z +Pushes the current stack depth; +the number of objects on the stack +before the execution of the @samp{z} command. +@end table + +@node Miscellaneous, Notes, Status Inquiry, Top +@chapter Miscellaneous + +@table @samp +@item ! +Will run the rest of the line as a system command. + +@item # +Will interpret the rest of the line as a comment. +(This command is a GNU extension.) + +@item :@var{r} +Will pop the top two values off of the stack. +The old second-to-top value will be stored in the array @var{r}, +indexed by the old top-of-stack value. + +@item ;@var{r} +Pops the top-of-stack and uses it as an index into +the array @var{r}. +The selected value is then pushed onto the stack. +@end table + +@node Notes, , Miscellaneous, Top +@chapter Notes + +The array operations @samp{:} and @samp{;} are usually +only used by traditional implementations of BC. +(The GNU implementation of BC is self contained +and does not need any version of @sc{dc} to run.) + +Email bug reports to @code{bug-gnu-utils@@prep.ai.mit.edu}. +Be sure to include the word ``dc'' somewhere in the ``Subject:'' field. + +@contents +@bye |
