diff options
Diffstat (limited to 'doc/dc.info')
| -rw-r--r-- | doc/dc.info | 441 |
1 files changed, 441 insertions, 0 deletions
diff --git a/doc/dc.info b/doc/dc.info new file mode 100644 index 0000000..050a6b3 --- /dev/null +++ b/doc/dc.info @@ -0,0 +1,441 @@ +This is dc.info, produced by makeinfo version 4.0 from dc.texi. + +START-INFO-DIR-ENTRY +* dc: (dc). Arbritrary precision RPN "Desktop Calculator". +END-INFO-DIR-ENTRY + This file documents DC, an arbitrary precision calculator. + + Published by the Free Software Foundation, Inc. 59 Temple Place, +Suite 330 Boston, MA 02111 USA + + Copyright (C) 1984, 1994, 1997, 1998, 2000 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. + + 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. + + +File: dc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (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 +* Reporting bugs:: Reporting bugs + + +File: dc.info, Node: Introduction, Next: Invocation, Prev: Top, Up: Top + +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 instead of reading from standard input. All normal output +is to standard output; all error messages are written to standard error. + + To exit, use `q'. `C-c' does not exit; it is used to abort macros +that are looping, etc. (Currently this is not true; `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 `_'. `-' 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. + + +File: dc.info, Node: Invocation, Next: Printing Commands, Prev: Introduction, Up: Top + +Invocation +********** + + DC may be invoked with the following command-line options: +`-e EXPR' + +`--expression=EXPR' + Evaluate EXPR as DC commands. + +`-f FILE' + +`--file=FILE' + Read and evaluate DC commands from FILE. + +`-h' + +`--help' + Print a usage message summarizing the command-line options, then + exit. + +`-V' + +`--version' + Print the version information for this program, then exit. + + If any command-line parameters remain after processing the options, +these parameters are interpreted as additional FILEs whose contents are +read and evaluated. A file name of `-' refers to the standard input +stream. If no `-e' option was specified, and no files were specified, +then the standard input will be read for commands to evaluate. + + +File: dc.info, Node: Printing Commands, Next: Arithmetic, Prev: Invocation, Up: Top + +Printing Commands +***************** + +`p' + Prints the value on the top of the stack, without altering the + stack. A newline is printed after the value. + +`n' + Prints the value on the top of the stack, popping it off, and does + not print a newline after. (This command is a GNU extension.) + +`P' + Pops off the value on top of the stack. If it it a string, it is + simply printed without a trailing newline. Otherwise it is a + number, and the integer portion of its absolute value is printed + out as a "base (UCHAR_MAX+1)" byte stream. Assuming that + (UCHAR_MAX+1) is 256 (as it is on most machines with 8-bit bytes), + the sequence `KSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk' could + also accomplish this function, except for the side-effect of + clobbering the x register. (Details of the behavior with a number + are a GNU extension.) + +`f' + Prints the entire contents of the stack 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. + + +File: dc.info, Node: Arithmetic, Next: Stack Control, Prev: Printing Commands, Up: Top + +Arithmetic +********** + +`+' + 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, subtracts the first one popped from the second + one popped, and pushes the result. + +`*' + Pops two values, multiplies them, and pushes the result. The + number of fraction digits in the result is the largest of the + precision value, the number of fraction digits in the multiplier, + or the number of fraction digits in the multiplicand; but in no + event exceeding the number of digits required for an exact result. + +`/' + 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. + +`%' + Pops two values, computes the remainder of the division that the + `/' command would do, and pushes that. The value computed is the + same as that computed by the sequence `Sd dld/ Ld*-' . + +`~' + 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 `SdSn lnld/ + LnLd%' could also accomplish this function, with slightly + different error checking.) (This command is a GNU extension.) + +`^' + 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. + +`|' + 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, which should be an + integer. For small integers this is like the sequence `Sm^Lm%', + but, unlike `^', this command will work with arbritrarily large + exponents. (This command is a GNU extension.) + +`v' + Pops one value, computes its square root, and pushes that. The + precision value specifies the number of fraction digits in the + result. + + Most arithmetic operations are affected by the _precision value_, +which you can set with the `k' command. The default precision value is +zero, which means that all arithmetic except for addition and +subtraction produces integer results. + + +File: dc.info, Node: Stack Control, Next: Registers, Prev: Arithmetic, Up: Top + +Stack Control +************* + +`c' + Clears the stack, rendering it empty. + +`d' + Duplicates the value on the top of the stack, pushing another copy + of it. Thus, `4d*p' computes 4 squared and prints it. + +`r' + Reverses the order of (swaps) the top two values on the stack. + (This command is a GNU extension.) + + +File: dc.info, Node: Registers, Next: Parameters, Prev: Stack Control, Up: Top + +Registers +********* + + DC provides at least 256 memory registers, each named by a single +character. You can store a number in a register and retrieve it later. + +`sR' + Pop the value off the top of the stack and store it into register + R. + +`lR' + Copy the value in register R, and push it onto the stack. This + does not alter the contents of R. + + Each register also contains its own stack. The current register + value is the top of the register's stack. + +`SR' + Pop the value off the top of the (main) stack and push it onto the + stack of register R. The previous value of the register becomes + inaccessible. + +`LR' + Pop the value off the top of register R's stack and push it onto + the main stack. The previous value in register R's stack, if any, + is now accessible via the `lR' command. + + +File: dc.info, Node: Parameters, Next: Strings, Prev: Registers, Up: Top + +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. The input radix controls the interpretation of numbers +typed in; _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 16 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. + +`i' + Pops the value off the top of the stack and uses it to set the + input radix. + +`o' + Pops the value off the top of the stack and uses it to set the + output radix. + +`k' + Pops the value off the top of the stack and uses it to set the + precision. + +`I' + Pushes the current input radix on the stack. + +`O' + Pushes the current output radix on the stack. + +`K' + Pushes the current precision on the stack. + + +File: dc.info, Node: Strings, Next: Status Inquiry, Prev: Parameters, Up: Top + +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; for example, the `p' command can accept either and +prints the object according to its type. + +`[CHARACTERS]' + Makes a string containing CHARACTERS and pushes it on the stack. + For example, `[foo]P' prints the characters `foo' (with no + newline). + +`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.) + +`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, `[1p]x' executes the macro `1p', + which pushes 1 on the stack and prints `1' on a separate line. + + Macros are most often stored in registers; `[1p]sa' stores a macro + to print `1' into register `a', and `lax' invokes the macro. + +`>R' + Pops two values off the stack and compares them assuming they are + numbers, executing the contents of register R as a macro if the + original top-of-stack is greater. Thus, `1 2>a' will invoke + register `a''s contents and `2 1>a' will not. + +`!>R' + Similar but invokes the macro if the original top-of-stack is not + greater (is less than or equal to) what was the second-to-top. + +`<R' + Similar but invokes the macro if the original top-of-stack is less. + +`!<R' + Similar but invokes the macro if the original top-of-stack is not + less (is greater than or equal to) what was the second-to-top. + +`=R' + Similar but invokes the macro if the two numbers popped are equal. + +`!=R' + Similar but invokes the macro if the two numbers popped are not + equal. + +`?' + Reads a line from the terminal and executes it. This command + allows a macro to request input from the user. + +`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 `q' command will cause DC to exit. + +`Q' + Pops a value off the stack and uses it as a count of levels of + macro execution to be exited. Thus, `3Q' exits three levels. + + +File: dc.info, Node: Status Inquiry, Next: Miscellaneous, Prev: Strings, Up: Top + +Status Inquiry +************** + +`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. + +`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 0. + +`z' + Pushes the current stack depth: the number of objects on the stack + before the execution of the `z' command. + + +File: dc.info, Node: Miscellaneous, Next: Reporting bugs, Prev: Status Inquiry, Up: Top + +Miscellaneous +************* + +`!' + Will run the rest of the line as a system command. Note that + parsing of the !<, !=, and !> commands take precidence, so if you + want to run a command starting with <, =, or > you will need to + add a space after the !. + +`#' + Will interpret the rest of the line as a comment. (This command + is a GNU extension.) + +`:R' + Will pop the top two values off of the stack. The old + second-to-top value will be stored in the array R, indexed by the + old top-of-stack value. + +`;R' + Pops the top-of-stack and uses it as an index into the array R. + The selected value is then pushed onto the stack. + + Note that each stacked instance of a register has its own array +associated with it. Thus `1 0:A 0SA 2 0:A LA 0;Ap' will print 1, +because the 2 was stored in an instance of 0:A that was later popped. + + +File: dc.info, Node: Reporting bugs, Prev: Miscellaneous, Up: Top + +Reporting bugs +************** + + Email bug reports to <bug-dc@gnu.org>. + + + +Tag Table: +Node: Top1084 +Node: Introduction1663 +Node: Invocation2880 +Node: Printing Commands3724 +Node: Arithmetic4902 +Node: Stack Control7815 +Node: Registers8228 +Node: Parameters9154 +Node: Strings10415 +Node: Status Inquiry13385 +Node: Miscellaneous13942 +Node: Reporting bugs14909 + +End Tag Table |