adding GNU dc ("desk calculator")

2 files changed, 711 insertions, 0 deletions

diff --git a/gnu/usr.bin/dc/dc.info b/gnu/usr.bin/dc/dc.info
new file mode 100644
index 0000000..a30fea9
--- /dev/null
+++ b/gnu/usr.bin/dc/dc.info
@@ -0,0 +1,330 @@
+This is Info file dc.info, produced by Makeinfo-1.52 from the input
+file dc.texinfo.
+
+   This file documents 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.
+
+   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
+* Printing Commands::           Printing Commands
+* Arithmetic::                  Arithmetic
+* Stack Control::               Stack Control
+* Registers::                   Registers
+* Parameters::                  Parameters
+* Strings::                     Strings
+* Status Inquiry::              Status Inquiry
+* Notes::                       Notes
+
+
+File: dc.info,  Node: Introduction,  Next: Printing Commands,  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 before reading from standard input.  All output is to
+standard output.
+
+   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: Printing Commands,  Next: Arithmetic,  Prev: Introduction,  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.
+
+`P'
+     Prints the value on the top of the stack, popping it off, and does
+     not print a newline after.
+
+`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.
+
+
+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 controlled by the
+     current precision flag (see below) and does not depend on the
+     values being multiplied.
+
+`/'
+     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, computes the remainder of the division that the
+     `/' 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.
+
+`^'
+     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 digits in the result.
+
+`v'
+     Pops one value, computes its square root, and pushes that.  The
+     precision flag specifies the number of fraction digits in the
+     result.
+
+   Most arithmetic operations are affected by the "precision flag",
+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.
+
+   The remainder operation (`%') requires some explanation: applied to
+arguments `a' and `b' it produces `a - (b * (a / b))', where `a / b' is
+computed in the current precision.
+
+
+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.
+
+
+File: dc.info,  Node: Registers,  Next: Parameters,  Prev: Stack Control,  Up: Top
+
+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.
+
+`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.
+
+   The `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.
+
+
+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.  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.
+
+`i'
+     Pops the value off the top of the stack and uses it to set the
+     input radix.
+
+`o'
+`k'
+     Similarly set the output radix and the precision.
+
+`I'
+     Pushes the current input radix on the stack.
+
+`O'
+`K'
+     Similarly push the current output radix and the current precision.
+
+
+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).
+
+`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 less.
+
+`=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.
+
+`?'
+     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 comand does not exit DC.
+     Instead, it exits from that macro and also from the macro which
+     invoked it (if any).
+
+`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: Notes,  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 -1.
+
+`z'
+     Pushes the current stack depth; the number of objects on the stack
+     before the execution of the `z' command.
+
+`I'
+     Pushes the current value of the input radix.
+
+`O'
+     Pushes the current value of the output radix.
+
+`K'
+     Pushes the current value of the precision.
+
+
+File: dc.info,  Node: Notes,  Prev: Status Inquiry,  Up: Top
+
+Notes
+*****
+
+   The `:' and `;' commands of the Unix DC program are not supported,
+as the documentation does not say what they do.  The `!' command is not
+supported, but will be supported as soon as a library for executing a
+line as a command exists.
+
+
+
+Tag Table:
+Node: Top960
+Node: Introduction1440
+Node: Printing Commands2603
+Node: Arithmetic3211
+Node: Stack Control5168
+Node: Registers5468
+Node: Parameters6586
+Node: Strings7659
+Node: Status Inquiry9857
+Node: Notes10571
+
+End Tag Table
diff --git a/gnu/usr.bin/dc/dc.texinfo b/gnu/usr.bin/dc/dc.texinfo
new file mode 100644
index 0000000..15b285f
--- /dev/null
+++ b/gnu/usr.bin/dc/dc.texinfo
@@ -0,0 +1,381 @@
+\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 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 odd
+
+@titlepage
+@title DC, An Arbitrary Precision Calculator
+
+@author by Richard Stallman
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1984 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
+* Printing Commands::           Printing Commands
+* Arithmetic::                  Arithmetic
+* Stack Control::               Stack Control
+* Registers::                   Registers
+* Parameters::                  Parameters
+* Strings::                     Strings
+* Status Inquiry::              Status Inquiry
+* Notes::                       Notes
+@end menu
+
+@node Introduction, Printing Commands, Top, Top
+@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.
+
+@node Printing Commands, Arithmetic, Introduction, 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
+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 flag (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.
+
+@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 flag 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.
+The fraction part of the exponent is ignored.
+The precision flag 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
+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
+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,
+`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.
+
+@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 `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.
+
+@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.
+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.  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.
+
+@table @samp
+@item i
+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.
+
+@item I
+Pushes the current input radix on the stack.
+
+@item O
+@itemx K
+Similarly push the current output radix and the current precision.
+@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;
+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 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.  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).
+
+@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, Notes, 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 -1.
+
+@item z
+Pushes the current stack depth; the number of
+objects on the stack before the execution of the @samp{z} command.
+
+@item I
+Pushes the current value of the input radix.
+
+@item O
+Pushes the current value of the output radix.
+
+@item K
+Pushes the current value of the precision.
+@end table
+
+@node Notes,  , Status Inquiry, 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.
+
+@contents
+@bye