calc: Formatting Lisp Functions
18.5.7.8 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. 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 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’.