I/O and Formatting Functions
............................

The functions described here are responsible for parsing and
formatting Calc numbers and formulas.

 -- Function: calc-eval STR SEP ARG1 ARG2 ...
     This is the simplest interface to the Calculator from another Lisp program.
     See Calling Calc from Your Programs.

 -- Function: read-number STR
     If string STR contains a valid Calc number, either integer,
     fraction, float, or HMS form, this function parses and returns
     that number.  Otherwise, it returns `nil'.

 -- Function: read-expr STR
     Read an algebraic expression from string STR.  If STR does not
     have the form of a valid expression, return a list of the form
     `(error POS MSG)' where POS is an integer index into STR of the
     general location of the error, and MSG is a string describing the
     problem.

 -- Function: read-exprs STR
     Read a list of expressions separated by commas, and return it as
     a Lisp list.  If an error occurs in any expressions, an error
     list as shown above is returned instead.

 -- Function: calc-do-alg-entry INITIAL PROMPT NO-NORM
     Read an algebraic formula or formulas using the minibuffer.  All
     conventions of regular algebraic entry are observed.  The return
     value is a list of Calc formulas; there will be more than one if
     the user entered a list of values separated by commas.  The
     result is `nil' if the user presses Return with a blank line.  If
     INITIAL is given, it is a string which the minibuffer will
     initially contain.  If PROMPT is given, it is the prompt string
     to use; the default is "Algebraic:".  If NO-NORM is `t', the
     formulas will be returned exactly as parsed; otherwise, they will
     be passed through `calc-normalize' first.

     To support the use of `$' characters in the algebraic entry, use
     `let' to bind `calc-dollar-values' to a list of the values to be
     substituted for `$', `$$', and so on, and bind `calc-dollar-used'
     to 0.  Upon return, `calc-dollar-used' will have been changed to
     the highest number of consecutive `$'s that actually appeared in
     the input.

 -- Function: format-number A
     Convert the real or complex number or HMS form A to string form.

 -- Function: format-flat-expr A PREC
     Convert the arbitrary Calc number or formula A to string form, in
     the style used by the trail buffer and the `calc-edit' command.
     This is a simple format designed mostly to guarantee the string
     is of a form that can be re-parsed by `read-expr'.  Most
     formatting modes, such as digit grouping, complex number format,
     and point character, are ignored to ensure the result will be
     re-readable.  The PREC parameter is normally 0; if you pass a
     large integer like 1000 instead, the expression will be
     surrounded by parentheses unless it is a plain number or variable
     name.

 -- Function: format-nice-expr A WIDTH
     This is like `format-flat-expr' (with PREC equal to 0), except
     that newlines will be inserted to keep lines down to the
     specified WIDTH, and vectors that look like matrices or rewrite
     rules are written in a pseudo-matrix format.  The `calc-edit'
     command uses this when only one stack entry is being edited.

 -- Function: format-value A WIDTH
     Convert the Calc number or formula A to string form, using the
     format seen in the stack buffer.  Beware the the string returned
     may not be re-readable by `read-expr', for example, because of
     digit grouping.  Multi-line objects like matrices produce strings
     that contain newline characters to separate the lines.  The W
     parameter, if given, is the target window size for which to
     format the expressions.  If W is omitted, the width of the
     Calculator window is used.

 -- Function: compose-expr A PREC
     Format the Calc number or formula A according to the current
     language mode, returning a "composition."  To learn about the
     structure of compositions, see the comments in the Calc source
     code.  You can specify the format of a given type of function
     call by putting a `math-compose-LANG' property on the function's
     symbol, whose value is a Lisp function that takes A and PREC as
     arguments and returns a composition.  Here LANG is a language
     mode name, one of `normal', `big', `c', `pascal', `fortran',
     `tex', `eqn', `math', or `maple'.  In Big mode, Calc actually
     tries `math-compose-big' first, then tries `math-compose-normal'.
     If this property does not exist, or if the function returns
     `nil', the function is written in the normal function-call
     notation for that language.

 -- Function: composition-to-string C W
     Convert a composition structure returned by `compose-expr' into a
     string.  Multi-line compositions convert to strings containing
     newline characters.  The target window size is given by W.  The
     `format-value' function basically calls `compose-expr' followed
     by `composition-to-string'.

 -- Function: comp-width C
     Compute the width in characters of composition C.

 -- Function: comp-height C
     Compute the height in lines of composition C.

 -- Function: comp-ascent C
     Compute the portion of the height of composition C which is on or
     above the baseline.  For a one-line composition, this will be
     one.

 -- Function: comp-descent C
     Compute the portion of the height of composition C which is below
     the baseline.  For a one-line composition, this will be zero.

 -- Function: comp-first-char C
     If composition C is a "flat" composition, return the first
     (leftmost) character of the composition as an integer.
     Otherwise, return `nil'.

 -- Function: comp-last-char C
     If composition C is a "flat" composition, return the last
     (rightmost) character, otherwise return `nil'.