home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / gnu / info / calc.info-28 (.txt) < prev    next >
GNU Info File  |  1994-12-22  |  39KB  |  660 lines
  1. This is Info file calc.info, produced by Makeinfo-1.55 from the input
  2. file calc.texinfo.
  3.    This file documents Calc, the GNU Emacs calculator.
  4.    Copyright (C) 1990, 1991 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the section entitled "GNU General Public License" is included
  11. exactly as in the original, and provided that the entire resulting
  12. derived work is distributed under the terms of a permission notice
  13. identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions, except that the section entitled "GNU General Public License"
  17. may be included in a translation approved by the author instead of in
  18. the original English.
  19. File: calc.info,  Node: Symbolic Lisp Functions,  Next: Formatting Lisp Functions,  Prev: Vector Lisp Functions,  Up: Internals
  20. Symbolic Functions
  21. ..................
  22. The functions described here operate on symbolic formulas in the
  23. Calculator.
  24.  - Function: calc-prepare-selection NUM
  25.      Prepare a stack entry for selection operations.  If NUM is
  26.      omitted, the stack entry containing the cursor is used; otherwise,
  27.      it is the number of the stack entry to use.  This function stores
  28.      useful information about the current stack entry into a set of
  29.      variables.  `calc-selection-cache-num' contains the number of the
  30.      stack entry involved (equal to NUM if you specified it);
  31.      `calc-selection-cache-entry' contains the stack entry as a list
  32.      (such as `calc-top-list' would return with `entry' as the
  33.      selection mode); and `calc-selection-cache-comp' contains a
  34.      special "tagged" composition (*note Formatting Lisp Functions::.)
  35.      which allows Calc to relate cursor positions in the buffer with
  36.      their corresponding sub-formulas.
  37.      A slight complication arises in the selection mechanism because
  38.      formulas may contain small integers.  For example, in the vector
  39.      `[1, 2, 1]' the first and last elements are `eq' to each other;
  40.      selections are recorded as the actual Lisp object that appears
  41.      somewhere in the tree of the whole formula, but storing `1' would
  42.      falsely select both `1''s in the vector.  So
  43.      `calc-prepare-selection' also checks the stack entry and replaces
  44.      any plain integers with "complex number" lists of the form `(cplx
  45.      N 0)'.  This list will be displayed the same as a plain N and the
  46.      change will be completely invisible to the user, but it will
  47.      guarantee that no two sub-formulas of the stack entry will be `eq'
  48.      to each other.  Next time the stack entry is involved in a
  49.      computation, `calc-normalize' will replace these lists with plain
  50.      numbers again, again invisibly to the user.
  51.  - Function: calc-encase-atoms X
  52.      This modifies the formula X to ensure that each part of the
  53.      formula is a unique atom, using the `(cplx N 0)' trick described
  54.      above.  This function may use `setcar' to modify the formula
  55.      in-place.
  56.  - Function: calc-find-selected-part
  57.      Find the smallest sub-formula of the current formula that contains
  58.      the cursor.  This assumes `calc-prepare-selection' has been called
  59.      already.  If the cursor is not actually on any part of the
  60.      formula, this returns `nil'.
  61.  - Function: calc-change-current-selection SELECTION
  62.      Change the currently prepared stack element's selection to
  63.      SELECTION, which should be `eq' to some sub-formula of the stack
  64.      element, or `nil' to unselect the formula.  The stack element's
  65.      appearance in the Calc buffer is adjusted to reflect the new
  66.      selection.
  67.  - Function: calc-find-nth-part EXPR N
  68.      Return the Nth sub-formula of EXPR.  This function is used by the
  69.      selection commands, and (unless `j b' has been used) treats sums
  70.      and products as flat many-element formulas.  Thus if EXPR is `((a
  71.      + b) - c) + d', calling `calc-find-nth-part' with N equal to four
  72.      will return `d'.
  73.  - Function: calc-find-parent-formula EXPR PART
  74.      Return the sub-formula of EXPR which immediately contains PART.
  75.      If EXPR is `a*b + (c+1)*d' and PART is `eq' to the `c+1' term of
  76.      EXPR, then this function will return `(c+1)*d'.  If PART turns out
  77.      not to be a sub-formula of EXPR, the function returns `nil'.  If
  78.      PART is `eq' to EXPR, the function returns `t'.  This function
  79.      does not take associativity into account.
  80.  - Function: calc-find-assoc-parent-formula EXPR PART
  81.      This is the same as `calc-find-parent-formula', except that
  82.      (unless `j b' has been used) it continues widening the selection
  83.      to contain a complete level of the formula.  Given `a' from `((a +
  84.      b) - c) + d', `calc-find-parent-formula' will return `a + b' but
  85.      `calc-find-assoc-parent-formula' will return the whole expression.
  86.  - Function: calc-grow-assoc-formula EXPR PART
  87.      This expands sub-formula PART of EXPR to encompass a complete
  88.      level of the formula.  If PART and its immediate parent are not
  89.      compatible associative operators, or if `j b' has been used, this
  90.      simply returns PART.
  91.  - Function: calc-find-sub-formula EXPR PART
  92.      This finds the immediate sub-formula of EXPR which contains PART.
  93.      It returns an index N such that `(calc-find-nth-part EXPR N)'
  94.      would return PART.  If PART is not a sub-formula of EXPR, it
  95.      returns `nil'.  If PART is `eq' to EXPR, it returns `t'.  This
  96.      function does not take associativity into account.
  97.  - Function: calc-replace-sub-formula EXPR OLD NEW
  98.      This function returns a copy of formula EXPR, with the sub-formula
  99.      that is `eq' to OLD replaced by NEW.
  100.  - Function: simplify EXPR
  101.      Simplify the expression EXPR by applying various algebraic rules.
  102.      This is what the `a s' (`calc-simplify') command uses.  This
  103.      always returns a copy of the expression; the structure EXPR points
  104.      to remains unchanged in memory.
  105.      More precisely, here is what `simplify' does:  The expression is
  106.      first normalized and evaluated by calling `normalize'.  If any
  107.      `AlgSimpRules' have been defined, they are then applied.  Then the
  108.      expression is traversed in a depth-first, bottom-up fashion; at
  109.      each level, any simplifications that can be made are made until no
  110.      further changes are possible.  Once the entire formula has been
  111.      traversed in this way, it is compared with the original formula
  112.      (from before the call to `normalize') and, if it has changed, the
  113.      entire procedure is repeated (starting with `normalize') until no
  114.      further changes occur.  Usually only two iterations are needed:
  115.      one to simplify the formula, and another to verify that no further
  116.      simplifications were possible.
  117.  - Function: simplify-extended EXPR
  118.      Simplify the expression EXPR, with additional rules enabled that
  119.      help do a more thorough job, while not being entirely "safe" in all
  120.      circumstances.  (For example, this mode will simplify `sqrt(x^2)'
  121.      to `x', which is only valid when X is positive.)  This is
  122.      implemented by temporarily binding the variable
  123.      `math-living-dangerously' to `t' (using a `let' form) and calling
  124.      `simplify'.  Dangerous simplification rules are written to check
  125.      this variable before taking any action.
  126.  - Function: simplify-units EXPR
  127.      Simplify the expression EXPR, treating variable names as units
  128.      whenever possible.  This works by binding the variable
  129.      `math-simplifying-units' to `t' while calling `simplify'.
  130.  - Macro: math-defsimplify FUNCS BODY
  131.      Register a new simplification rule; this is normally called as a
  132.      top-level form, like `defun' or `defmath'.  If FUNCS is a symbol
  133.      (like `+' or `calcFunc-sqrt'), this simplification rule is applied
  134.      to the formulas which are calls to the specified function.  Or,
  135.      FUNCS can be a list of such symbols; the rule applies to all
  136.      functions on the list.  The BODY is wr