diff options
Diffstat (limited to 'gnu/usr.bin/dc/doc')
-rw-r--r-- | gnu/usr.bin/dc/doc/dc.texinfo | 314 |
1 files changed, 179 insertions, 135 deletions
diff --git a/gnu/usr.bin/dc/doc/dc.texinfo b/gnu/usr.bin/dc/doc/dc.texinfo index 15b285f..73f687b 100644 --- a/gnu/usr.bin/dc/doc/dc.texinfo +++ b/gnu/usr.bin/dc/doc/dc.texinfo @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename dc.info -@settitle DC, An Arbitrary Precision Calculator +@settitle dc, an arbitrary precision calculator @c %**end of header @c This file has the new style title page commands. @@ -21,7 +21,7 @@ @syncodeindex tp fn @ifinfo -This file documents DC, an arbitrary precision calculator. +This file documents @sc{dc}, an arbitrary precision calculator. Published by the Free Software Foundation, 675 Massachusetts Avenue, @@ -51,15 +51,16 @@ except that this permission notice may be stated in a translation approved by the Foundation. @end ifinfo -@setchapternewpage odd +@setchapternewpage off @titlepage -@title DC, An Arbitrary Precision Calculator +@title dc, an arbitrary precision calculator -@author by Richard Stallman +@author by Ken Pizzini +@author manual by Richard Stallman @page @vskip 0pt plus 1filll -Copyright @copyright{} 1984 Free Software Foundation, Inc. +Copyright @copyright{} 1994 Free Software Foundation, Inc. @sp 2 Published by the Free Software Foundation, @* @@ -94,6 +95,7 @@ by the Foundation. * Parameters:: Parameters * Strings:: Strings * Status Inquiry:: Status Inquiry +* Miscellaneous:: Other commands * Notes:: Notes @end menu @@ -101,27 +103,34 @@ by the Foundation. @comment node-name, next, previous, up @chapter Introduction -DC is a reverse-polish desk calculator which supports unlimited -precision arithmetic. It also allows you to define and call macros. -Normally DC reads from the standard input; if any command arguments -are given to it, they are filenames, and DC reads and executes the -contents of the files before reading from standard input. All output -is to standard output. - -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 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. +@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 +before 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 Printing Commands, Arithmetic, Introduction, Top @chapter Printing Commands @@ -129,19 +138,19 @@ newlines. These have no meaning as 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. +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. +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 -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. +@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 @@ -149,10 +158,9 @@ what the effect of some command has been. @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. +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 @@ -161,41 +169,46 @@ 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 flag (see below) and does not +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 flag. +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. +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 flag specifies, and the remainder -is also computed with that many fraction digits. +as the precision value specifies, +and the remainder is also computed with that many fraction digits. @item ^ -Pops two values and exponentiates, using the first -value popped as the exponent and the second popped as the base. +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 flag specifies the number of fraction +The precision value specifies the number of fraction digits in the result. @item v Pops one value, computes its square root, and pushes that. -The precision flag specifies the number of fraction digits +The precision value specifies the number of fraction digits in the result. @end table -Most arithmetic operations are affected by the "precision flag", -which you can set with the @samp{k} command. The default precision -value is zero, which means that all arithmetic except for +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))}, +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 @@ -207,28 +220,28 @@ Clears the stack, rendering it empty. @item d Duplicates the value on the top of the stack, -pushing another copy of it. Thus, -`4d*p' computes 4 squared and prints it. +pushing another copy of it. +Thus, @samp{4d*p} computes 4 squared and prints it. @end table @node Registers, Parameters, Stack Control, Top @chapter Registers -DC provides 128 memory registers, each named by a single -ASCII character. You can store a number in a register -and retrieve it later. +@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}. +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}. +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. +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 @@ -237,31 +250,34 @@ 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 `l@var{r}' command. +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 - -The @samp{f} command prints a list of all registers that have contents -stored in them, together with their contents. Only the -current contents of each register (the top of its stack) -is printed. +@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 -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. +@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. +@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. Each radix must be between 2 -and 36 inclusive. The precision must be zero or greater. The precision -is always measured in decimal digits, regardless of the current input or -output radix. +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 @@ -269,42 +285,51 @@ Pops the value off the top of the stack and uses it to set the input radix. @item o -@itemx k -Similarly set the output radix and the precision. +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 -@itemx K -Similarly push the current output radix and the current precision. +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 -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 DC commands). -Both registers and the stack can hold strings, and 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; +@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). +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 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. +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}, @@ -312,70 +337,89 @@ 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 +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. +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. This can also be validly used to compare two -strings for equality. +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 comand -does not exit DC. Instead, it exits from that -macro and also from the macro which invoked it (if any). +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. +of levels of macro execution to be exited. +Thus, @samp{3Q} exits three levels. @end table -@node Status Inquiry, Notes, Strings, Top +@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) +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 -1. +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. +Pushes the current stack depth; +the number of objects on the stack +before the execution of the @samp{z} command. +@end table -@item I -Pushes the current value of the input radix. +@node Miscellaneous, Notes, Status Inquiry, Top +@chapter Miscellaneous -@item O -Pushes the current value of the output radix. +@table @samp +@item ! +Will run the rest of the line as a system command. -@item K -Pushes the current value of the precision. +@item # +Will interpret the rest of the line as a comment. + +@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, , Status Inquiry, Top +@node Notes, , Miscellaneous, Top @chapter Notes -The @samp{:} and @samp{;} commands of the Unix DC program are -not supported, as the documentation does not say what they do. -The @samp{!} command is not supported, but will be supported -as soon as a library for executing a line as a command exists. +The array operations @samp{:} and @samp{;} are usually +only used by traditional implementations of BC. +(The GNU BC is self contained and does not need @sc{dc} to run.) +The comment operator @samp{#} is a new command +not found in traditional implementations of @sc{dc}. @contents @bye |