home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / elisp / misc / setf / README < prev    next >
Encoding:
Text File  |  1992-04-22  |  4.1 KB  |  87 lines
  1. Setf.el is an implementation of ``generalized variable'' operations for
  2. elisp.  A generalized variable is anything that has a value that can be both
  3. retrieved and stored into (which obviously includes normal variables!); e.g.,
  4. the car of a cons-cell can be retrieved with CAR, and stored into with SETCAR.
  5.  
  6. Setf (the whole package, not the macro) remembers which storage-function
  7. corresponds to each access function, and allows you to use the name of the
  8. access-function for both purposes:
  9.   (setf (car x) y) is the same as (setcar x y), and
  10.   (setf (get x y) z) is the same as (put x y z).
  11.  
  12. Because a generalized variable, say (nth (1+ (f1 x)) (f2 y)), may involve
  13. evaluating forms that have side-effects (here perhaps the functions f1 and
  14. f2), setf uses a mechanism that allows it to ensure that the sub-forms of the
  15. GV are only evaluated once, and in the same order in which they occur in the
  16. source.  So you can write (push 'hello (nth (1+ (f1 x)) (f2 y))) and it will
  17. only call f1 and f2 once.
  18.  
  19. Most standard emacs and lisp functions have setf definitions defined here,
  20. but you can define new ones using defsetf and define-setf-method.
  21.  
  22. ****************
  23. The following files should have been included:
  24.  
  25.  setf.el --    A full* implementation of setf & friends for emacs-lisp, as
  26.      defined in "Common Lisp the Language."  This includes psetf, rotatef,
  27.      shiftf, both forms of defsetf, define-setf-method, etc.  Also setf
  28.      definitions for most lisp and emacs functions for which it makes sense.
  29.  letopt.el --    A let-binding optimizer, which is used by setf to remove
  30.      unecessary bindings which are generated.  This is functionality which
  31.      should perhaps be folded in some form into the compiler, but it isn't
  32.      yet, so here it is.  Two macros, maybe-let and maybe-let* are the
  33.      essential interface.
  34.  plist.el --    Getf, remf, and (setf getf) -- functions for anonymous
  35.      property lists.
  36.  strhash.el --    A set of trivial wrappers for intern, etc., to provide
  37.      string-keyed hash-tables that work with setf.
  38.  gensym.el --    YA gensym.  But setf needs it, and it isn't standard.
  39.  setf-autoloads.el -- Autoloads for all the external functions in the
  40.      preceeding files.
  41.  
  42. It's recommended that these be compiled, since they use macros heavily.
  43.  
  44. ****************
  45. To use, just make sure all the above files are in directory that's on your
  46. load-path, and load setf-autoloads (which also should be done before
  47. compiling them).
  48.  
  49. The function doc strings (that you can access with ^Hf; try looking at setf,
  50. for example) are intended to be helpful, but you should see CLtL for real
  51. documentation.
  52.  
  53. Setf.el defines setf-methods for all the standard elisp that make sense (and
  54. that I could think of), both pure lisp functions and editor functions [e.g.,
  55. (setf (point) (point-min))].
  56.  
  57. ****************
  58. Setf depends two non-standard elisp packages:
  59.  * Jamie Zawinski's new byte-compiler, for the eval-and-compile special form
  60.    (the let-binding optimizer also uses information from this compiler to
  61.    detect side-effect-free functions).
  62.  * Rick Sladkey's backquote package, for a non-broken backquote macro.
  63.  
  64. The following errors will show up while setf.el(c) is loadeding if you are
  65. missing one of these package:
  66.  * If you get an error like "Autoloading failed to define function
  67.    eval-and-compile", then you don't have the new byte-compiler (or it isn't
  68.    on your standard load-path).
  69.  * If you get an error like "Symbol's value as variable is void: args", then
  70.    you don't have the new backquote package (or it isn't on your load-path).
  71.  
  72. Both of these have been posted to the net, and are worthwhile having even if
  73. you don't use setf.  You can contact me if you can't find them elsewhere.
  74.  
  75. ****************
  76. Bug reports should be sent to Miles Bader <miles@cogsci.ed.ac.uk>.
  77.  
  78. ****************
  79. *Note:
  80.    Since there are no multiple return values in elisp, only a single
  81.    store-variable is supported (although the syntax for defsetf is still the
  82.    same, and get-setf-method still returns a list of store-variables).
  83.    For the same reason, get-setf-method returns a list of its values instead
  84.    of multiple values.
  85.  
  86.    None of the routines take environment arguments.
  87.