daveg@near.cs.caltech.edu (Dave Gillespie) (10/24/90)
#!/bin/sh
# this is part 5 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file calc.patch continued
#
CurArch=5
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
exit 1; fi
( read Scheck
if test "$Scheck" != $CurArch
then echo "Please unpack part $Scheck next!"
exit 1;
else exit 0; fi
) < s2_seq_.tmp || exit 1
sed 's/^X//' << 'SHAR_EOF' >> calc.patch
X+ will be evaluated first, and they may be ineffectual if this is not
X+ the case.
X+
X+ Another example where top-level evaluation @emph{is} useful: Typing
X+ @kbd{V R +} to sum the vector @samp{[1, 2, 3, 4]} produces the formula
X+ @samp{reduce(add, [1, 2, 3, 4])}. Using @kbd{a v} will evaluate this
X+ all the way to 10; using @kbd{C-u - a v} will evaluate it only to
X+ @samp{1 + 2 + 3 + 4}. (@xref{Reducing and Mapping}.)
X+
X @kindex a s
X @pindex calc-simplify
X The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies
X***************
X*** 11485,11490 ****
X--- 12162,12173 ----
X only,'' Calc (like most other symbolic integration programs) will simply
X produce an unqualified result.@refill
X
X+ Because @kbd{a e}'s simplifications are unsafe, it is sometimes better
X+ to type @kbd{C-u - 3 a v}, which does extended simplification only
X+ on the top level of the formula without affecting the sub-formulas.
X+ In fact, @kbd{C-u - 3 j v} allows you to target extended simplification
X+ to any specific part of a formula.
X+
X @kindex a x
X @pindex calc-expand
X The @kbd{a x} (@code{calc-expand}) command expands an expression by
X***************
X*** 11540,11546 ****
X because the @samp{+} operator is left-associative, so the ``deep
X structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U}
X (@code{calc-unformatted-language}) mode to see the true structure of
X! a formula. The rewrite rule mechanism, discussed next, does not have
X these limitations.
X
X @node Calculus, Numerical Solutions, Algebraic Manipulation, Algebra
X--- 12223,12229 ----
X because the @samp{+} operator is left-associative, so the ``deep
X structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U}
X (@code{calc-unformatted-language}) mode to see the true structure of
X! a formula. The rewrite rule mechanism, discussed later, does not have
X these limitations.
X
X @node Calculus, Numerical Solutions, Algebraic Manipulation, Algebra
X***************
X*** 11684,11689 ****
X--- 12367,12399 ----
X You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a
X fully general inverse, as described above.
X
X+ @kindex a P
X+ @pindex calc-poly-roots
X+ @tindex roots
X+ Some equations, specifically polynomials, have a known, finite number
X+ of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}]
X+ command uses @kbd{H a S} to solve an equation in general form, then, for
X+ all arbitrary-sign variables like @code{s1}, and all arbitrary-integer
X+ variables like @code{n1} for which @code{n1} only usefully varies over
X+ a finite range, it expands these variables out to all their possible
X+ values. The results are collected into a vector, which is returned.
X+ For example, @samp{roots(x^4 = 1, x)} returns the four solutions
X+ @samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree
X+ polynomial will always have @var{n} roots on the complex plane.
X+
X+ Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver
X+ symbolic solutions if the polynomial has symbolic coefficients. Also
X+ note that Calc's solver is not able to solve all polynomials even if
X+ the coefficients are all simple numbers. Polynomials containing
X+ powers up to @samp{x^4} can always be solved; polynomials of higher
X+ degree can sometimes be solved: @samp{x^6 + x^3 + 1} is converted
X+ to @samp{(x^3)^2 + (x^3) + 1}, which can be solved for @samp{x^3}
X+ using the quadratic equation, and then for @samp{x} by taking cube
X+ roots. But in many cases, like @samp{x^6 + x + 1}, Calc does
X+ not know how to rewrite the polynomial into a form it can solve.
X+ For these you must factor the polynomial by hand if you can, or
X+ else use the @kbd{a R} command discussed next.
X+
X @node Numerical Solutions, Logical Operations, Calculus, Algebra
X @section Numerical Solutions
X
X***************
X*** 11776,11782 ****
X--- 12486,12494 ----
X Calc's explanation for why no root was found.
X
X @kindex a N
X+ @kindex H a N
X @kindex a X
X+ @kindex H a X
X @pindex calc-find-minimum
X @pindex calc-find-maximum
X @tindex minimize
X***************
X*** 12124,12130 ****
X account:
X
X @example
X! + - * = != && || and or xor gcd lcm max min beta
X @end example
X
X For example, the rewrite rule:
X--- 12836,12842 ----
X account:
X
X @example
X! + - * = != && || and or xor vint vunion vxor gcd lcm max min beta
X @end example
X
X For example, the rewrite rule:
X***************
X*** 12163,12168 ****
X--- 12875,12885 ----
X four terms with @samp{a} matching the remainder. Half-and-half matches,
X like @samp{(x + y) + (z - w)}, are not tried.
X
X+ Note that @samp{*} is not commutative when applied to matrices, but the
X+ rewrite rules pretend that it is. If you are working with matrices,
X+ some caution is necessary with rewrites to make sure they don't take
X+ undue liberties with your matrix products.
X+
X The pattern @samp{-x} will actually match any expression. For example,
X the rule
X
X***************
X*** 12283,12288 ****
X--- 13000,13013 ----
X g(x), temp = x+1]} where the @samp{x-1} term must correspond to an
X actual ``something-minus-one'' in the target formula.
X
X+ A successful way to write this would be @samp{[ f(x, x+2), g(x+1) ]}.
X+ You could make this resemble the original form more closely by using
X+ @code{let} notation, which is described in the next section:
X+
X+ @example
X+ [ f(xm1, x+1), g(x), let(x, xm1+1) ]
X+ @end example
X+
X Calc does this rewriting or ``conditionalizing'' for any sub-pattern
X which involves only the functions in the following list, operating
X only on constants and meta-variables which have already been matched
X***************
X*** 12399,12405 ****
X
X @table @samp
X @item quote(x)
X! @findex quote
X This pattern matches exactly @samp{x}; variable names in @samp{x} are
X not interpreted as meta-variables. The only flexibility is that
X numbers are compared for numeric equality, so that the pattern
X--- 13124,13130 ----
X
X @table @samp
X @item quote(x)
X! @tindex quote
X This pattern matches exactly @samp{x}; variable names in @samp{x} are
X not interpreted as meta-variables. The only flexibility is that
X numbers are compared for numeric equality, so that the pattern
X***************
X*** 12410,12416 ****
X as a result in this case.)
X
X @item plain(x)
X! @findex plain
X Here @samp{x} must be a function call @samp{f(x1,x2,@dots{})}. This
X pattern matches a call to function @samp{f} with the specified
X argument patterns. No special knowledge of the properties of the
X--- 13135,13141 ----
X as a result in this case.)
X
X @item plain(x)
X! @tindex plain
X Here @samp{x} must be a function call @samp{f(x1,x2,@dots{})}. This
X pattern matches a call to function @samp{f} with the specified
X argument patterns. No special knowledge of the properties of the
X***************
X*** 12421,12427 ****
X @samp{plain(plain(-a) + plain(b c))}.
X
X @item opt(x,def)
X! @findex opt
X Here @samp{x} must be a variable name. This must appear as an
X argument to a function or an element of a vector; it specifies that
X the argument or element is optional.
X--- 13146,13152 ----
X @samp{plain(plain(-a) + plain(b c))}.
X
X @item opt(x,def)
X! @tindex opt
X Here @samp{x} must be a variable name. This must appear as an
X argument to a function or an element of a vector; it specifies that
X the argument or element is optional.
X***************
X*** 12442,12448 ****
X In other words, the default @code{def} is effectively quoted.@refill
X
X @item condition(x,c)
X! @findex condition
X This matches the pattern @samp{x}, with the attached condition
X @samp{c}. The rule @samp{[condition(f(n x), integer(n)), n f(x)]}
X is functionally equivalent to @samp{[f(n x), n f(x), integer(n)]}.
X--- 13167,13173 ----
X In other words, the default @code{def} is effectively quoted.@refill
X
X @item condition(x,c)
X! @tindex condition
X This matches the pattern @samp{x}, with the attached condition
X @samp{c}. The rule @samp{[condition(f(n x), integer(n)), n f(x)]}
X is functionally equivalent to @samp{[f(n x), n f(x), integer(n)]}.
X***************
X*** 12462,12468 ****
X @samp{x % a = b} where @samp{a} and @samp{b} are constants.
X
X @item cons(h,t)
X! @findex cons
X This matches any vector of one or more elements. The first
X element is matched to @samp{h}; a vector of the remaining
X elements is matched to @samp{t}. Note that vectors of fixed
X--- 13187,13193 ----
X @samp{x % a = b} where @samp{a} and @samp{b} are constants.
X
X @item cons(h,t)
X! @tindex cons (rewrites)
X This matches any vector of one or more elements. The first
X element is matched to @samp{h}; a vector of the remaining
X elements is matched to @samp{t}. Note that vectors of fixed
X***************
X*** 12474,12481 ****
X rule set consisting of two rules, the latter one being
X invalid.
X
X @item apply(f,args)
X! @findex apply (rewrites)
X This matches any function call. The name of the function, in
X the form of a variable, is matched to @samp{f}. The arguments
X of the function, as a vector of zero or more objects, are
X--- 13199,13212 ----
X rule set consisting of two rules, the latter one being
X invalid.
X
X+ @item rcons(t,h)
X+ @tindex rcons (rewrites)
X+ This is like @code{cons}, except that the @emph{last} element
X+ is matched to @samp{h}, with the remaining elements matched
X+ to @samp{t}.
X+
X @item apply(f,args)
X! @tindex apply (rewrites)
X This matches any function call. The name of the function, in
X the form of a variable, is matched to @samp{f}. The arguments
X of the function, as a vector of zero or more objects, are
X***************
X*** 12505,12511 ****
X for formulas which are calls to @code{floor}.
X
X @item select(x)
X! @findex select
X This is used for applying rules to formulas with selections;
X @pxref{Selections with Rewrite Rules}.
X @end table
X--- 13236,13242 ----
X for formulas which are calls to @code{floor}.
X
X @item select(x)
X! @tindex select (rewrites)
X This is used for applying rules to formulas with selections;
X @pxref{Selections with Rewrite Rules}.
X @end table
X***************
X*** 12536,12541 ****
X--- 13267,13276 ----
X side of a rule will be evaluated even if default simplifications
X have been turned off.
X
X+ @item rcons(t,h)
X+ Analogous to @code{cons} except putting @code{h} at the @emph{end} of
X+ the vector.
X+
X @item apply(f,args)
X Where @samp{f} is a variable and @samp{args} is a vector, this
X is converted to a function call. Once again, note that @code{apply}
X***************
X*** 12542,12548 ****
X is also a regular Calc function.
X
X @item eval(x)
X! @findex eval
X The formula @samp{x} is handled in the usual way, then the
X default simplifications are applied to it even if they have
X been turned off normally. This allows you to treat any function
X--- 13277,13283 ----
X is also a regular Calc function.
X
X @item eval(x)
X! @tindex eval
X The formula @samp{x} is handled in the usual way, then the
X default simplifications are applied to it even if they have
X been turned off normally. This allows you to treat any function
X***************
X*** 12552,12566 ****
X whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}.
X
X @item evalsimp(x)
X! @findex evalsimp
X The formula @samp{x} has meta-variables substituted in the usual
X way, then algebraically simplified as if by the @kbd{a s} command.
X
X @item select(x)
X @xref{Selections with Rewrite Rules}.
X @end table
X
X! There is also one special function you can use in conditions, both
X as the third part of a rule vector and as the second argument of
X @code{condition}.
X
X--- 13287,13306 ----
X whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}.
X
X @item evalsimp(x)
X! @tindex evalsimp
X The formula @samp{x} has meta-variables substituted in the usual
X way, then algebraically simplified as if by the @kbd{a s} command.
X
X+ @item evalextsimp(x)
X+ @tindex evalextsimp
X+ The formula @samp{x} has meta-variables substitited in the normal
X+ way, then ``extendedly'' simplified as if by the @kbd{a e} command.
X+
X @item select(x)
X @xref{Selections with Rewrite Rules}.
X @end table
X
X! There are also two special functions you can use in conditions, both
X as the third part of a rule vector and as the second argument of
X @code{condition}.
X
X***************
X*** 12574,12579 ****
X--- 13314,13346 ----
X be manipulated on the Calc stack because @samp{variable(a)} will
X immediately be evaluated to 1. But @samp{[a, f(a), quote(variable(a))]}
X will work properly.
X+
X+ @item let(v,x)
X+ @tindex let (rewrites)
X+ The expression @samp{x} is evaluated with meta-variables substituted.
X+ The @kbd{a s} command's simplifications are @emph{not} applied by
X+ default, but @samp{x} can include calls to @code{evalsimp} or
X+ @code{evalextsimp} as described above to invoke higher levels
X+ of simplification. The
X+ result of @samp{x} is then bound to the meta-variable @samp{v}. As
X+ usual, if this meta-variable has already been matched to something
X+ else the two values must be equal; if the meta-variable is new then
X+ it is bound to the result of the expression. It can then appear in
X+ later conditions, and on the righthand side of the rule. Note that
X+ @code{let} can only appear by itself as the condition, or as one term
X+ of an @samp{&&} which is the whole condition: It cannot be inside
X+ an @samp{||} term or otherwise buried.@refill
X+
X+ As an example, the rule
X+ @samp{[f(a), g(ia), let(ia,1/a) && constant(ia)]} replaces @samp{f(a)}
X+ with @samp{g} of the inverse of @samp{a}, if that inverse exists and
X+ is constant. For example, if @samp{a} is a singular matrix the
X+ operation @samp{1/a} is left unsimplified and @samp{constant(ia)}
X+ fails, but if @samp{a} is an invertible matrix then the rule succeeds.
X+ Without @code{let} there would be no way to implement this rule that
X+ didn't have to invert the matrix twice. Note that the @code{let}
X+ condition itself always ``succeeds'' unless the meta-variable
X+ has already been matched to a different value.@refill
X @end table
X
X @node Nested Formulas with Rewrite Rules, Selections with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules
X***************
X*** 12666,12675 ****
X markers are ignored by the rewrite mechanism and the rules are allowed
X to apply anywhere in the formula.
X
X! As a special feature, the normal @kbd{a r} command ignores @samp{select( )}
X! calls in rewrite rules. For example, if you used the above rule
X! @samp{[select(a)^x, select(a)]} with @kbd{a r}, it would apply the
X! rule as if it were @samp{[a^x, a]}. Thus, you can write general
X purpose rules that include @samp{select( )} hints inside them so
X that they will ``do the right thing'' in both @kbd{a r} and @kbd{j r},
X both with and without selections.
X--- 13433,13442 ----
X markers are ignored by the rewrite mechanism and the rules are allowed
X to apply anywhere in the formula.
X
X! As a special feature, the normal @kbd{a r} command also ignores
X! @samp{select( )} calls in rewrite rules. For example, if you used the
X! above rule @samp{[select(a)^x, select(a)]} with @kbd{a r}, it would apply
X! the rule as if it were @samp{[a^x, a]}. Thus, you can write general
X purpose rules that include @samp{select( )} hints inside them so
X that they will ``do the right thing'' in both @kbd{a r} and @kbd{j r},
X both with and without selections.
X***************
X*** 12690,12698 ****
X For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])}
X will return @samp{[x+y, x-y, x+y+z]}.
X
X- The @code{import} mechanism is not available for pattern sets.
X Conditional patterns must use the @code{condition} pseudo-function
X discussed above (@pxref{Other Features of Rewrite Rules}).
X
X The @kbd{a m} command does not provide you with any information about
X which meta-variables in the pattern matched which parts of the vector
X--- 13457,13465 ----
X For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])}
X will return @samp{[x+y, x-y, x+y+z]}.
X
X Conditional patterns must use the @code{condition} pseudo-function
X discussed above (@pxref{Other Features of Rewrite Rules}).
X+ The @code{import} mechanism is not available for pattern sets.
X
X The @kbd{a m} command does not provide you with any information about
X which meta-variables in the pattern matched which parts of the vector
X***************
X*** 12701,12708 ****
X [x, x+y, x-y, 7, x+y+z])} might produce the result @samp{[x, y, -y, 7, y+z]}.
X Note that it would not have worked to write @samp{map(rewrite, [a+b, b],
X [ @dots{} ])} because @code{map} would try to map pairwise across both
X! vectors; storing the rule in a variable would avoid this difficulty.
X! @xref{Reducing and Mapping}.
X
X The @kbd{a m} command can also be used to extract all vector elements
X which satisfy any condition: If the pattern is @samp{condition(x, x>0)}
X--- 13468,13475 ----
X [x, x+y, x-y, 7, x+y+z])} might produce the result @samp{[x, y, -y, 7, y+z]}.
X Note that it would not have worked to write @samp{map(rewrite, [a+b, b],
X [ @dots{} ])} because @code{map} would try to map pairwise across both
X! vectors; storing the rule in a variable would be another way to avoid
X! this difficulty. @xref{Reducing and Mapping}.
X
X The @kbd{a m} command can also be used to extract all vector elements
X which satisfy any condition: If the pattern is @samp{condition(x, x>0)}
X***************
X*** 13132,13138 ****
X The lowercase-@kbd{l} (@code{calc-let}) command evaluates a formula under
X a @emph{temporary} assignment of a variable. It stores the value on the
X top of the stack into the specified variable, then evaluates the
X! second-to-top stack entry, then restores the orginal value (or lack
X of one) in the variable. Thus after @kbd{' a+b^2 @key{RET} 3 l b @key{RET}},
X the stack will contain the formula @samp{a + 9}. The subsequent command
X @kbd{5 l a @key{RET}} will replace this formula with the number 14. The
X--- 13899,13905 ----
X The lowercase-@kbd{l} (@code{calc-let}) command evaluates a formula under
X a @emph{temporary} assignment of a variable. It stores the value on the
X top of the stack into the specified variable, then evaluates the
X! second-to-top stack entry, then restores the original value (or lack
X of one) in the variable. Thus after @kbd{' a+b^2 @key{RET} 3 l b @key{RET}},
X the stack will contain the formula @samp{a + 9}. The subsequent command
X @kbd{5 l a @key{RET}} will replace this formula with the number 14. The
X***************
X*** 13225,13231 ****
X command works successfully, it does an automatic @kbd{M-x calc} to enter
X the Calculator buffer.
X
X! The @kbd{M-#} key with a negative prefix argument (@kbd{M-- M-#}) is
X equivalent to @code{calc-grab-region} (with no prefix argument).
X
X Each line of the grabbed area becomes a row of the matrix. The result
X--- 13992,13998 ----
X command works successfully, it does an automatic @kbd{M-x calc} to enter
X the Calculator buffer.
X
X! The @kbd{M-#} key with a prefix argument of -1 as in (@kbd{M-- M-#}) is
X equivalent to @code{calc-grab-region} (with no prefix argument).
X
X Each line of the grabbed area becomes a row of the matrix. The result
X***************
X*** 13902,13907 ****
X--- 14669,14680 ----
X Lisp, you may find keyboard macros to be an easier way to program the
X Calculator.
X
X+ This section first discusses ways to write commands, functions, or
X+ small programs to be executed inside of Calc. Then it discusses
X+ how to get your own separate programs to call Calc from the outside.
X+ Finally, there is a list of internal Calc functions and data structures
X+ for the true Lisp enthusiast.
X+
X @menu
X * Defining Functions::
X * Defining Simple Commands::
X***************
X*** 13908,13913 ****
X--- 14681,14688 ----
X * Defining Stack Commands::
X * Argument Qualifiers::
X * Example Definitions::
X+
X+ * Calling Calc from Your Programs::
X * Internals::
X @end menu
X
X***************
X*** 14355,14361 ****
X which performs the necessary checks and conversions before executing the
X body of the function.
X
X! @node Example Definitions, Internals, Argument Qualifiers, Lisp Definitions
X @subsection Example Definitions
X
X This section includes some Lisp programming examples on a larger scale.
X--- 15130,15136 ----
X which performs the necessary checks and conversions before executing the
X body of the function.
X
X! @node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions
X @subsection Example Definitions
X
X This section includes some Lisp programming examples on a larger scale.
X***************
X*** 14443,14452 ****
X when you know that your own use of the sine function will never encounter
X a large argument, a simpler program like the first one shown is fine.
X
X! @node Internals, , Example Definitions, Lisp Definitions
X @subsection Calculator Internals
X
X! This chapter describes the Lisp functions defined by the Calculator that
X may be of use to user-written Calculator programs (as described in the
X rest of this chapter). These functions are shown by their names as they
X conventionally appear in @code{defmath}. Their full Lisp names are
X--- 15218,15469 ----
X when you know that your own use of the sine function will never encounter
X a large argument, a simpler program like the first one shown is fine.
X
X! @node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions
X! @subsection Calling Calc from Your Lisp Programs
X!
X! The following section (@pxref{Internals}) gives a full description
X! of Calc's internal Lisp functions. It's not hard to call Calc from
X! inside your programs, but the number of these functions can be daunting.
X! So Calc provides one special ``programmer-friendly'' function called
X! @code{calc-eval} that can be made to do just about everything you
X! need. It's not as fast as the low-level Calc functions, but it's
X! much simpler to use!
X!
X! It may seem that @code{calc-eval} itself has a daunting number of
X! options, but they all stem from one simple operation.
X!
X! In its simplest manifestation, @samp{(calc-eval "1+2")} parses the
X! string @samp{"1+2"} as if it were a Calc algebraic entry and returns
X! the result formatted as a string: @samp{"3"}.
X!
X! Since @code{calc-eval} is on the list of recommended @code{autoload}
X! functions, you don't need to make any special preparations to load
X! Calc before calling @code{calc-eval} the first time. Calc will be
X! loaded and initialized for you.
X!
X! All the Calc modes that are currently in effect will be used when
X! evaluating the expression and formatting the result.
X!
X! @subsubsection Additional Arguments to @code{calc-eval}
X!
X! If the input string parses to a list of expressions, Calc returns
X! the results separated by @samp{", "}. You can specify a different
X! separator by giving a second string argument to @code{calc-eval}:
X! @samp{(calc-eval "1+2,3+4" ";")} returns @samp{"3;7"}.
X!
X! The ``separator'' can also be any of several Lisp symbols which
X! request other behaviors from @code{calc-eval}. These are discussed
X! one by one below.
X!
X! You can give additional arguments to be substituted for
X! @samp{$}, @samp{$$}, and so on in the main expression. For
X! example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the
X! expression @samp{"7/(1+1)"} to yield the result @samp{"3.5"}
X! (assuming Fraction mode is not in effect). Note the @code{nil}
X! used as a placeholder for the item-separator argument.
X!
X! @subsubsection Numbers Only
X!
X! Sometimes it is preferable to treat @samp{1 / 0} as an error
X! rather than returning a symbolic result. If you pass the symbol
X! @code{num} as the second argument to @code{calc-eval}, results
X! that are not constants are treated as errors. The error message
X! reported is the first @samp{calc-why} message if there is one,
X! or otherwise ``Number expected.''
X!
X! A result is ``constant'' if it is a number, vector, or other
X! object that does not include variables or function calls. If it
X! is a vector, the components must themselves be constants.
X!
X! @subsubsection Error Handling
X!
X! If @code{calc-eval} encounters an error, it returns a list containing
X! the character position of the error, plus a suitable message as a
X! string. Note that @samp{1 / 0} is @emph{not} an error by Calc's
X! standards; it simply returns the string @samp{"1 / 0"} which is the
X! division left in symbolic form. But @samp{(calc-eval "1/")} will
X! return the list @samp{(2 "Expected a number")}.
X!
X! If you bind the variable @code{calc-eval-error} to @code{t}
X! using a @code{let} form surrounding the call to @code{calc-eval},
X! errors instead call the Emacs @code{error} function which aborts
X! to the Emacs command loop with a beep and an error message.
X!
X! If you bind this variable to the symbol @code{string}, error messages
X! are returned as strings instead of lists. The character position is
X! ignored.
X!
X! As a courtesy to other Lisp code which may be using Calc, be sure
X! to bind @code{calc-eval-error} using @code{let} rather than changing
X! it permanently with @code{setq}.
X!
X! @subsubsection Default Modes
X!
X! If the first argument to @code{calc-eval} is a list whose first
X! element is a formula string, then @code{calc-eval} sets all the
X! various Calc modes to their default values while the formula is
X! evaluated and formatted. For example, the precision is set to 12
X! digits, digit grouping is turned off, and the normal language
X! mode is used.
X!
X! This same principle applies to the other options discussed below.
X! If the first argument would normally be @var{x}, then it can also
X! be the list @samp{(@var{x})} to use the default mode settings.
X!
X! If there are other elements in the list, they are taken as
X! variable-name/value pairs which override the default mode
X! settings. Look at the documentation at the front of the
X! @file{calc.el} file to find the names of the Lisp variables for
X! the various modes. The mode settings are restored to their
X! original values when @code{calc-eval} is done.
X!
X! For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)}
X! computes the sum of two numbers, requiring a numeric result, and
X! using default mode settings except that the precision is 8 instead
X! of the default of 12.
X!
X! It's usually best to use the form of @code{calc-eval} unless your
X! program actually considers the interaction with Calc's mode settings
X! to be a feature. This will avoid all sorts of potential ``gotchas'';
X! consider what happens with @samp{(calc-eval "sqrt(2)" 'num)}
X! when the user has left Calc in symbolic mode or no-simplify mode.
X!
X! As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")}
X! checks if the number in string @samp{a} is less than the one in
X! string @samp{b}. Without using a list, the integer 1 might
X! come out in a variety of formats which would be hard to test for
X! conveniently: @samp{"1"}, @samp{"8#1"}, @samp{"00001"}.
X!
X! @subsubsection Raw Numbers
X!
X! Normally all input and output for @code{calc-eval} is done with strings.
X! You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)}
X! in place of @samp{(+ a b)}, but this is very inefficient since the
X! numbers must be converted to and from string format as they are passed
X! from one @code{calc-eval} to the next.
X!
X! If the separator is the symbol @code{raw}, the result will be returned
X! as a raw Calc data structure rather than a string. You can read about
X! how these objects look in the following sections, but usually you can
X! treat them as ``black box'' objects with no important internal
X! structure.
X!
X! Another way to do a reliable ``less-than'' test would be
X! @samp{(eq (calc-eval "$<$$" 'raw a b) 1)}, relying on our knowledge
X! that Calc represents small integers like 1 as plain Lisp integers.
X!
X! There is also a @code{rawnum} symbol, which is a combination of
X! @code{raw} (returning a raw Calc object) and @code{num} (signalling
X! an error if that object is not a constant).
X!
X! You can pass a raw Calc object to @code{calc-eval} in place of a
X! string, either as the formula itself or as one of the @samp{$}
X! arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an
X! addition function that operates on raw Calc objects. Of course
X! in this case it would be easier to call the low-level @code{math-add}
X! function in Calc, if you can remember its name.
X!
X! When it comes time to display the object, just use @samp{(calc-eval a)}
X! to format it as a string.
X!
X! It is an error if the input expression evaluates to a list of
X! values. The separator symbol @code{list} is like @code{raw}
X! except that it returns a list of one or more raw Calc objects.
X!
X! Note that a Lisp string is not a valid Calc object, nor is a list
X! containing a string. Thus you can still safely distinguish all the
X! various kinds of error returns discussed above.
X!
X! @subsubsection Stack Access
X!
X! If the separator symbol is @code{push}, the formula argument is
X! evaluated (with possible @samp{$} expansions, as usual). The
X! result is pushed onto the Calc stack. The return value is @code{nil}
X! (unless there is an error from evaluating the formula).
X!
X! If the separator symbol is @code{pop}, the first argument to
X! @code{calc-eval} must be an integer instead of a string. That
X! many values are popped from the stack and thrown away. A negative
X! argument deletes the entry at that stack level. The return value
X! is the number of elements remaining in the stack after popping;
X! @samp{(calc-eval 0 'pop)} is a good way to measure the size of
X! the stack.
X!
X! If the separator symbol is @code{top}, the first argument to
X! @code{calc-eval} must again be an integer. The value at that
X! stack level is formatted as a string and returned. If the
X! integer is out of range, @code{nil} is returned.
X!
X! The separator symbol @code{rawtop} is just like @code{top} except
X! that the stack entry is returned as a raw Calc object instead of
X! as a string.
X!
X! In all of these cases the first argument can be made a list in
X! order to force the default mode settings, as described above.
X! Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the
X! second-to-top stack entry, formatted as a string using the default
X! instead of current display modes, except that the radix is
X! hexadecimal instead of decimal.
X!
X! It is, of course, polite to put the Calc stack back the way you
X! found it when you are done, unless the user of your program is
X! actually expecting it to affect the stack.
X!
X! @subsubsection Keyboard Macros
X!
X! If the separator symbol is @code{macro}, the first argument must be a
X! string of characters which Calc executes as a sequence of keystroke.
X! This switches into the Calc buffer for the duration of the macro.
X! For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the
X! vector @samp{[1,2,3,4,5]} on the stack and then replaces it
X! with the sum of those numbers. Note that @samp{\r} is the Lisp
X! notation for the carriage-return character.
X!
X! If your keyboard macro wishes to pop the stack, @samp{\C-d} is
X! safer than @samp{\177} (the @key{DEL} character) because some
X! installations may have switched the meanings of @key{DEL} and
X! @kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for
X! ``pop-stack'' regardless of key mapping.
X!
X! If you provide a third argument to @code{calc-eval}, evaluation
X! of the keyboard macro will leave a record in the Trail using
X! that argument as a tag string. Normally the Trail is unaffected.
X!
X! The return value in this case is always @code{nil}.
X!
X! @subsubsection Lisp Evaluation
X!
X! Finally, if the separator symbol is @code{eval}, then the Lisp
X! @code{eval} function is called on the first argument, which must
X! be a Lisp expression rather than a Calc formula. Remember to
X! quote the expression so that it is not evaluated until inside
X! @code{calc-eval}.
X!
X! The difference from plain @code{eval} is that @code{calc-eval}
X! switches to the Calc buffer before evaluating the expression.
X! For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)}
X! will correctly affect the buffer-local Calc precision variable.
X!
X! An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}.
X! This is evaluating a call to the function that is normally invoked
X! by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.''
X! Note that this function will leave a message in the echo area as
X! a side effect. Also, all Calc functions switch to the Calc buffer
X! automatically if not invoked from there, so the above call is
X! also equivalent to @samp{(calc-precision 17)} by itself.
X! In all cases, Calc uses @code{save-excursion} to switch back to
X! your original buffer when it is done.
X!
X! As usual the first argument can be a list that begins with a Lisp
X! expression to use default instead of current mode settings.
X!
X! The result of @code{calc-eval} in this usage is just the result
X! returned by the evaluated Lisp expression.
X!
X! @node Internals, , Calling Calc from Your Programs, Lisp Definitions
X @subsection Calculator Internals
X
X! This section describes the Lisp functions defined by the Calculator that
X may be of use to user-written Calculator programs (as described in the
X rest of this chapter). These functions are shown by their names as they
X conventionally appear in @code{defmath}. Their full Lisp names are
X***************
X*** 15073,15079 ****
X equal except possibly in the last decimal place. For example,
X 314.159 and 314.166 are considered nearly equal if the current
X precision is 6 (since they differ by 7 units), but not if the current
X! precision is 7 (since they differ by 70 units). Most functions which
X use series expansions use @code{with-extra-prec} to evaluate the
X series with 2 extra digits of precision, then use @code{nearly-equal}
X to decide when the series has converged; this guards against cumulative
X--- 16090,16096 ----
X equal except possibly in the last decimal place. For example,
X 314.159 and 314.166 are considered nearly equal if the current
X precision is 6 (since they differ by 7 units), but not if the current
X! precision is 7 (since they differ by 70 units). Most functions which
X use series expansions use @code{with-extra-prec} to evaluate the
X series with 2 extra digits of precision, then use @code{nearly-equal}
X to decide when the series has converged; this guards against cumulative
X***************
X*** 15080,15086 ****
X error in the series evaluation without doing extra work which would be
X lost when the result is rounded back down to the current precision.
X In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
X! @var{X} and @var{y} can be numbers of any time, including complex.
X @end defun
X
X @defun nearly-zerop x y
X--- 16097,16103 ----
X error in the series evaluation without doing extra work which would be
X lost when the result is rounded back down to the current precision.
X In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}.
X! @var{X} and @var{y} can be numbers of any kind, including complex.
X @end defun
X
X @defun nearly-zerop x y
X***************
X*** 16122,16140 ****
X
X @defun calc-eval str sep arg1 arg2 @dots{}
X This is the simplest interface to the Calculator from another Lisp program.
X! The algebraic expression(s) in @var{str} are parsed and evaluated; the
X! results are formatted as a string and returned. If @var{str} contains
X! several expressions the results are separated by string @var{sep}, or
X! by the string @samp{", "} if @var{sep} is omitted. If any additional
X! arguments are given, they are values (in Calc's internal format) to be
X! used for @kbd{$}, @kbd{$$}, and so on in the string.
X!
X! If the string @var{str} contains an error, the return value is instead
X! a list of two items: An integer index into @var{str} to show the
X! approximate position of the error, and an explanatory message string.
X!
X! This function uses the mode settings in the @code{*Calculator*} buffer.
X! If no such buffer exists, it will be created as a side-effect.
X @end defun
X
X @defun read-number str
X--- 17139,17145 ----
X
X @defun calc-eval str sep arg1 arg2 @dots{}
X This is the simplest interface to the Calculator from another Lisp program.
X! @xref{Calling Calc from Your Programs}.
X @end defun
X
X @defun read-number str
X***************
X*** 16400,16406 ****
X @node Installation, Reporting Bugs, Programming, Top
X @chapter Installation
X
X! Calc 1.05 comes as a pair of Emacs Lisp files, generally called
X @file{calc.el} and @file{calc-ext.el}. The first contains the basic
X foundations of the Calculator, and is as small as possible to promote
X quick loading. The second contains all the more advanced commands and
X--- 17405,17411 ----
X @node Installation, Reporting Bugs, Programming, Top
X @chapter Installation
X
X! Calc 1.06 comes as a pair of Emacs Lisp files, generally called
X @file{calc.el} and @file{calc-ext.el}. The first contains the basic
X foundations of the Calculator, and is as small as possible to promote
X quick loading. The second contains all the more advanced commands and
X***************
X*** 16487,16492 ****
X--- 17492,17498 ----
X (autoload 'calc-extensions ".../calc-ext.elc" nil)
X (autoload 'quick-calc ".../calc.elc" "Quick Calculator" t)
X (autoload 'full-calc ".../calc.elc" "Full-screen Calculator" t)
X+ (autoload 'calc-keypad ".../calc.elc" "X windows Calculator" t)
X (autoload 'calc-eval ".../calc.elc" "Use Calculator from Lisp")
X (autoload 'calc-grab-region ".../calc-ext.elc" nil t)
X (autoload 'defmath ".../calc-ext.elc" nil t t)
X***************
X*** 16505,16511 ****
X brings in the extensions module; Calc takes care to call the
X @code{calc-extensions} function (which doesn't actually do anything)
X before any operation that requires the extensions to be present.
X! The other five @code{autoload} commands are for functions which might
X reasonably be used before the user has typed @kbd{M-x calc} for the
X first time.
X
X--- 17511,17517 ----
X brings in the extensions module; Calc takes care to call the
X @code{calc-extensions} function (which doesn't actually do anything)
X before any operation that requires the extensions to be present.
X! The other six @code{autoload} commands are for functions which might
X reasonably be used before the user has typed @kbd{M-x calc} for the
X first time.
X
XFiles macedit.el and ../dist/macedit.el are identical
SHAR_EOF
chmod 0666 calc.patch || echo "restore of calc.patch fails"
rm -f s2_seq_.tmp
echo "You have unpacked the last part"
exit 0
--
Dave Gillespie
256-80 Caltech Pasadena CA USA 91125
daveg@csvax.cs.caltech.edu, ...!cit-vax!daveg