home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume24 / gnucalc / part54 < prev    next >
Encoding:
Text File  |  1991-11-02  |  55.5 KB  |  1,331 lines

  1. Newsgroups: comp.sources.misc
  2. From: daveg@synaptics.com (David Gillespie)
  3. Subject:  v24i102:  gnucalc - GNU Emacs Calculator, v2.00, Part54/56
  4. Message-ID: <1991Nov3.001134.20001@sparky.imd.sterling.com>
  5. X-Md4-Signature: 4abe2a5e4dc99be4212ce72aa5ac3ba0
  6. Date: Sun, 3 Nov 1991 00:11:34 GMT
  7. Approved: kent@sparky.imd.sterling.com
  8.  
  9. Submitted-by: daveg@synaptics.com (David Gillespie)
  10. Posting-number: Volume 24, Issue 102
  11. Archive-name: gnucalc/part54
  12. Environment: Emacs
  13. Supersedes: gmcalc: Volume 13, Issue 27-45
  14.  
  15. #!/bin/sh
  16. # do not concatenate these parts, unpack them in order with /bin/sh
  17. # file calc.texinfo continued
  18. #
  19. if test ! -r _shar_seq_.tmp; then
  20.     echo 'Please unpack part 1 first!'
  21.     exit 1
  22. fi
  23. (read Scheck
  24.  if test "$Scheck" != 54; then
  25.     echo Please unpack part "$Scheck" next!
  26.     exit 1
  27.  else
  28.     exit 0
  29.  fi
  30. ) < _shar_seq_.tmp || exit 1
  31. if test ! -f _shar_wnt_.tmp; then
  32.     echo 'x - still skipping calc.texinfo'
  33. else
  34. echo 'x - continuing file calc.texinfo'
  35. sed 's/^X//' << 'SHAR_EOF' >> 'calc.texinfo' &&
  36. Convert the HMS form @var{a} into a real number.  If @var{ang} is specified,
  37. it is the angular mode in which to express the result, otherwise the
  38. current angular mode is used.  If @var{a} is already a real number, it
  39. is returned as-is.
  40. @end defun
  41. X
  42. @defun to-radians a
  43. Convert the number or HMS form @var{a} to radians from the current
  44. angular mode.
  45. @end defun
  46. X
  47. @defun from-radians a
  48. Convert the number @var{a} from radians to the current angular mode.
  49. If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}.
  50. @end defun
  51. X
  52. @defun to-radians-2 a
  53. Like @code{to-radians}, except that in Symbolic Mode a degrees to
  54. radians conversion yields a formula like @samp{@var{a}*pi/180}.
  55. @end defun
  56. X
  57. @defun from-radians-2 a
  58. Like @code{from-radians}, except that in Symbolic Mode a radians to
  59. degrees conversion yields a formula like @samp{@var{a}*180/pi}.
  60. @end defun
  61. X
  62. @defun random-digit
  63. Produce a random base-1000 digit in the range 0 to 999.
  64. @end defun
  65. X
  66. @defun random-digits n
  67. Produce a random @var{n}-digit integer; this will be an integer
  68. in the interval @samp{[0, 10^@var{n})}.
  69. @end defun
  70. X
  71. @defun random-float
  72. Produce a random float in the interval @samp{[0, 1)}.
  73. @end defun
  74. X
  75. @defun prime-test n iters
  76. Determine whether the integer @var{n} is prime.  Return a list which has
  77. one of these forms: @samp{(nil @var{f})} means the number is non-prime
  78. because it was found to be divisible by @var{f}; @samp{(nil)} means it
  79. was found to be non-prime by table look-up (so no factors are known);
  80. @samp{(nil unknown)} means it is definitely non-prime but no factors
  81. are known because @var{n} was large enough that Fermat's probabilistic
  82. test had to be used; @samp{(t)} means the number is definitely prime;
  83. and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i}
  84. iterations, is @var{p} percent sure that the number is prime.  The
  85. @var{iters} parameter is the number of Fermat iterations to use, in the
  86. case that this is necessary.  If @code{prime-test} returns ``maybe,''
  87. you can call it again with the same @var{n} to get a greater certainty;
  88. @code{prime-test} remembers where it left off.@refill
  89. @end defun
  90. X
  91. @defun to-simple-fraction f
  92. If @var{f} is a floating-point number which can be represented exactly
  93. as a small rational number. return that number, else return @var{f}.
  94. For example, 0.75 would be converted to 3:4.  This function is very
  95. fast.
  96. @end defun
  97. X
  98. @defun to-fraction f tol
  99. Find a rational approximation to floating-point number @var{f} to within
  100. a specified tolerance @var{tol}; this corresponds to the algebraic
  101. function @code{frac}, and can be rather slow.
  102. @end defun
  103. X
  104. @node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals
  105. @subsubsection Vector Functions
  106. X
  107. @noindent
  108. The functions described here perform various operations on vectors and
  109. matrices.
  110. X
  111. @defun math-concat x y
  112. Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}}
  113. in a symbolic formula.  @xref{Building Vectors}.
  114. @end defun
  115. X
  116. @defun vec-length v
  117. Return the length of vector @var{v}.  If @var{v} is not a vector, the
  118. result is zero.  If @var{v} is a matrix, this returns the number of
  119. rows in the matrix.
  120. @end defun
  121. X
  122. @defun mat-dimens m
  123. Determine the dimensions of vector or matrix @var{m}.  If @var{m} is not
  124. a vector, the result is an empty list.  If @var{m} is a plain vector
  125. but not a matrix, the result is a one-element list containing the length
  126. of the vector.  If @var{m} is a matrix with @var{r} rows and @var{c} columns,
  127. the result is the list @samp{(@var{r} @var{c})}.  Higher-order tensors
  128. produce lists of more than two dimensions.  Note that the object
  129. @samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size,
  130. and is treated by this and other Calc routines as a plain vector of two
  131. elements.@refill
  132. @end defun
  133. X
  134. @defun dimension-error
  135. Abort the current function with a message of ``Dimension error.''
  136. The Calculator will leave the function being evaluated in symbolic
  137. form; this is really just a special case of @code{reject-arg}.
  138. @end defun
  139. X
  140. @defun build-vector args
  141. Return a Calc vector with the zero-or-more @var{args} as elements.
  142. For example, @samp{(build-vector 1 2 3)} returns the Calc vector
  143. @samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}.
  144. @end defun
  145. X
  146. @defun make-vec obj dims
  147. Return a Calc vector or matrix all of whose elements are equal to
  148. @var{obj}.  For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix
  149. filled with 27's.
  150. @end defun
  151. X
  152. @defun row-matrix v
  153. If @var{v} is a plain vector, convert it into a row matrix, i.e.,
  154. a matrix whose single row is @var{v}.  If @var{v} is already a matrix,
  155. leave it alone.
  156. @end defun
  157. X
  158. @defun col-matrix v
  159. If @var{v} is a plain vector, convert it into a column matrix, i.e., a
  160. matrix with each element of @var{v} as a separate row.  If @var{v} is
  161. already a matrix, leave it alone.
  162. @end defun
  163. X
  164. @defun map-vec f v
  165. Map the Lisp function @var{f} over the Calc vector @var{v}.  For example,
  166. @samp{(map-vec 'math-floor v)} returns a vector of the floored components
  167. of vector @var{v}.
  168. @end defun
  169. X
  170. @defun map-vec-2 f a b
  171. Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}.
  172. If @var{a} and @var{b} are vectors of equal length, the result is a
  173. vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})}
  174. for each pair of elements @var{ai} and @var{bi}.  If either @var{a} or
  175. @var{b} is a scalar, it is matched with each value of the other vector.
  176. For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v}
  177. with each element increased by one.  Note that using @samp{'+} would not
  178. work here, since @code{defmath} does not expand function names everywhere,
  179. just where they are in the function position of a Lisp expression.@refill
  180. @end defun
  181. X
  182. @defun reduce-vec f v
  183. Reduce the function @var{f} over the vector @var{v}.  For example, if
  184. @var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}.
  185. If @var{v} is a matrix, this reduces over the rows of @var{v}.
  186. @end defun
  187. X
  188. @defun reduce-cols f m
  189. Reduce the function @var{f} over the columns of matrix @var{m}.  For
  190. example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result
  191. is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}.
  192. @end defun
  193. X
  194. @defun mat-row m n
  195. Return the @var{n}th row of matrix @var{m}.  This is equivalent to
  196. @samp{(elt m n)}.  For a slower but safer version, use @code{mrow}.
  197. (@xref{Extracting Elements}.)
  198. @end defun
  199. X
  200. @defun mat-col m n
  201. Return the @var{n}th column of matrix @var{m}, in the form of a vector.
  202. The arguments are not checked for correctness.
  203. @end defun
  204. X
  205. @defun mat-less-row m n
  206. Return a copy of matrix @var{m} with its @var{n}th row deleted.  The
  207. number @var{n} must be in range from 1 to the number of rows in @var{m}.
  208. @end defun
  209. X
  210. @defun mat-less-col m n
  211. Return a copy of matrix @var{m} with its @var{n}th column deleted.
  212. @end defun
  213. X
  214. @defun transpose m
  215. Return the transpose of matrix @var{m}.
  216. @end defun
  217. X
  218. @defun flatten-vector v
  219. Flatten nested vector @var{v} into a vector of scalars.  For example,
  220. if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}.
  221. @end defun
  222. X
  223. @defun copy-matrix m
  224. If @var{m} is a matrix, return a copy of @var{m}.  This maps
  225. @code{copy-sequence} over the rows of @var{m}; in Lisp terms, each
  226. element of the result matrix will be @code{eq} to the corresponding
  227. element of @var{m}, but none of the @code{cons} cells that make up
  228. the structure of the matrix will be @code{eq}.  If @var{m} is a plain
  229. vector, this is the same as @code{copy-sequence}.@refill
  230. @end defun
  231. X
  232. @defun swap-rows m r1 r2
  233. Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place.  In
  234. other words, unlike most of the other functions described here, this
  235. function changes @var{m} itself rather than building up a new result
  236. matrix.  The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)}
  237. is true, with the side effect of exchanging the first two rows of
  238. @var{m}.@refill
  239. @end defun
  240. X
  241. @node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals
  242. @subsubsection Symbolic Functions
  243. X
  244. @noindent
  245. The functions described here operate on symbolic formulas in the
  246. Calculator.
  247. X
  248. @defun calc-prepare-selection num
  249. Prepare a stack entry for selection operations.  If @var{num} is
  250. omitted, the stack entry containing the cursor is used; otherwise,
  251. it is the number of the stack entry to use.  This function stores
  252. useful information about the current stack entry into a set of
  253. variables.  @code{calc-selection-cache-num} contains the number of
  254. the stack entry involved (equal to @var{num} if you specified it);
  255. @code{calc-selection-cache-entry} contains the stack entry as a
  256. list (such as @code{calc-top-list} would return with @code{entry}
  257. as the selection mode); and @code{calc-selection-cache-comp} contains
  258. a special ``tagged'' composition (@pxref{Formatting Lisp Functions})
  259. which allows Calc to relate cursor positions in the buffer with
  260. their corresponding sub-formulas.
  261. X
  262. A slight complication arises in the selection mechanism because
  263. formulas may contain small integers.  For example, in the vector
  264. @samp{[1, 2, 1]} the first and last elements are @code{eq} to each
  265. other; selections are recorded as the actual Lisp object that
  266. appears somewhere in the tree of the whole formula, but storing
  267. @code{1} would falsely select both @code{1}'s in the vector.  So
  268. @code{calc-prepare-selection} also checks the stack entry and
  269. replaces any plain integers with ``complex number'' lists of the form
  270. @samp{(cplx @var{n} 0)}.  This list will be displayed the same as a
  271. plain @var{n} and the change will be completely invisible to the
  272. user, but it will guarantee that no two sub-formulas of the stack
  273. entry will be @code{eq} to each other.  Next time the stack entry
  274. is involved in a computation, @code{calc-normalize} will replace
  275. these lists with plain numbers again, again invisibly to the user.
  276. @end defun
  277. X
  278. @defun calc-find-selected-part
  279. Find the smallest sub-formula of the current formula that contains
  280. the cursor.  This assumes @code{calc-prepare-selection} has been
  281. called already.  If the cursor is not actually on any part of the
  282. formula, this returns @code{nil}.
  283. @end defun
  284. X
  285. @defun calc-change-current-selection selection
  286. Change the currently prepared stack element's selection to
  287. @var{selection}, which should be @code{eq} to some sub-formula
  288. of the stack element, or @code{nil} to unselect the formula.
  289. The stack element's appearance in the Calc buffer is adjusted
  290. to reflect the new selection.
  291. @end defun
  292. X
  293. @defun calc-find-nth-part expr n
  294. Return the @var{n}th sub-formula of @var{expr}.  This function is used
  295. by the selection commands, and (unless @kbd{j b} has been used) treats
  296. sums and products as flat many-element formulas.  Thus if @var{expr}
  297. is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with
  298. @var{n} equal to four will return @samp{d}.
  299. @end defun
  300. X
  301. @defun calc-find-parent-formula expr part
  302. Return the sub-formula of @var{expr} which immediately contains
  303. @var{part}.  If @var{expr} is @samp{a*b + (c+1)*d} and @var{part}
  304. is @code{eq} to the @samp{c+1} term of @var{expr}, then this function
  305. will return @samp{(c+1)*d}.  If @var{part} turns out not to be a
  306. sub-formula of @var{expr}, the function returns @code{nil}.  If
  307. @var{part} is @code{eq} to @var{expr}, the function returns @code{t}.
  308. This function does not take associativity into account.
  309. @end defun
  310. X
  311. @defun calc-find-assoc-parent-formula expr part
  312. This is the same as @code{calc-find-parent-formula}, except that
  313. (unless @kbd{j b} has been used) it continues widening the selection
  314. to contain a complete level of the formula.  Given @samp{a} from
  315. @samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will
  316. return @samp{a + b} but @code{calc-find-assoc-parent-formula} will
  317. return the whole expression.
  318. @end defun
  319. X
  320. @defun calc-grow-assoc-formula expr part
  321. This expands sub-formula @var{part} of @var{expr} to encompass a
  322. complete level of the formula.  If @var{part} and its immediate
  323. parent are not compatible associative operators, or if @kbd{j b}
  324. has been used, this simply returns @var{part}.
  325. @end defun
  326. X
  327. @defun calc-find-sub-formula expr part
  328. This finds the immediate sub-formula of @var{expr} which contains
  329. @var{part}.  It returns an index @var{n} such that
  330. @samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}.
  331. If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}.
  332. If @var{part} is @code{eq} to @var{expr}, it returns @code{t}.  This
  333. function does not take associativity into account.
  334. @end defun
  335. X
  336. @defun calc-replace-sub-formula expr old new
  337. This function returns a copy of formula @var{expr}, with the
  338. sub-formula that is @code{eq} to @var{old} replaced by @var{new}.
  339. @end defun
  340. X
  341. @defun simplify expr
  342. Simplify the expression @var{expr} by applying various algebraic rules.
  343. This is what the @kbd{a s} (@code{calc-simplify}) command uses.  This
  344. always returns a copy of the expression; the structure @var{expr} points
  345. to remains unchanged in memory.
  346. X
  347. More precisely, here is what @code{simplify} does:  The expression is
  348. first normalized and evaluated by calling @code{normalize}.  Then
  349. the expression is traversed in a depth-first, bottom-up fashion; at
  350. each level, any simplifications that can be made are made until no
  351. further changes are possible.  Once the entire formula has been
  352. traversed in this way, it is compared with the original formula (from
  353. before the call to @code{normalize}) and, if it has changed,
  354. the entire procedure is repeated (starting with @code{normalize})
  355. until no further changes occur.  Usually only two iterations are
  356. needed: one to simplify the formula, and another to verify that no
  357. further simplifications were possible.
  358. @end defun
  359. X
  360. @defun simplify-extended expr
  361. Simplify the expression @var{expr}, with additional rules enabled that
  362. help do a more thorough job, while not being entirely ``safe'' in all
  363. circumstances.  (For example, this mode will simplify @samp{sqrt(x^2)}
  364. to @samp{x}, which is only valid when @var{x} is positive.)  This is
  365. implemented by temporarily binding the variable @code{math-living-dangerously}
  366. to @code{t} (using a @code{let} form) and calling @code{simplify}.
  367. Dangerous simplification rules are written to check this variable
  368. before taking any action.@refill
  369. @end defun
  370. X
  371. @defun simplify-units expr
  372. Simplify the expression @var{expr}, treating variable names as units
  373. whenever possible.  This works by binding the variable
  374. @code{math-simplifying-units} to @code{t} while calling @code{simplify}.
  375. @end defun
  376. X
  377. @defmac math-defsimplify funcs body
  378. Register a new simplification rule; this is normally called as a top-level
  379. form, like @code{defun} or @code{defmath}.  If @var{funcs} is a symbol
  380. (like @code{+} or @code{calcFunc-sqrt}), this simplification rule is
  381. applied to the formulas which are calls to the specified function.  Or,
  382. @var{funcs} can be a list of such symbols; the rule applies to all
  383. functions on the list.  The @var{body} is written like the body of a
  384. function with a single argument called @code{expr}.  The body will be
  385. executed with @code{expr} bound to a formula which is a call to one of
  386. the functions @var{funcs}.  If the function body returns @code{nil}, or
  387. if it returns a result @code{equal} to the original @code{expr}, it is
  388. ignored and Calc goes on to try the next simplification rule that applies.
  389. If the function body returns something different, that new formula is
  390. substituted for @var{expr} in the original formula.@refill
  391. X
  392. At each point in the formula, rules are tried in the order of the
  393. original calls to @code{math-defsimplify}; the search stops after the
  394. first rule that makes a change.  Thus later rules for that same
  395. function will not have a chance to trigger until the next iteration
  396. of the main @code{simplify} loop.
  397. X
  398. Note that, since @code{defmath} is not being used here, @var{body} must
  399. be written in true Lisp code without the conveniences that @code{defmath}
  400. provides.  If you prefer, you can have @var{body} simply call another
  401. function (defined with @code{defmath}) which does the real work.
  402. X
  403. The arguments of a function call will already have been simplified
  404. before any rules for the call itself are invoked.  Since a new argument
  405. list is consed up when this happens, this means that the rule's body is
  406. allowed to rearrange the function's arguments destructively if that is
  407. convenient.  Here is a typical example of a simplification rule:
  408. X
  409. @smallexample
  410. (math-defsimplify calcFunc-arcsinh
  411. X  (or (and (math-looks-negp (nth 1 expr))
  412. X           (math-neg (list 'calcFunc-arcsinh (math-neg (nth 1 expr)))))
  413. X      (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh)
  414. X           (or math-living-dangerously
  415. X               (math-known-realp (nth 1 (nth 1 expr))))
  416. X           (nth 1 (nth 1 expr)))))
  417. @end smallexample
  418. X
  419. This is really a pair of rules written with one @code{math-defsimplify}
  420. for convenience; the first replaces @samp{arcsinh(-x)} with
  421. @samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x},
  422. replaces @samp{arcsinh(sinh(x))} with @samp{x}.@refill
  423. @end defmac
  424. X
  425. @defun common-constant-factor expr
  426. Check @var{expr} to see if it is a sum of terms all multiplied by the
  427. same rational value.  If so, return this value.  If not, return @code{nil}.
  428. For example, if called on @samp{6x + 9y + 12z}, it would return 3, since
  429. 3 is a common factor of all the terms.
  430. @end defun
  431. X
  432. @defun cancel-common-factor expr factor
  433. Assuming @var{expr} is a sum with @var{factor} as a common factor,
  434. divide each term of the sum by @var{factor}.  This is done by
  435. destructively modifying parts of @var{expr}, on the assumption that
  436. it is being used by a simplification rule (where such things are
  437. allowed; see above).  For example, consider this built-in rule for
  438. square roots:
  439. X
  440. @smallexample
  441. (math-defsimplify calcFunc-sqrt
  442. X  (let ((fac (math-common-constant-factor (nth 1 expr))))
  443. X    (and fac
  444. X         (math-mul (list 'calcFunc-sqrt fac)
  445. X                   (list 'calcFunc-sqrt
  446. X                         (math-cancel-common-factor
  447. X                          (nth 1 expr) fac))))))
  448. @end smallexample
  449. @end defun
  450. X
  451. @defun frac-gcd a b
  452. Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be
  453. rational numbers.  This is the fraction composed of the GCD of the
  454. numerators of @var{a} and @var{b}, over the GCD of the denominators.
  455. It is used by @code{common-constant-factor}.@refill
  456. @end defun
  457. X
  458. @defun map-tree func expr many
  459. Try applying Lisp function @var{func} to various sub-expressions of
  460. @var{expr}.  Initially, call @var{func} with @var{expr} itself as an
  461. argument.  If this returns an expression which is not @code{equal} to
  462. @var{expr}, apply @var{func} again until eventually it does return
  463. @var{expr} with no changes.  Then, if @var{expr} is a function call,
  464. recursively apply @var{func} to each of the arguments.  This keeps going
  465. until no changes occur anywhere in the expression; this final expression
  466. is returned by @code{map-tree}.  Note that, unlike simplification rules,
  467. @var{func} functions may @emph{not} make destructive changes to
  468. @var{expr}.  If a third argument @var{many} is provided, it is an
  469. integer which says how many times @var{func} may be applied; the
  470. default, as described above, is infinitely many times.@refill
  471. @end defun
  472. X
  473. @defun compile-rewrites rules
  474. Compile the rewrite rule set specified by @var{rules}, which should
  475. be a formula that is either a vector or a variable name.  If the latter,
  476. the compiled rules are saved so that later @code{compile-rules} calls
  477. for that same variable can return immediately.  If there are problems
  478. with the rules, this function calls @code{error} with a suitable
  479. message.
  480. @end defun
  481. X
  482. @defun apply-rewrites expr crules heads
  483. Apply the compiled rewrite rule set @var{crules} to the expression
  484. @var{expr}.  This will make only one rewrite and only checks at the
  485. top level of the expression.  The result @code{nil} if no rules
  486. matched, or if the only rules that matched did not actually change
  487. the expression.  The @var{heads} argument is optional; if is given,
  488. it should be a list of all function names that (may) appear in
  489. @var{expr}.  The rewrite compiler tags each rule with the
  490. rarest-looking function name in the rule; if you specify @var{heads},
  491. @code{apply-rewrites} can use this information to narrow its search
  492. down to just a few rules in the rule set.
  493. @end defun
  494. X
  495. @defun rewrite-heads expr
  496. Compute a @var{heads} list for @var{expr} suitable for use with
  497. @code{apply-rewrites}, as discussed above.
  498. @end defun
  499. X
  500. @defun rewrite expr rules many
  501. This is an all-in-one rewrite function.  It compiles the rule set
  502. specified by @var{rules}, then uses @code{map-tree} to apply the
  503. rules throughout @var{expr} up to @var{many} (default infinity)
  504. times.
  505. @end defun
  506. X
  507. @defun match-patterns pat vec not-flag
  508. Given a Calc vector @var{vec} and an uncompiled pattern set or
  509. pattern set variable @var{pat}, this function returns a new vector
  510. of all elements of @var{vec} which do (or don't, if @var{not-flag} is
  511. non-@code{nil}) match any of the patterns in @var{pat}.
  512. @end defun
  513. X
  514. @defun deriv expr var value symb
  515. Compute the derivative of @var{expr} with respect to variable @var{var}
  516. (which may actually be any sub-expression).  If @var{value} is specified,
  517. the derivative is evaluated at the value of @var{var}; otherwise, the
  518. derivative is left in terms of @var{var}.  If the expression contains
  519. functions for which no derivative formula is known, new derivative
  520. functions are invented by adding primes to the names; @pxref{Calculus}.
  521. However, if @var{symb} is non-@code{nil}, the presence of undifferentiable
  522. functions in @var{expr} instead cancels the whole differentiation, and
  523. @code{deriv} returns @code{nil} instead.
  524. X
  525. Derivatives of a one-argument function can be defined by
  526. adding a @code{math-derivative-@var{n}} property to the property list
  527. of the symbol for the function's derivative, which will be the
  528. function name followed by an apostrophe.  Here @var{n} is the number
  529. of arguments to the function.  The value of the property should be a
  530. Lisp function; it is called with the same arguments as the original
  531. function call that is being differentiated.  It should return a formula
  532. for the derivative.  For example, the derivative of @code{ln} is defined by
  533. X
  534. @smallexample
  535. (put 'calcFunc-ln\' 'math-derivative-1
  536. X     (function (lambda (u) (math-div 1 u))))
  537. @end smallexample
  538. X
  539. The two-argument @code{log} function has two derivatives,
  540. @smallexample
  541. (put 'calcFunc-log\' 'math-derivative-2     ; d(log(x,b)) / dx
  542. X     ... )
  543. (put 'calcFunc-log\'2 'math-derivative-2    ; d(log(x,b)) / db
  544. X     ... )
  545. @end smallexample
  546. @end defun
  547. X
  548. @defun tderiv expr var value symb
  549. Compute the total derivative of @var{expr}.  This is the same as
  550. @code{deriv}, except that variables other than @var{var} are not
  551. assumed to be constant with respect to @var{var}.
  552. @end defun
  553. X
  554. @defun integ expr var low high
  555. Compute the integral of @var{expr} with respect to @var{var}.
  556. @xref{Calculus}, for further details.
  557. @end defun
  558. X
  559. @defmac math-defintegral funcs body
  560. Define a rule for integrating a function or functions of one argument;
  561. this macro is very similar in format to @code{math-defsimplify}.
  562. The main difference is that here @var{body} is the body of a function
  563. with a single argument @code{u} which is bound to the argument to the
  564. function being integrated, not the function call itself.  Also, the
  565. variable of integration is available as @code{math-integ-var}.  If
  566. evaluation of the integral requires doing further integrals, the body
  567. should call @samp{(math-integral @var{x})} to find the integral of
  568. @var{x} with respect to @code{math-integ-var}; this function returns
  569. @code{nil} if the integral could not be done.  Some examples:
  570. X
  571. @smallexample
  572. (math-defintegral calcFunc-conj
  573. X  (let ((int (math-integral u)))
  574. X    (and int
  575. X         (list 'calcFunc-conj int))))
  576. X
  577. (math-defintegral calcFunc-cos
  578. X  (and (equal u math-integ-var)
  579. X       (math-from-radians-2 (list 'calcFunc-sin u))))
  580. @end smallexample
  581. X
  582. In the @code{cos} example, we define only the integral of @samp{cos(x) dx},
  583. relying on the general integration-by-substitution facility to handle
  584. cosines of more complicated arguments.  An integration rule should return
  585. @code{nil} if it can't do the integral; if several rules are defined for
  586. the same function, they are tried in order until one returns a non-@code{nil}
  587. result.@refill
  588. @end defmac
  589. X
  590. @defmac math-defintegral-2 funcs body
  591. Define a rule for integrating a function or functions of two arguments.
  592. This is exactly analogous to @code{math-defintegral}, except that @var{body}
  593. is written as the body of a function with two arguments, @var{u} and
  594. @var{v}.@refill
  595. @end defmac
  596. X
  597. @defun solve-for lhs rhs var full
  598. Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating
  599. the variable @var{var} on the lefthand side; return the resulting righthand
  600. side, or @code{nil} if the equation cannot be solved.  The variable
  601. @var{var} must appear at least once in @var{lhs} or @var{rhs}; if it
  602. appears more than once, Calc can solve the equation in only a few cases
  603. (such as when the quadratic formula can be applied).  Note that the
  604. return value is a formula which does not contain @var{var}; this is
  605. different from the user-level @code{solve} and @code{finv} functions,
  606. which return a rearranged equation or a functional inverse, respectively.
  607. If @var{full} is non-@code{nil}, a full solution including dummy signs
  608. and dummy integers will be produced.  User-defined inverses are provided
  609. as properties in a manner similar to derivatives:@refill
  610. X
  611. @smallexample
  612. (put 'calcFunc-ln 'math-inverse
  613. X     (function (lambda (x) (list 'calcFunc-exp x))))
  614. @end smallexample
  615. X
  616. This function can call @samp{(math-solve-get-sign @var{x})} to create
  617. a new arbitrary sign variable, returning @var{x} times that sign, and
  618. @samp{(math-solve-get-int @var{x})} to create a new arbitrary integer
  619. variable multiplied by @var{x}.  These functions simply return @var{x}
  620. if the caller requested a non-``full'' solution.
  621. @end defun
  622. X
  623. @defun solve-eqn expr var full
  624. This version of @code{solve-for} takes an expression which will
  625. typically be an equation or inequality.  (If it is not, it will be
  626. interpreted as the equation @samp{@var{expr} = 0}.)  It returns an
  627. equation or inequality, or @code{nil} if no solution could be found.
  628. @end defun
  629. X
  630. @defun expr-contains expr var
  631. Returns the number of occurrences of @var{var} as a subexpression
  632. of @var{expr}, or @code{nil} if there are no occurrences.  Thus,
  633. this function can be used as a Lisp predicate or as an actual counting
  634. function.@refill
  635. X
  636. When used as a predicate, this function seems at first to be identical
  637. to @code{calc-find-sub-formula}.  The key difference is that
  638. @code{expr-contains} uses @code{equal} to test for matches, whereas
  639. @code{calc-find-sub-formula} uses @code{eq}.  In the formula
  640. @samp{f(a, a)}, the two @samp{a}'s will be @code{equal} but not
  641. @code{eq} to each other.
  642. @end defun
  643. X
  644. @defun expr-depends expr var
  645. Returns true if @var{expr} refers to any variable the occurs in @var{var}.
  646. In other words, it checks if @var{expr} and @var{var} have any variables
  647. in common.
  648. @end defun
  649. X
  650. @defun expr-contains-vars expr
  651. Return true if @var{expr} contains any variables, or @code{nil} if @var{expr}
  652. contains only constants and functions with constant arguments.
  653. @end defun
  654. X
  655. @defun expr-subst expr old new
  656. Returns a copy of @var{expr}, with all occurrences of @var{old} replaced
  657. by @var{new}.  This treats the derivative forms specially with respect
  658. to the dummy variable, so that the effect is always to return @var{expr}
  659. evaluated at @var{old} = @var{new}.@refill
  660. @end defun
  661. X
  662. @defun expr-weight expr
  663. Returns the ``weight'' of @var{expr}, basically a count of the total
  664. number of objects and function calls that appear in @var{expr}.  For
  665. ``primitive'' objects, this will be one.
  666. @end defun
  667. X
  668. @defun expr-height expr
  669. Returns the ``height'' of @var{expr}, which is the deepest level to
  670. which function calls are nested.  (Note that @samp{@var{a} + @var{b}}
  671. counts as a function call.)  For primitive objects, this returns zero.@refill
  672. @end defun
  673. X
  674. @defun polynomial-p expr var
  675. Check if @var{expr} is a polynomial in variable (or sub-expression)
  676. @var{var}.  If so, return the degree of the polynomial, that is, the
  677. highest power of @var{var} that appears in @var{expr}.  For example,
  678. for @samp{(x^2 + 3)^3 + 4} this would return 6.  This function returns
  679. @code{nil} unless @var{expr}, when expanded out by @kbd{a x}
  680. (@code{calc-expand}), would consist of a sum of terms in which @var{var}
  681. appears only raised to nonnegative integer powers.  Note that if
  682. @var{var} does not occur in @var{expr}, then @var{expr} is considered
  683. a polynomial of degree 0.@refill
  684. @end defun
  685. X
  686. @defun is-polynomial expr var degree loose
  687. Check if @var{expr} is a polynomial in variable or sub-expression
  688. @var{var}, and, if so, return a list representation of the polynomial
  689. where the elements of the list are coefficients of successive powers of
  690. @var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the
  691. list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would
  692. produce the list @samp{(1 2 1)}.  The highest element of the list will
  693. be non-zero, with the special exception that if @var{expr} is the
  694. constant zero, the returned value will be @samp{(0)}.  Return @code{nil}
  695. if @var{expr} is not a polynomial in @var{var}.  If @var{degree} is
  696. specified, this will not consider polynomials of degree higher than that
  697. value.  This is a good precaution because otherwise an input of
  698. @samp{(x+1)^1000} will cause a huge coefficient list to be built.  If
  699. @var{loose} is non-@code{nil}, then a looser definition of a polynomial
  700. is used in which coefficients are no longer required not to depend on
  701. @var{var}, but are only required not to take the form of polynomials
  702. themselves.  For example, @samp{sin(x) x^2 + cos(x)} is a loose
  703. polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin
  704. x))}.  The result will never be @code{nil} in loose mode, since any
  705. expression can be interpreted as a ``constant'' loose polynomial.@refill
  706. @end defun
  707. X
  708. @defun polynomial-base expr pred
  709. Check if @var{expr} is a polynomial in any variable that occurs in it;
  710. if so, return that variable.  (If @var{expr} is a multivariate polynomial,
  711. choose one variable arbitrarily.)  If @var{pred} is specified, it should
  712. be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})},
  713. and which should return true if @code{mpb-top-expr} (a global name for
  714. the original @var{expr}) is a suitable polynomial in @var{subexpr}.
  715. The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})};
  716. you can use @var{pred} to specify additional conditions.  Or, you could
  717. have @var{pred} build up a list of every suitable @var{subexpr} that
  718. is found.@refill
  719. @end defun
  720. X
  721. @defun poly-simplify poly
  722. Simplify polynomial coefficient list @var{poly} by (destructively)
  723. clipping off trailing zeros.
  724. @end defun
  725. X
  726. @defun poly-mix a ac b bc
  727. Mix two polynomial lists @var{a} and @var{b} (in the form returned by
  728. @code{is-polynomial}) in a linear combination with coefficient expressions
  729. @var{ac} and @var{bc}.  The result is a (not necessarily simplified)
  730. polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}.@refill
  731. @end defun
  732. X
  733. @defun poly-mul a b
  734. Multiply two polynomial coefficient lists @var{a} and @var{b}.  The
  735. result will be in simplified form if the inputs were simplified.
  736. @end defun
  737. X
  738. @defun build-polynomial-expr poly var
  739. Construct a Calc formula which represents the polynomial coefficient
  740. list @var{poly} applied to variable @var{var}.  The @kbd{a c}
  741. (@code{calc-collect}) command uses @code{is-polynomial} to turn an
  742. expression into a coefficient list, then @code{build-polynomial-expr}
  743. to turn the list back into an expression in regular form.@refill
  744. @end defun
  745. X
  746. @defun check-unit-name var
  747. Check if @var{var} is a variable which can be interpreted as a unit
  748. name.  If so, return the units table entry for that unit.  This
  749. will be a list whose first element is the unit name (not counting
  750. prefix characters) as a symbol and whose second element is the
  751. Calc expression which defines the unit.  (Refer to the Calc sources
  752. for details on the remaining elements of this list.)  If @var{var}
  753. is not a variable or is not a unit name, return @code{nil}.
  754. @end defun
  755. X
  756. @defun units-in-expr-p expr sub-exprs
  757. Return true if @var{expr} contains any variables which can be
  758. interpreted as units.  If @var{sub-exprs} is @code{t}, the entire
  759. expression is searched.  If @var{sub-exprs} is @code{nil}, this
  760. checks whether @var{expr} is directly a units expression.@refill
  761. @end defun
  762. X
  763. @defun single-units-in-expr-p expr
  764. Check whether @var{expr} contains exactly one units variable.  If so,
  765. return the units table entry for the variable.  If @var{expr} does
  766. not contain any units, return @code{nil}.  If @var{expr} contains
  767. two or more units, return the symbol @samp{'wrong}.
  768. @end defun
  769. X
  770. @defun to-standard-units expr which
  771. Convert units expression @var{expr} to base units.  If @var{which}
  772. is @code{nil}, use Calc's native base units.  Otherwise, @var{which}
  773. can specify a units system, which is a list of two-element lists,
  774. where the first element is a Calc base symbol name and the second
  775. is an expression to substitute for it.@refill
  776. @end defun
  777. X
  778. @defun remove-units expr
  779. Return a copy of @var{expr} with all units variables replaced by ones.
  780. This expression is generally normalized before use.
  781. @end defun
  782. X
  783. @defun extract-units expr
  784. Return a copy of @var{expr} with everything but units variables replaced
  785. by ones.
  786. @end defun
  787. X
  788. @node Formatting Lisp Functions, Lisp Variables, Symbolic Lisp Functions, Internals
  789. @subsubsection I/O and Formatting Functions
  790. X
  791. @noindent
  792. The functions described here are responsible for parsing and formatting
  793. Calc numbers and formulas.
  794. X
  795. @defun calc-eval str sep arg1 arg2 @dots{}
  796. This is the simplest interface to the Calculator from another Lisp program.
  797. @xref{Calling Calc from Your Programs}.
  798. @end defun
  799. X
  800. @defun read-number str
  801. If string @var{str} contains a valid Calc number, either integer,
  802. fraction, float, or HMS form, this function parses and returns that
  803. number.  Otherwise, it returns @code{nil}.
  804. @end defun
  805. X
  806. @defun read-expr str
  807. Read an algebraic expression from string @var{str}.  If @var{str} does
  808. not have the form of a valid expression, return a list of the form
  809. @samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index
  810. into @var{str} of the general location of the error, and @var{msg} is
  811. a string describing the problem.@refill
  812. @end defun
  813. X
  814. @defun read-exprs str
  815. Read a list of expressions separated by commas, and return it as a
  816. Lisp list.  If an error occurs in any expressions, an error list as
  817. shown above is returned instead.
  818. @end defun
  819. X
  820. @defun calc-do-alg-entry initial prompt no-norm
  821. Read an algebraic formula or formulas using the minibuffer.  All
  822. conventions of regular algebraic entry are observed.  The return value
  823. is a list of Calc formulas; there will be more than one if the user
  824. entered a list of values separated by commas.  The result is @code{nil}
  825. if the user presses Return with a blank line.  If @var{initial} is
  826. given, it is a string which the minibuffer will initially contain.
  827. If @var{prompt} is given, it is the prompt string to use; the default
  828. is ``Algebraic:''.  If @var{no-norm} is @code{t}, the formulas will
  829. be returned exactly as parsed; otherwise, they will be passed through
  830. @code{calc-normalize} first.@refill
  831. X
  832. To support the use of @kbd{$} characters in the algebraic entry, use
  833. @code{let} to bind @code{calc-dollar-values} to a list of the values
  834. to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind
  835. @code{calc-dollar-used} to 0.  Upon return, @code{calc-dollar-used}
  836. will have been changed to the highest number of consecutive @kbd{$}s
  837. that actually appeared in the input.@refill
  838. @end defun
  839. X
  840. @defun format-number a
  841. Convert the real or complex number or HMS form @var{a} to string form.
  842. @end defun
  843. X
  844. @defun format-flat-expr a prec
  845. Convert the arbitrary Calc number or formula @var{a} to string form,
  846. in the style used by the trail buffer.  This is a simple format designed
  847. mostly to guarantee the string is of a form that can be re-parsed by
  848. @code{read-expr}.  Most formatting modes, such as digit grouping,
  849. complex number format, and point character, are ignored to ensure the
  850. result will be re-readable.  The @var{prec} parameter is normally 0; if
  851. you pass a large integer like 1000 instead, the expression will be
  852. surrounded by parentheses unless it is a plain number or variable name.
  853. @end defun
  854. X
  855. @defun format-nice-expr a width
  856. This is like @code{format-flat-expr} (with @var{prec} equal to 0),
  857. except that newlines will be inserted to keep lines down to the
  858. specified @var{width}, and vectors of vectors (not necessarily
  859. strict matrices) are written in a pseudo-matrix format.  The
  860. @code{calc-edit} command uses this when only a stack entry is
  861. being edited.
  862. @end defun
  863. X
  864. @defun format-value a width
  865. Convert the Calc number or formula @var{a} to string form, using the
  866. format seen in the stack buffer.  Beware the the string returned may
  867. not be re-readable by @code{read-expr}, for example, because of digit
  868. grouping.  Multi-line objects like matrices produce strings that
  869. contain newline characters to separate the lines.  The @var{w}
  870. parameter, if given, is the target window size for which to format
  871. the expressions.  If @var{w} is omitted, the width of the Calculator
  872. window is used.@refill
  873. @end defun
  874. X
  875. @defun compose-expr a prec
  876. Format the Calc number or formula @var{a} according to the current
  877. language mode, returning a ``composition.''  To learn about the
  878. structure of compositions, see the comments in the Calc source code.
  879. You can specify the format of a given type of function call by putting
  880. a @code{math-compose-@var{lang}} property on the function's symbol,
  881. whose value is a Lisp function that takes @var{a} and @var{prec} as
  882. arguments and returns a composition.  Here @var{lang} is a language
  883. mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal},
  884. @code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}.
  885. In Big mode, Calc actually tries @code{math-compose-big} first, then
  886. tries @code{math-compose-normal}.  If this property does not exist,
  887. or if the function returns @code{nil}, the function is written in the
  888. normal function-call notation for that language.
  889. @end defun
  890. X
  891. @defun composition-to-string c w
  892. Convert a composition structure returned by @code{compose-expr} into
  893. a string.  Multi-line compositions convert to strings containing
  894. newline characters.  The target window size is given by @var{w}.
  895. The @code{format-value} function basically calls @code{compose-expr}
  896. followed by @code{composition-to-string}.
  897. @end defun
  898. X
  899. @defun comp-width c
  900. Compute the width in characters of composition @var{c}.
  901. @end defun
  902. X
  903. @defun comp-height c
  904. Compute the height in lines of composition @var{c}.
  905. @end defun
  906. X
  907. @defun comp-ascent c
  908. Compute the portion of the height of composition @var{c} which is on or
  909. above the baseline.  For a one-line composition, this will be one.
  910. @end defun
  911. X
  912. @defun comp-descent c
  913. Compute the portion of the height of composition @var{c} which is below
  914. the baseline.  For a one-line composition, this will be zero.
  915. @end defun
  916. X
  917. @defun comp-first-char c
  918. If composition @var{c} is a simple horizontal composition, return the
  919. first (leftmost) character of the composition as an integer.  Otherwise,
  920. return @code{nil}.@refill
  921. @end defun
  922. X
  923. @defun comp-last-char c
  924. If composition @var{c} is a simple horizontal composition, return the
  925. last (rightmost) character, otherwise return @code{nil}.
  926. @end defun
  927. X
  928. @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals
  929. @subsubsection Lisp Variables
  930. X
  931. @noindent
  932. (This section is currently unfinished.)
  933. X
  934. @node Hooks, , Lisp Variables, Internals
  935. @subsubsection Hooks
  936. X
  937. @noindent
  938. Hooks are variables which contain Lisp functions (or lists of functions)
  939. which are called at various times.  Calc defines a number of hooks
  940. that help you to customize it in various ways.  Calc uses the Lisp
  941. function @code{run-hooks} to invoke the hooks shown below.  Several
  942. other customization-related variables are also described here.
  943. X
  944. @defvar calc-load-hook
  945. This hook is called at the end of @file{calc.el}, after the file has
  946. been loaded, before any functions in it have been called, but after
  947. @code{calc-mode-map} and similar variables have been set up.
  948. @end defvar
  949. X
  950. @defvar calc-ext-load-hook
  951. This hook is called at the end of @file{calc-ext.el}.
  952. @end defvar
  953. X
  954. @defvar calc-start-hook
  955. This hook is called as the last step in a @kbd{M-x calc} command.
  956. At this point, the Calc buffer has been created and initialized if
  957. necessary, the Calc window and trail window have been created,
  958. and the ``Welcome to Calc'' message has been displayed.
  959. @end defvar
  960. X
  961. @defvar calc-mode-hook
  962. This hook is called when the Calc buffer is being created.  Usually
  963. this will only happen once per Emacs session.  The hook is called
  964. after Emacs has switched to the new buffer, the mode-settings file
  965. has been read if necessary, and all other buffer-local variables
  966. have been set up.  After this hook returns, Calc will perform a
  967. @code{calc-refresh} operation, set up the mode line display, then
  968. evaluate any deferred @code{calc-define} properties that have not
  969. been evaluated yet.
  970. @end defvar
  971. X
  972. @defvar calc-trail-mode-hook
  973. This hook is called when the Calc Trail buffer is being created.
  974. It is called as the very last step of setting up the Trail buffer.
  975. Like @code{calc-mode-hook}, this will normally happen only once
  976. per Emacs session.
  977. @end defvar
  978. X
  979. @defvar calc-end-hook
  980. This hook is called by @code{calc-quit}, generally because the user
  981. presses @key{q} or @kbd{M-# c} while in Calc.  The Calc buffer will
  982. be the current buffer.  The hook is called as the very first
  983. step, before the Calc window has been destroyed.
  984. @end defvar
  985. X
  986. @defvar calc-window-hook
  987. If this hook exists, it is called to create the Calc window.
  988. Upon return, this new Calc window should be the current window.
  989. (The Calc buffer will already be the current buffer when the
  990. hook is called.)  If the hook is not defined, Calc will
  991. generally use @code{split-window}, @code{set-window-buffer},
  992. and @code{select-window} to create the Calc window.
  993. @end defvar
  994. X
  995. @defvar calc-trail-window-hook
  996. If this hook exists, it is called to create the Calc Trail window.
  997. The variable @code{calc-trail-buffer} will contain the buffer
  998. which the window should use.  Unlike @code{calc-window-hook},
  999. this hook must @emph{not} switch into the new window.
  1000. @end defvar
  1001. X
  1002. @defvar calc-edit-mode-hook
  1003. This hook is called by @code{calc-edit} (and a few other similar
  1004. commands) when the temporary editing buffer is being created.
  1005. The buffer will have been selected and set up to be in
  1006. @code{calc-edit-mode}, but will not yet have been filled with
  1007. text.  (In fact it may still have leftover text from a previous
  1008. @code{calc-edit} command.)
  1009. @end defvar
  1010. X
  1011. @defvar calc-mode-save-hook
  1012. This hook is called by the @code{calc-save-modes} command,
  1013. after Calc's own mode features have been inserted into the
  1014. @file{.emacs} buffer and just before the ``End of mode settings''
  1015. message is inserted.
  1016. @end defvar
  1017. X
  1018. @defvar calc-reset-hook
  1019. This hook is called after @kbd{M-# 0} (@code{calc-reset}) has
  1020. reset all modes.  The Calc buffer will be the current buffer.
  1021. @end defvar
  1022. X
  1023. @defvar calc-other-modes
  1024. This variable contains a list of strings.  The strings are
  1025. concatenated at the end of the modes portion of the Calc
  1026. mode line (after standard modes such as ``Deg'', ``Inv'' and
  1027. ``Hyp'').  Each string should be a short, single word followed
  1028. by a space.  The variable is @code{nil} by default.
  1029. @end defvar
  1030. X
  1031. @defvar calc-mode-map
  1032. This is the keymap that is used by Calc mode.  The best time
  1033. to adjust it is probably in a @code{calc-mode-hook}.  If the
  1034. Calc extensions package (@file{calc-ext.el}) has not yet been
  1035. loaded, many of these keys will be bound to @code{calc-missing-key},
  1036. which is a command that loads the extensions package and
  1037. ``retypes'' the key.  If your @code{calc-mode-hook} rebinds
  1038. one of these keys, it will probably be overridden when the
  1039. extensions are loaded.
  1040. @end defvar
  1041. X
  1042. @defvar calc-digit-map
  1043. This is the keymap that is used during numeric entry.  Numeric
  1044. entry uses the minibuffer, but this map binds every non-numeric
  1045. key to @code{calcDigit-nondigit} which generally calls
  1046. @code{exit-minibuffer} and ``retypes'' the key.
  1047. @end defvar
  1048. X
  1049. @defvar calc-alg-ent-map
  1050. This is the keymap that is used during algebraic entry.  This is
  1051. mostly a copy of @code{minibuffer-local-map}.
  1052. @end defvar
  1053. X
  1054. @defvar calc-store-var-map
  1055. This is the keymap that is used during entry of variable names for
  1056. commands like @code{calc-store} and @code{calc-recall}.  This is
  1057. mostly a copy of @code{minibuffer-local-completion-map}.
  1058. @end defvar
  1059. X
  1060. @defvar calc-edit-mode-map
  1061. This is the (sparse) keymap used by @code{calc-edit} and other
  1062. temporary editing commands.  It binds @key{RET}, @key{LFD},
  1063. and @kbd{C-c C-c} to @code{calc-edit-finish}.
  1064. @end defvar
  1065. X
  1066. @defvar calc-mode-var-list
  1067. This is a list of variables which are saved by @code{calc-save-modes}.
  1068. Each entry is a list of two items, the variable (as a Lisp symbol)
  1069. and its default value.  When modes are being saved, each variable
  1070. is compared with its default value (using @code{equal}) and any
  1071. non-default variables are written out.
  1072. @end defvar
  1073. X
  1074. @defvar calc-local-var-list
  1075. This is a list of variables which should be buffer-local to the
  1076. Calc buffer.  Each entry is a variable name (as a Lisp symbol).
  1077. These variables also have their default values manipulated by
  1078. the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}.
  1079. Since @code{calc-mode-hook} is called after this list has been
  1080. used the first time, your hook should add a variable to the
  1081. list and also call @code{make-local-variable} itself.
  1082. @end defvar
  1083. X
  1084. @node Installation, Reporting Bugs, Programming, Top
  1085. @appendix Installation
  1086. X
  1087. @noindent
  1088. Calc 2.00 comes as a set of GNU Emacs Lisp files, with names like
  1089. @file{calc.el} and @file{calc-ext.el}, and also as a @file{calc.texinfo}
  1090. file which can be used to generate both on-line and printed
  1091. documentation.@refill
  1092. X
  1093. To install Calc, just follow these simple steps.  If you want more
  1094. information, each step is discussed at length in the sections below.
  1095. X
  1096. @enumerate
  1097. @item
  1098. Change (@samp{cd}) to the Calc ``home'' directory.  This directory was
  1099. created when you unbundled the Calc @file{.tar} or @file{.shar} file.
  1100. X
  1101. @item
  1102. Type @samp{make} to install Calc privately for your own use, or type
  1103. @samp{make install} to install Calc system-wide.  This will compile all
  1104. the Calc component files, modify your @file{.emacs} or the system-wide
  1105. @file{lisp/default} file to install Calc as appropriate, and format
  1106. the on-line Calc manual.
  1107. X
  1108. @noindent
  1109. Both variants are shorthand for the following three steps:
  1110. @itemize @bullet
  1111. @item
  1112. @pindex calc-compile
  1113. @samp{make compile} to run the byte-compiler.
  1114. X
  1115. @item
  1116. @samp{make private} or @samp{make public}, corresponding to
  1117. @samp{make} and @samp{make install}, respectively.  (If @samp{make public}
  1118. fails because your system doesn't already have a @file{default} or
  1119. @file{default.el} file, use Emacs or the Unix @code{touch} command
  1120. to create a zero-sized one first.)
  1121. X
  1122. @item
  1123. @samp{make info} to format the on-line Calc manual.  This first tries
  1124. to use the @file{makeinfo} program; if that program is not present, it
  1125. uses the Emacs @code{texinfo-format-buffer} command instead.
  1126. @end itemize
  1127. @noindent
  1128. The Unix @code{make} utility looks in the file @file{Makefile} in the
  1129. current directory to see what Unix commands correspond to the various
  1130. ``targets'' like @code{install} or @code{public}.  If your system
  1131. doesn't have @code{make}, you will have to examine the @file{Makefile}
  1132. and type in the corresponding commands by hand.
  1133. X
  1134. @item
  1135. If you ever move Calc to a new home directory, just give the
  1136. @samp{make private} or @samp{make public} command again in the new
  1137. directory.
  1138. X
  1139. @item
  1140. Test your installation as described at the end of these instructions.
  1141. X
  1142. @item
  1143. (Optional.)  To print a hardcopy of the Calc manual (over 500 pages)
  1144. or just the Calc Summary (about 20 pages), follow the instructions under
  1145. ``Printed Documentation'' below.
  1146. @end enumerate
  1147. X
  1148. @noindent
  1149. Calc is now installed and ready to go!
  1150. @example
  1151. X
  1152. @end example
  1153. X
  1154. @appendixsec Upgrading from Calc 1.07
  1155. X
  1156. @noindent
  1157. If you have Calc version 1.07 or earlier, you will find that Calc 2.00
  1158. is organized quite differently.  For one, Calc 2.00 is now distributed
  1159. already split into many parts; formerly this was done as part of the
  1160. installation procedure.  Also, some new functions must be autoloaded
  1161. and the @kbd{M-#} key must be bound to @code{calc-dispatch} instead
  1162. of to @code{calc}.
  1163. X
  1164. The easiest way to upgrade is to delete your old Calc files and then
  1165. install Calc 2.00 from scratch using the above instructions.  You should
  1166. then go into your @file{.emacs} or @file{default} file and remove the
  1167. old @code{autoload} and @code{global-set-key} commands for Calc, since
  1168. @samp{make public}/@samp{make private} has added new, better ones.
  1169. X
  1170. @xref{New for Calc 2.00}, for more information about what has
  1171. changed since version 1.07.
  1172. X
  1173. @ifinfo
  1174. @example
  1175. X
  1176. @end example
  1177. @end ifinfo
  1178. @appendixsec The @samp{make public} Command
  1179. X
  1180. If you are not the regular Emacs administrator on your system, your
  1181. account may not be allowed to execute the @samp{make public} command,
  1182. since the system-wide @file{default} file may be write-protected.
  1183. If this is the case, you will have to ask your Emacs installer to
  1184. execute this command.  (Just @code{cd} to the Calc home directory
  1185. and type @samp{make public}.)
  1186. X
  1187. The @samp{make private} command adds exactly the same set of commands
  1188. to your @file{.emacs} file as @samp{make public} adds to @file{default}.
  1189. If your Emacs installer is concerned about typing this command out of
  1190. the blue, you can ask her/him instead to copy the necessary text from
  1191. your @file{.emacs} file.  (They will be marked by a comment that says
  1192. ``Commands added by @code{calc-private-autoloads} on (date and time).'')
  1193. X
  1194. @ifinfo
  1195. @example
  1196. X
  1197. @end example
  1198. @end ifinfo
  1199. @appendixsec Compilation
  1200. X
  1201. @noindent
  1202. Calc is written in a way that maximizes performance when its code has been
  1203. byte-compiled; a side effect is that performance is seriously degraded if
  1204. it @emph{isn't} compiled.  Thus, it is essential to compile the Calculator
  1205. before trying to use it.  The function @samp{calc-compile} in the file
  1206. @file{calc-maint.el} runs the Emacs byte-compiler on all the Calc source
  1207. files.  (Specifically, it runs @kbd{M-x byte-compile-file} on all files
  1208. in the current directory with names of the form @file{calc*.el}, and also
  1209. on the file @file{macedit.el}.)
  1210. X
  1211. If @code{calc-compile} finds that certain files have already been
  1212. compiled and have not been changed since, then it will not bother to
  1213. recompile those files.
  1214. X
  1215. The @code{calc-compile} command also pre-builds certain tables, such as
  1216. the units table (@pxref{The Units Table}) and the built-in rewrite rules
  1217. (@pxref{Rearranging with Selections}) which Calc would otherwise
  1218. need to rebuild every time those features were used.
  1219. X
  1220. The @samp{make compile} shell command is simply a convenient way to
  1221. start an Emacs and give it a @code{calc-compile} command.
  1222. X
  1223. @ifinfo
  1224. @example
  1225. X
  1226. @end example
  1227. @end ifinfo
  1228. @appendixsec Auto-loading
  1229. X
  1230. @noindent
  1231. To teach Emacs how to load in Calc when you type @kbd{M-#} for the
  1232. first time, add these lines to your @file{.emacs} file (if you are
  1233. installing Calc just for your own use), or the system's @file{lisp/default}
  1234. file (if you are installing Calc publicly).  The @samp{make private}
  1235. and @samp{make public} commands, respectively, take care of this.
  1236. (Note that @samp{make} runs @samp{make private}, and @samp{make install}
  1237. runs @samp{make public}.)
  1238. X
  1239. @smallexample
  1240. (autoload 'calc-dispatch          "calc" "Calculator Options" t)
  1241. (autoload 'full-calc              "calc" "Full-screen Calculator" t)
  1242. (autoload 'full-calc-keypad       "calc" "Full-screen X Calculator" t)
  1243. (autoload 'calc-eval              "calc" "Use Calculator from Lisp")
  1244. (autoload 'defmath                "calc" nil t t)
  1245. (autoload 'calc                   "calc" "Calculator Mode" t)
  1246. (autoload 'quick-calc             "calc" "Quick Calculator" t)
  1247. (autoload 'calc-keypad            "calc" "X windows Calculator" t)
  1248. (autoload 'calc-embedded          "calc" "Use Calc from any buffer" t)
  1249. (autoload 'calc-embedded-activate "calc" "Activate =>'s in buffer" t)
  1250. (autoload 'calc-grab-region       "calc" "Grab region of Calc data" t)
  1251. (autoload 'calc-grab-rectangle    "calc" "Grab rectangle of data" t)
  1252. @end smallexample
  1253. X
  1254. @vindex load-path
  1255. Unless you have installed the Calc files in Emacs' main @file{lisp/}
  1256. directory, you will also have to add a command that looks like the
  1257. following to tell Emacs where to find them.  In this example, we
  1258. have put the files in directory @file{/usr/gnu/src/calc-2.00}.
  1259. X
  1260. @smallexample
  1261. (setq load-path (append load-path (list "/usr/gnu/src/calc-2.00")))
  1262. @end smallexample
  1263. X
  1264. @noindent
  1265. The @samp{make public} and @samp{make private} commands also do this
  1266. (they use the then-current directory as the name to add to the path).
  1267. If you move Calc to a new location, just repeat the @samp{make public}
  1268. or @samp{make private} command to have this new location added to
  1269. the @code{load-path}.@refill
  1270. X
  1271. The @code{autoload} command for @code{calc-dispatch} is what loads
  1272. @file{calc.elc} when you type @kbd{M-#}.  It is the only @code{autoload}
  1273. that is absolutely necessary for Calc to work.  The others are for
  1274. commands and features that you may wish to use before typing
  1275. @kbd{M-#} for the first time.  In particular, @code{full-calc} and
  1276. @code{full-calc-keypad} are autoloaded to support ``standalone''
  1277. operation (@pxref{Standalone Operation}), @code{calc-eval} and
  1278. @code{defmath} are autoloaded to allow other Emacs Lisp programs to
  1279. use Calc facilities (@pxref{Calling Calc from Your Programs}), and
  1280. @code{calc-embedded-activate} is autoloaded because some Embedded
  1281. Mode files may call it as soon as they are read into Emacs
  1282. (@pxref{Assignments in Embedded Mode}).
  1283. X
  1284. @ifinfo
  1285. @example
  1286. X
  1287. @end example
  1288. @end ifinfo
  1289. @appendixsec Finding Component Files
  1290. X
  1291. There is no need to write @code{autoload} commands that point to all
  1292. the various Calc component files like @file{calc-misc.elc} and
  1293. @file{calc-alg.elc}.  The main file, @file{calc.elc}, contains all
  1294. the necessary @code{autoload} commands for these files.
  1295. X
  1296. (Actually, to conserve space @file{calc.elc} only autoloads a few of
  1297. the component files, plus @file{calc-ext.elc}, which in turn autoloads
  1298. the rest of the components.  This allows Calc to load a little faster
  1299. in the beginning, but the net effect is the same.)
  1300. X
  1301. This autoloading mechanism assumes that all the component files can
  1302. be found on the @code{load-path}.  The @samp{make public} and
  1303. @samp{make private} commands take care of this, but Calc has a few
  1304. other strategies in case you have installed it in an unusual way.
  1305. X
  1306. If, when Calc is loaded, it is unable to find its components on the
  1307. @code{load-path} it is given, it checks the file name in the original
  1308. @code{autoload} command for @code{calc-dispatch}.  If that name
  1309. included directory information, Calc adds that directory to the
  1310. @code{load-path}:
  1311. X
  1312. @example
  1313. (autoload 'calc-dispatch "calc-2.00/calc" "Calculator" t)
  1314. @end example
  1315. X
  1316. @noindent
  1317. Suppose the directory @file{/usr/gnu/src/emacs/lisp} is on the path, and
  1318. SHAR_EOF
  1319. true || echo 'restore of calc.texinfo failed'
  1320. fi
  1321. echo 'End of  part 54'
  1322. echo 'File calc.texinfo is continued in part 55'
  1323. echo 55 > _shar_seq_.tmp
  1324. exit 0
  1325. exit 0 # Just in case...
  1326. -- 
  1327. Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
  1328. Sterling Software, IMD           UUCP:     uunet!sparky!kent
  1329. Phone:    (402) 291-8300         FAX:      (402) 291-4362
  1330. Please send comp.sources.misc-related mail to kent@uunet.uu.net.
  1331.