Return to cl.texinfo CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / man

Annotation of 43BSDReno/contrib/emacs-18.55/man/cl.texinfo, revision 1.1

1.1     ! root        1: \input texinfo    @c -*-texinfo-*-
        !             2: @setfilename ../info/cl
        !             3: @settitle Common Lisp Extensions
        !             4: 
        !             5: @iftex
        !             6: @finalout
        !             7: @end iftex
        !             8: 
        !             9: Copyright (C) 1987 Cesar Quiroz
        !            10: 
        !            11: @node Top, Generalities,,(DIR)
        !            12: @chapter Common Lisp Extensions
        !            13: 
        !            14: The routines described in this chapter provide some of the functionality of
        !            15: Common Lisp inside Emacs Lisp.
        !            16: 
        !            17: @menu
        !            18: * gen: Generalities.           Things you need to know.
        !            19: * sym: Symbols.                Gensym, gentemp, keyword-p, @dots{}
        !            20: * lis: Lists.                  List*, pairlis, acons, @dots{}
        !            21: * seq: Sequences.              Every, any, notevery, notany, @dots{}
        !            22: * con: Conditionals.           When, unless, case, ecase.
        !            23: * ite: Iterations.             Do, do*, dolist, dotimes, @dots{}
        !            24: * mul: Multiple Values.        Values, values-list, @dots{}
        !            25: * ari: Integer Arithmetic.     Floor, ceiling, round, truncate, @dots{}
        !            26: * stf: Generalized Variables.  Setf and friends.
        !            27: * str: Structures.             Like Pascal records or C structs.
        !            28: * mis: Miscellanea.            Odds and ends that didn't fit elsewhere.
        !            29: * tod: To Do.                  Suggestions for future hackery.
        !            30: @end menu
        !            31: 
        !            32: @node Generalities, Symbols, Top, Top
        !            33: @section Generalities
        !            34: 
        !            35: This section tells you want you need to know about the routines in the file
        !            36: @file{cl.el}, so that you can use them.  The distribution also includes
        !            37: this documentation and perhaps a few example files.
        !            38: 
        !            39: @subsection License, Availability, Maintenance
        !            40: 
        !            41: These files are covered by the GNU Emacs General Public License (if you
        !            42: don't know its terms, try @kbd{@key{C-h} @key{C-c}}) and the statement of
        !            43: no warranty (again, you can type @kbd{@key{C-h} @key{C-w}} if you don't
        !            44: know its terms) also applies to them. @refill
        !            45: 
        !            46: I, Cesar Quiroz, the original author of the software described here, will
        !            47: appreciate hearing about bug reports (and fixes), suggestions and comments,
        !            48: applying both to the code and to this documentation.  I don't promise to
        !            49: act on those communications, but whenever they might conduce to
        !            50: improvements of this software, I will make those improvements available to
        !            51: the general community through the Free Software Foundation.  You can reach
        !            52: me at the following net addresses:
        !            53: @quotation
        !            54: quiroz@@seneca.cs.rochester.edu
        !            55: quiroz@@rochester.arpa
        !            56: @{allegra | seismo | @dots{} @} ! rochester ! quiroz
        !            57: CSNET: Cesar Quiroz at node Rochester
        !            58: @end quotation
        !            59: 
        !            60: @subsection Purpose and Limitations
        !            61: 
        !            62: These routines were written with two purposes in mind:
        !            63: 
        !            64: @enumerate
        !            65: @item
        !            66: To make programming in Emacs Lisp even more compatible with Common Lisp.
        !            67: Indeed, my original motivation was to have a @code{do} macro.
        !            68: @item
        !            69: To facilitate to novice Lisp programmers a chance to practice with
        !            70: features commonly found only in expensive implementations of Lisp. 
        !            71: @end enumerate
        !            72: 
        !            73: In order to satisfy these purposes, the routines were written in such a way
        !            74: that it is practical to use them inside Emacs: no effort was given to
        !            75: implement features that could slow down the host Emacs unnecessarily nor
        !            76: require recoding of the Emacs Lisp interpreter.
        !            77: 
        !            78: For instance, no support is given to floating point arithmetic.
        !            79: 
        !            80: So, I have tried to implement a subset of the functionality of Common Lisp.
        !            81: Whatever is implemented, has syntactic and semantic properties like the
        !            82: equally named features of Common Lisp, but not all the relevant features
        !            83: have been implemented (@pxref{To Do}, for some suggestions).  When
        !            84: deciding what to include, I have tried to strike a balance between these
        !            85: constraints:
        !            86: 
        !            87: @enumerate
        !            88: @item
        !            89: Keep it simple, I didn't want to spend much time in this idea.
        !            90: @item
        !            91: Keep it compatible with Common Lisp.
        !            92: @item
        !            93: Keep it flexible, so my code doesn't oppose a better implementation (when
        !            94: this looked hard, I just didn't implement the feature).
        !            95: @item
        !            96: Keep an eye on the intended use of Emacs Lisp: to support an advanced
        !            97: editor.  I don't expect that more arithmetic support will be as conducive
        !            98: to this goal as having better iterations and conditionals will.
        !            99: @end enumerate
        !           100: 
        !           101: For background, the reference is ``Common Lisp: The Language'' by Guy
        !           102: Steele Jr. (Digital Press, 1984).  For all the features described here
        !           103: you can assume that the intent has been to provide the syntax and
        !           104: semantics of the features of like name in the book.  For the most part,
        !           105: this documentation will concentrate on how my routines @i{fail} to
        !           106: implement Common Lisp faithfully.
        !           107: 
        !           108: @subsubsection Specific Limitations
        !           109: 
        !           110: Emacs Lisp and Common Lisp differ enough to make some of the emulation
        !           111: difficult, expensive or nearly impractical.  Some specific limitations are
        !           112: stated here:
        !           113: 
        !           114: @enumerate
        !           115: @item
        !           116: Common Lisp is lexically scoped (mostly), while Emacs Lisp is dynamically
        !           117: scoped.  Things like @code{block}, @code{return}, @code{tagbody} are then
        !           118: practically impossible to imitate correctly (in principle, rewriting
        !           119: @code{eval}, @code{apply} and a couple of other functions would suffice,
        !           120: problem is that such rewriting amounts to  a new interpreter on top
        !           121: of the old.)  Things like @samp{implicit-blocks},
        !           122: @samp{implicit-tagbodies} and the like have not been implemented at all.
        !           123: Where they are needed, the most you can assume is that I tried to put
        !           124: @samp{implicit-progns} around places where it made sense. @refill
        !           125: 
        !           126: @item
        !           127: Emacs Lisp's @code{lambda} does not support all the possible argument
        !           128: markers.  Similarly, @code{defmacro} doesn't support automatic
        !           129: destructuring of the calls.  An approximation to a keyword-based calling
        !           130: style was implemented, mainly for the sake of @code{defstruct}, but is
        !           131: not general enough.  @refill
        !           132: 
        !           133: @item
        !           134: Emacs Lisp supports arithmetic only on integers.
        !           135: 
        !           136: @item
        !           137: Emacs Lisp doesn't support many of the basic types of Common Lisp.  In
        !           138: particular, there are no arrays beyond vectors and strings (although these
        !           139: ones are compatible), characters are essentially small
        !           140: integers, etc. @refill
        !           141: 
        !           142: @item
        !           143: There are no declarations in Emacs Lisp (in the sense of Common Lisp's
        !           144: @code{declare}, @code{proclaim}, @dots{}) nor there is a explicit lattice
        !           145: of types.  These limitations could be effectively overcome from Lisp code
        !           146: (to a extent), but I don't see them as a very pressing need, if a need at
        !           147: all in Emacs Lisp.  @code{defstruct} can be used to generate new types
        !           148: that can be recognized at runtime. @refill
        !           149: 
        !           150: @item
        !           151: The Emacs Lisp reader is not programmable.  The syntax it accepts is
        !           152: almost standard, but it preempts '?' as a dispatching macro of sorts.
        !           153: The @code{format} function is incompatible with Common Lisp.  There
        !           154: isn't a `quasi-constant' notation (the usual @code{backquote} of Common
        !           155: Lisp).  None of these differences causes any problems when writing Emacs
        !           156: Lisp (although the lack of backquoting is felt sorely), but they oppose
        !           157: a Common Lisp emulation. @refill
        !           158: 
        !           159: @end enumerate
        !           160: 
        !           161: @subsection Loading and Compiling
        !           162: 
        !           163: The file @file{cl.el} provides the @samp{cl} feature, you can use this to
        !           164: test whether these routines have been loaded, or to load them from your
        !           165: code (by means of @code{(require 'cl)}).  The compiled file is a little
        !           166: larger than 50K bytes.
        !           167: 
        !           168: If you need to recompile the sources, make sure you load them first on the
        !           169: Emacs that will do the recompilation.  This is because many syntactic
        !           170: characteristics (like the special forms) have been implemented as macros
        !           171: and you need to make sure that macros are known to the compiler before they
        !           172: are used.
        !           173: 
        !           174: These extensions work correctly when interpreted in a GNU Emacs of
        !           175: version 17.64 or beyond.  Compiling them requires a more recent byte
        !           176: compiler, preferably one strictly younger than version 18.XX.
        !           177: 
        !           178: @subsection On Line Help
        !           179: 
        !           180: The routines in this file have documentation strings, so you can (and
        !           181: should) consult them for the exact syntax allowed.  That information is
        !           182: not repeated in this manual.  Some of the routines are also documented
        !           183: explicitly in the Common Lisp reference, their doc-strings begin with
        !           184: @samp{[cl]} to represent this fact.
        !           185: 
        !           186: The rest (those without the @samp{[cl]} mark) are auxiliary functions or
        !           187: macros used by the rest of the implementation.  They are not constrained
        !           188: by any standard and are advertised only in as much as they can be useful
        !           189: in other applications. @refill
        !           190: 
        !           191: Each of the following sections contains a subsection called `Features
        !           192: Provided'.  It lists briefly the user-visible features of this
        !           193: implementation.  In its entries, names by themselves refer to functions.
        !           194: Macros and variables are identified by a `MACRO' or a `VARIABLE' ahead
        !           195: of their names.
        !           196: 
        !           197: @node Symbols, Lists, Generalities, Top
        !           198: @section Symbols
        !           199: 
        !           200: The most important omission is that of a @var{packages} mechanism.
        !           201: (For a possible implementation, @pxref{To Do})  Whenever a Common Lisp
        !           202: function expects a package, I have substituted an obarray.  There is a
        !           203: hack to have pseudo-keywords, see below. @refill
        !           204: 
        !           205: There are two other notorious omissions over which I haven't lost any
        !           206: sleep.  The first is the lack of a @code{remprop} function, which could be
        !           207: easily provided if needed.  The second is the lack of ways to modify the
        !           208: print name of a symbol.  This one would probably be good only to
        !           209: introduce strange bugs, so I don't miss it. @refill
        !           210: 
        !           211: @subsection Features Provided
        !           212: 
        !           213: @table @code
        !           214: @item VARIABLE *gensym-index*
        !           215: @itemx VARIABLE *gensym-prefix*
        !           216: @itemx VARIABLE *gentemp-index*
        !           217: @itemx VARIABLE *gentemp-prefix*
        !           218: These variables are used to keep the state of the generator of new names.
        !           219: Better leave them alone.
        !           220: @item gensym
        !           221: @itemx gentemp
        !           222: These do the same as the Common Lisp names of like names.
        !           223: @item MACRO defkeyword 
        !           224: @itemx keyword-of
        !           225: @item keywordp
        !           226: These provide the pseudo-keywords implementation.
        !           227: @end table
        !           228: 
        !           229: @subsection Keywords
        !           230: 
        !           231: The lack of packages makes it difficult to implement keywords correctly.
        !           232: I have provided a macro @code{defkeyword} that takes a symbol and makes
        !           233: sure it evaluates to itself.  (So, it is like @code{defconst}.)  If your
        !           234: programs ever need keywords, put a bunch of calls to @code{defkeyword} at
        !           235: the beginning of your code, so when loaded they will be in effect. @refill
        !           236: 
        !           237: The (standard) predicate @code{keywordp} tests to see if the given
        !           238: symbol's name begins with a colon and then ensures that it evaluates to
        !           239: itself. @refill
        !           240: 
        !           241: The function @code{keyword-of} takes a symbol and returns a keyword of
        !           242: like name. @refill
        !           243: 
        !           244: @example
        !           245:  (keyword-of 'foo)
        !           246: :foo
        !           247:  (keyword-of ':bar)
        !           248: :bar
        !           249: @end example
        !           250: 
        !           251: This feature was added mainly to support @code{defstruct} and the tests of
        !           252: the sequence functions.  It is fragile and easy to fool.
        !           253: 
        !           254: @subsection New Symbols
        !           255: 
        !           256: A common need (especially when writing macros) is to be able to invent new
        !           257: names for things.  I provide the @code{gensym} and @code{gentemp}
        !           258: functions.  The global state needed is kept in the variables
        !           259: @code{*gentemp-index*}, @code{*gentemp-prefix*}, @code{*gensym-index*} and
        !           260: @code{*gensym-prefix*}.  Changing them, especially the index ones, is a
        !           261: very bad idea.  I am not providing the Common Lisp default prefixes ('G'
        !           262: for @code{gensym} and 'T' for @code{gentemp}) because of debugging
        !           263: paranoia.  My default prefixes are harder to come by when giving sane
        !           264: names to things. @refill
        !           265: 
        !           266: @node Lists, Sequences, Symbols, Top
        !           267: @section Lists
        !           268: 
        !           269: Lists (indeed, conses) are so deeply involved in Lisp that there seems
        !           270: to be little need to justify improving the list handling of a Lisp.
        !           271: 
        !           272: Common Lisp, however, is a rather huge Lisp.  I haven't provided all the
        !           273: functions in the chapter of lists, mainly because some of them could be
        !           274: implemented correctly only if keyword arguments were supported.
        !           275: That explains why I haven't rushed to provide
        !           276: @code{subst}, @code{sublis}, etc.  Also, that explains the rather
        !           277: temporary nature of the implementation of @code{member} and
        !           278: @code{adjoin}.  I will welcome any efforts to extend
        !           279: this work. @refill
        !           280: 
        !           281: @subsection Features Provided
        !           282: 
        !           283: @table @code
        !           284: @item endp
        !           285: @itemx list*
        !           286: @itemx list-length
        !           287: Very standard utilities.  List* has proven especially useful to
        !           288: overcome the lack of a real @code{backquote}.  In addition, things that
        !           289: usually required the relatively clumsy
        !           290: @example
        !           291: (cons 'a (cons 'b oldlist))
        !           292: (append (list a b) oldlist)
        !           293: @end example
        !           294: can now be simply put:
        !           295: @example
        !           296: (list* 'a 'b oldlist)
        !           297: @end example
        !           298: See also @code{acons}.
        !           299: 
        !           300: @item member
        !           301: Another well known function.  Supports test with @code{eql} only.
        !           302: 
        !           303: @item acons
        !           304: @itemx pairlis
        !           305: These two are part of the standards association lists implementation.  I
        !           306: am leaving @code{sublis} as an exercise for the reader.
        !           307: 
        !           308: @item adjoin
        !           309: Done mainly for the sake of @code{pushnew}.
        !           310: 
        !           311: @item butlast
        !           312: @itemx last
        !           313: @itemx ldiff
        !           314: Occasionally useful ways to access the last cons or a specified tail of
        !           315: a list.  I don't remember why there isn't a @code{tailp} here.
        !           316: 
        !           317: @item c[ad][ad][ad][ad]r, up to four a's or d's
        !           318: These 28 functions (and their setf inverses) have been provided once and
        !           319: for all.  Many packages contributed to Emacs Lisp contain macros that
        !           320: implement some of these, I think this code will make most of them
        !           321: unnecessary. 
        !           322: 
        !           323: @item first
        !           324: @itemx rest
        !           325: @itemx second
        !           326: @itemx third
        !           327: @itemx fourth
        !           328: @itemx fifth
        !           329: @itemx sixth
        !           330: @itemx seventh
        !           331: @itemx eighth
        !           332: @itemx ninth
        !           333: @itemx tenth
        !           334: More standard accessors (and their setf inverses).  Not particularly
        !           335: useful but easy to provide.
        !           336: 
        !           337: @item setnth
        !           338: @itemx setnthcdr
        !           339: These functions are non-standard.  They are here for @code{defsetf}
        !           340: purposes only, but they might be useful on their own.
        !           341: 
        !           342: @end table
        !           343: 
        !           344: @node Sequences, Conditionals, Lists, Top
        !           345: @section Sequences
        !           346: 
        !           347: Sequences are partly supported in Emacs Lisp (see, for instance, the
        !           348: @code{elt} function).  This limited support is compatible with Common
        !           349: Lisp, so it should be easy to extend.  However, the lack of
        !           350: keyword arguments makes many of the functions impossible so far (but, as
        !           351: mentioned below, a basic framework for that extension
        !           352: is provided here). @refill
        !           353: 
        !           354: The functionality really provided here is given by the functions
        !           355: (essentially, predicates) @code{every}, @code{some}, @code{notevery},
        !           356: @code{notany}.  I have found them useful countless times, so I thought
        !           357: to provide them before anything else. @refill
        !           358: 
        !           359: That still leaves many omissions, though.
        !           360: 
        !           361: @subsection Features Provided
        !           362: 
        !           363: @table @code
        !           364: @item every
        !           365: @itemx notany
        !           366: @itemx notevery
        !           367: @itemx some
        !           368: Extremely useful functions.  If your favorite Lisp doesn't have them,
        !           369: you are missing a lot.
        !           370: 
        !           371: @item setelt
        !           372: A setf-inverse to @code{elt}.
        !           373: 
        !           374: @item add-to-klist
        !           375: @itemx build-klist
        !           376: @itemx extract-from-klist
        !           377: A @dfn{klist} is just an alist whose keys are keywords.  I based the
        !           378: pseudo-keyword argument support of @code{defstruct} on this idea, but
        !           379: their best fit is here, as they could help to write the remaining
        !           380: sequence-handling functions (@code{find}, @code{substitute}, @dots{})
        !           381: that I didn't provide for the lack of a good keyword
        !           382: arguments mechanism. @refill
        !           383: 
        !           384: @item elt-satisfies-if-not-p
        !           385: @itemx elt-satisfies-if-p
        !           386: @itemx elt-satisfies-test-p
        !           387: @itemx elts-match-under-klist-p
        !           388: The Common Lisp book defines some of the semantics of sequence functions
        !           389: in terms of satisfaction of certain tests.  These predicates provide
        !           390: that functionality, but I haven't integrated them with the rest of the
        !           391: extensions.  However, I thought it was better to include them anyway, as
        !           392: they can serve somebody else as a starting point.
        !           393: 
        !           394: @end table
        !           395: 
        !           396: 
        !           397: @node Conditionals, Iterations, Sequences, Top
        !           398: @section Conditionals
        !           399: 
        !           400: An elementary incompatibility prevents us from producing true Common
        !           401: Lisp here.  The @code{if} forms are different.  In Emacs Lisp, @code{if}
        !           402: can take any number of subforms, there being a @var{condition} form, a
        !           403: @var{then} form, and after them any number of @var{else} subforms,
        !           404: which are executed in an implicit @code{progn}.  Moreover, that style is
        !           405: widely used in the Emacs sources, so I thought most impractical to break
        !           406: with 
        !           407: it to support Common Lisp's @code{if} (where only one @var{else} form is
        !           408: tolerated).  For the most part, I use @code{cond} almost always, so it
        !           409: doesn't bother me much.  If you use single-branch @code{if}s often,
        !           410: consider @code{when} or @code{unless} as alternatives.  @refill
        !           411: 
        !           412: @code{case} and @code{ecase} are a convenient way to write things that
        !           413: usually end up in a very baroque @code{cond}.  
        !           414: 
        !           415: @subsection Features Provided
        !           416: 
        !           417: @table @code
        !           418: @item MACRO case
        !           419: @itemx MACRO ecase
        !           420: @itemx MACRO unless
        !           421: @itemx MACRO when
        !           422: The standard stuff, completely implemented.
        !           423: @end table
        !           424: 
        !           425: @node Iterations, Multiple Values, Conditionals, Top
        !           426: @section Iterations
        !           427: 
        !           428: Having a @code{do} macro was my original motivation.  The alternatives
        !           429: in standard Emacs Lisp are either expensive (recursion) or correspond
        !           430: directly to the expansion of my macros:
        !           431: @example
        !           432:  (macroexpand '
        !           433:   (do ((i 0) (j 1 (+ 1 j)))
        !           434:       ((> j (foo i)) (cons i bar))
        !           435:     (setq i (baz i j))))
        !           436: 
        !           437: (let ((i 0) (j 1))
        !           438:   (while (not (> j (foo i)))
        !           439:     (setq i (baz i j))
        !           440:     (psetq j (+ 1 j)))
        !           441:   (cons i bar))
        !           442: @end example
        !           443: So I prefer to leave to the macros the problem of remembering the
        !           444: details right.
        !           445: 
        !           446: The incompatibilities are due to the problems already discussed
        !           447: (@pxref{Generalities}, for more details). @refill
        !           448: 
        !           449: If you write Emacs Lisp code often, you will find enough uses for these.
        !           450: Examples are cooking up a translation table to move @key{C-s} out of the
        !           451: way of multiplexers, switches, concentrators and similar fauna, or
        !           452: building keymaps.  @refill
        !           453: 
        !           454: @subsection Features Provided
        !           455: 
        !           456: @table @code
        !           457: @item MACRO do
        !           458: @itemx MACRO do*
        !           459: @itemx MACRO dolist
        !           460: @itemx MACRO dotimes
        !           461: The standard, but for the lack of implicit blocks.
        !           462: 
        !           463: @item MACRO loop
        !           464: The basic standard one, not the fancy one.  As per the book, warns you
        !           465: about atomic entries at the surface of the macro (to guarantee that the
        !           466: fancy @code{loop} macros can be made standard later).
        !           467: 
        !           468: @item MACRO do-all-symbols
        !           469: @itemx MACRO do-symbols
        !           470: These operate on obarrays, the default is the current one.
        !           471: 
        !           472: @end table
        !           473: 
        !           474: @node Multiple Values, Integer Arithmetic, Iterations, Top
        !           475: @section Multiple Values
        !           476: 
        !           477: The multiple values mechanism covers (simply and elegantly, in my
        !           478: opinion) various common needs:
        !           479: 
        !           480: @enumerate
        !           481: @item
        !           482: The case where a function returns a composite value, that has to be
        !           483: assembled in the callee and disassembled in the caller.  An example is
        !           484: @code{pair-with-newsyms}.
        !           485: @item
        !           486: The case where a function might cheaply compute redundant information
        !           487: that is useful to the caller only eventually.  For instance, routines
        !           488: that compute quotients and remainders together, whose callers might be
        !           489: more often interested in just receiving the quotient.
        !           490: @item
        !           491: The case of functions that usually return a useful value, but might need
        !           492: to elaborate on occasion (say, returning a reason code too).
        !           493: @end enumerate
        !           494: 
        !           495: The general idea is that one such function @i{always} returns the extra
        !           496: values, but only callers that are aware of this ability receive them.
        !           497: Unaware callers just receive the first value.
        !           498: 
        !           499: I think my implementation is pretty much complete.  I am imposing no
        !           500: limits on the number of multiple values a function may return, so
        !           501: I am not providing the constant @code{multiple-values-limit}.  You can
        !           502: assume multiple values are bound by the memory 
        !           503: size only. @refill
        !           504: 
        !           505: @subsection Features Provided
        !           506: 
        !           507: @table @code
        !           508: @item values
        !           509: @itemx values-list
        !           510: These are the forms that produce multiple values.
        !           511: 
        !           512: @item MACRO multiple-value-bind
        !           513: @itemx MACRO multiple-value-call
        !           514: @itemx MACRO multiple-value-list
        !           515: @itemx MACRO multiple-value-prog1
        !           516: @itemx MACRO multiple-value-setq
        !           517: These are the forms that receive multiple values.
        !           518: 
        !           519: @item VARIABLE *mvalues-count*
        !           520: @itemx VARIABLE *mvalues-values*
        !           521: Used by the implementation.  Don't touch them!
        !           522: 
        !           523: @end table
        !           524: 
        !           525: @node Integer Arithmetic, Generalized Variables, Multiple Values, Top
        !           526: @section Integer Arithmetic
        !           527: 
        !           528: I have provided most of the functions that are supposed to act on
        !           529: integers.  Of those that take arbitrary numbers, I have implemented
        !           530: those that have a reasonable implementation if restricted to integers
        !           531: only, although some more could be added (like a restricted form of
        !           532: @code{expt}).
        !           533: 
        !           534: Being a little worried about the bad fame that affects some
        !           535: implementations of the '%' C operator, I have taken perhaps unnecessary
        !           536: precautions whenever integer division is concerned (see the function
        !           537: @code{safe-idiv}).  This should be of interest only when dividing
        !           538: numbers that might be negative, but I have preferred here to be safe
        !           539: rather than fast.  @refill
        !           540: 
        !           541: @subsection Features Provided
        !           542: 
        !           543: @table @code
        !           544: @item abs
        !           545: @itemx signum
        !           546: The usual.
        !           547: 
        !           548: @item gcd
        !           549: @itemx lcm
        !           550: The usual.
        !           551: 
        !           552: @item isqrt
        !           553: A rather annoying function.  Only use I can think of: to cut short a
        !           554: prime number sieve.
        !           555: 
        !           556: @item evenp
        !           557: @itemx oddp
        !           558: @itemx plusp
        !           559: @itemx minusp
        !           560: A few predicates that use to come handy.
        !           561: 
        !           562: @item ceiling
        !           563: @itemx floor
        !           564: @itemx round
        !           565: @itemx truncate
        !           566: @itemx mod
        !           567: @itemx rem
        !           568: The intention is to give everybody his preferred way to divide integers.
        !           569: I have tried not to depend on the unreliable semantics of C's integer
        !           570: division, I hope I got it right.  Read the code when in doubt.
        !           571: 
        !           572: @end table
        !           573: 
        !           574: @node Generalized Variables, Structures, Integer Arithmetic, Top
        !           575: @section Generalized Variables
        !           576: 
        !           577: This implementation has many limitations.  Take a look to see if you
        !           578: want to overcome them, the fixes might prove unnecessarily expensive for
        !           579: Emacs purposes.  The ones I am clearly aware of:
        !           580: 
        !           581: @enumerate
        !           582: @item
        !           583: Common Lisp suggests an underlying mechanism (the setf-methods) to
        !           584: implement generalized variables.  I have used ad-hoc ideas that gave me
        !           585: a rather trivial implementation 
        !           586: that suffers from some inflexibility.  As a result, @code{defsetf}
        !           587: only admits the simplest form and there is no @code{define-modify-macro}
        !           588: nor there are functions to handle the (nonexistent) setf-methods. @refill
        !           589: @item
        !           590: I haven't implemented (I was uninterested) @code{getf} and friends.
        !           591: This shouldn't be hard.
        !           592: @end enumerate
        !           593: 
        !           594: In addition to providing this mechanism, I have written @code{defsetf}s
        !           595: for almost every accessor I thought of.  There is room for improvement
        !           596: here, as Emacs Lisp provides many types of its own (buffers, windows,
        !           597: keymaps, syntax tables, @dots{}) for which pairs of accessors and
        !           598: mutators could be defined.
        !           599: 
        !           600: If you want to check whether a function has a setf-inversor, look at the
        !           601: property `:setf-update-fn' of its name.  This is a characteristic of my
        !           602: implementation, not mandated by Common Lisp, so you
        !           603: shouldn't use it in code, but only to determine interactively what can
        !           604: be setf'd.  @refill
        !           605: 
        !           606: @subsection Features Provided
        !           607: 
        !           608: @table @code
        !           609: @item MACRO setf
        !           610: @itemx MACRO psetf
        !           611: Almost complete implementation.  @code{Setf} should handle @code{apply}
        !           612: inside itself and not in a @code{defsetf}, but the difference is so
        !           613: minute I feel lazy about fixing this. @code{Psetf} is the version where
        !           614: the assignments occur in parallel. @refill
        !           615: 
        !           616: @item MACRO defsetf
        !           617: Very sketchy implementation.  I will appreciate if somebody puts some
        !           618: time in implementing the whole works of setf-methods and such.
        !           619: 
        !           620: @itemx MACRO incf
        !           621: @itemx MACRO decf
        !           622: The usual and standard.
        !           623: 
        !           624: @item MACRO pop
        !           625: @itemx MACRO push
        !           626: @itemx MACRO pushnew
        !           627: Should be the usual, but I haven't had the time to test them properly. 
        !           628: 
        !           629: @item MACRO rotatef
        !           630: @itemx MACRO shiftf
        !           631: Very fancy.  Good for implementing history rings and such.
        !           632: To swap two values, the following forms are equivalent:
        !           633: @example
        !           634: (rotatef a b)
        !           635: (psetf a b b a)
        !           636: (psetq a b b a)  ;not good for anything but variables
        !           637: @end example
        !           638: 
        !           639: @end table
        !           640: 
        !           641: @node Structures, Miscellanea, Generalized Variables, Top
        !           642: @section Structures
        !           643: 
        !           644: I haven't had the time to construct a complete implementation of
        !           645: structures, but the part provided should stand on its own for many
        !           646: purposes.  I am not supporting `BOA constructors', nor typed slots (the
        !           647: @code{:type}, @code{:named} and @code{:initial-offset} options), nor
        !           648: explicit representational types.  The rest should be
        !           649: pretty much complete.  See the example file @file{fractions.el} for an
        !           650: idea of how complete the implementation is, and for exercises. @refill
        !           651: 
        !           652: When writing these functions, I noticed I was incurring in lots of
        !           653: auxiliaries.  I used dollar signs in their names, in the hope that this
        !           654: could prevent clashes with user functions.  In retrospect, I should have
        !           655: done it in the other sections, too.
        !           656: 
        !           657: 
        !           658: @subsection Features Provided
        !           659: 
        !           660: @table @code
        !           661: @item MACRO defstruct
        !           662: Create records (a la C structs) and use them as types in your programs.
        !           663: Almost completely standard.
        !           664: 
        !           665: @item make$structure$instance
        !           666: This non-standard function implements most of the `guts' of the `make-'
        !           667: constructors.  It can be used as an example of the pseudo
        !           668: keyword-arguments.  
        !           669: @end table
        !           670: 
        !           671: @node Miscellanea, To Do, Structures, Top
        !           672: @section Miscellanea
        !           673: 
        !           674: @subsection Features Provided
        !           675: 
        !           676: @table @code
        !           677: @item MACRO psetq
        !           678: A parallel-assignments version of @code{setq}, makes the expansions of
        !           679: @code{do} and @code{do*} be very similar, as they should.  Otherwise
        !           680: used to swap two values, now superseded by @code{rotatef}. @refill
        !           681: 
        !           682: @item duplicate-symbols-p
        !           683: @itemx pair-with-newsyms
        !           684: @itemx reassemble-argslists
        !           685: @itemx unzip-list
        !           686: @itemx zip-lists
        !           687: These are utilities I find useful when parsing a call or generating code
        !           688: inside a macro.  Non standard.
        !           689: @end table
        !           690: 
        !           691: @node To Do, , Miscellanea, Top
        !           692: @section To Do
        !           693: 
        !           694: No doubt many people will like to extend the functionality of these
        !           695: routines.  When considering doing so, please try and do it in such a way
        !           696: that your implementation of a subset of the functionality of Common Lisp
        !           697: is not inimical with a more extensive or more correct one.  For
        !           698: definiteness, ask yourself the questions:
        !           699: 
        !           700: @itemize @bullet
        !           701: @item
        !           702: Will my code run under a correct implementation of Common Lisp?
        !           703: @item
        !           704: Will a correct implementation of Common Lisp run if my code is loaded?
        !           705: @end itemize
        !           706: @noindent
        !           707: 
        !           708: The first question tests the pertinence of your extensions.  The second
        !           709: tries to discover ``extensions'' that prevent correct implementations of
        !           710: other features.  Please tell me if you notice a case in which my code
        !           711: fails to pass any of those tests.
        !           712: 
        !           713: The next subsections propose some more extensions.  I hope that they are
        !           714: attempted by people learning Lisp, as a way to enhance their
        !           715: understanding.  Of course, experts are also admitted. @refill
        !           716: 
        !           717: @subsection Keyword Arguments
        !           718: 
        !           719: Some effort has been done to handle keywords almost right.  For
        !           720: instance, a structure constructor (@pxref{Structures}) can be invoked
        !           721: with keyword arguments.
        !           722: 
        !           723: Look for the functions whose names have a @samp{klist} in them.  They
        !           724: were written to facilitate parsing calls with keyword arguments, but I
        !           725: haven't done a complete implementation yet.  (Note that @code{member},
        !           726: @code{assoc} and perhaps some other function, have to be implemented
        !           727: independently of the general framework.  More details by Email if you
        !           728: want to try 
        !           729: your hand at this.) @refill
        !           730: 
        !           731: @subsection Mapping Functions
        !           732: 
        !           733: There is enough support to write @code{maplist}, @code{mapl}, etc.  Emacs
        !           734: Lisp already provides some of the mapping functions, the trick now is to
        !           735: code the rest in a very efficient manner, so there will be an incentive
        !           736: to use @code{maplist} over an explicit iteration.  I have a draft
        !           737: implementation, but I don't have the time to test it now.
        !           738: 
        !           739: @subsection Complete the current implementation
        !           740: 
        !           741: Some of the features described above are only a partial implementation
        !           742: of the Common Lisp features.  Things that cry for a more complete form:
        !           743: 
        !           744: @table @code
        !           745: @item defsetf
        !           746: Only the simplest format is supported.  The most general one is needed
        !           747: too.  Also, try to get @code{define-setf-method} and
        !           748: @code{get-setf-method} to work. @refill
        !           749: @item define-modify-macro
        !           750: Same as above.  The modify-macros provided are all ad hoc.
        !           751: @item defstruct
        !           752: I think my version recognizes all the options and then proceeds to
        !           753: ignore most of them.  Making sure that at least good error messages are
        !           754: produced would be nice.  Also, what about BOA constructors?
        !           755: @end table
        !           756: 
        !           757: There are other places where your programming ingenuity would help us
        !           758: all.  For instance, @code{subst}, @code{sublis} and the like could be
        !           759: easily provided in the @var{lists} section.  (I haven't done it because
        !           760: I wanted to have the keyword arguments stuff first.) @refill
        !           761: 
        !           762: @subsection Hash Tables
        !           763: 
        !           764: A very simple implementation of hash tables would admit only strings as
        !           765: keys.  For each string and a given number of buckets (a prime is
        !           766: desirable here), add the numeric values of all (or of a reasonable
        !           767: subset) of the characters and assign the bucket whose index is the
        !           768: remainder of the sum modulo the (prime) number of buckets.
        !           769: 
        !           770: A more convenient implementation can then be based on using
        !           771: @code{prin1-to-string} on an arbitrary Lisp object and using the output
        !           772: string as a key. This should make it easy to write @code{sxhash}.
        !           773: Remember that one needs to ensure that @code{(equal x y)} should imply
        !           774: that @w{@code{(= (sxhash x) (sxhash y))}}; and also that the keys are
        !           775: state-less (so you can write them to a 
        !           776: file and read them back later). @refill
        !           777: 
        !           778: Don't forget to provide a @code{defsetf} for @code{gethash}.
        !           779: 
        !           780: @subsection Packages
        !           781: 
        !           782: Packages should be easy to implement on top of a good hash table
        !           783: implementation, either by using it directly or by reusing some shared
        !           784: code.  Don't worry too much about efficiency: package qualification has
        !           785: no run-time cost, only read- and print-time costs.
        !           786: 
        !           787: The difficult thing is to integrate it correctly.  You have to replace
        !           788: the built-in functions @code{read} and @code{write}.  This is not as bad
        !           789: as writing a programmable reader, but still a pain.  For starters, your
        !           790: routines could remember the default definitions of the above mentioned
        !           791: functions: @refill
        !           792: 
        !           793: @example
        !           794: (setf def-reader  (symbol-function 'read))
        !           795: (setf def-printer (symbol-function 'print))
        !           796: @dots{}
        !           797: @end example
        !           798: 
        !           799: And then your specialized functions could just use @code{apply} to
        !           800: exercise the default ones, intercepting their activity in time to do the
        !           801: package qualification.  You might have to do this to @code{prin1},
        !           802: @code{prin1-to-string} and friends. @refill
        !           803: 
        !           804: @subsection Streams and Files
        !           805: 
        !           806: This is the first ``To Do'' that might require doing some C programming.
        !           807: The purpose is to construct an efficient byte stream abstraction that
        !           808: will allow Streams and Files to be handled.  Think of stdio, not Unix
        !           809: I/O, because Emacs already runs under other operating systems.  Also,
        !           810: think of doing it in a way that can be generalized easily (for instance,
        !           811: streams kept in memory without a file behind, streams as an interface to
        !           812: a windowing system, etc.)  Of course, the intended syntax is that of
        !           813: Common Lisp.
        !           814: 
        !           815: @subsection Reader and Printer
        !           816: 
        !           817: The Emacs Lisp reader (the C function @code{Fread}) is not reentrant nor
        !           818: programmable.  It could be fixed as Lisp Code, but that is probably
        !           819: uglily expensive (as bad as redoing @code{eval} and @code{apply} to
        !           820: support lexical scoping).  Doing this  extension is probably a bad
        !           821: idea: a Common Lisp reader is incompatible with Emacs Lisp code (because
        !           822: of the @samp{?\} constructions) and the most important rule to keep in
        !           823: mind is that this code is running under Emacs, so the host shouldn't be
        !           824: burdened too much with these emulations.  Same goes for a more complete
        !           825: printer (a Common Lisp @code{format} would be incompatible with the
        !           826: Emacs Lisp one). @refill
        !           827: 
        !           828: @subsection Backquote
        !           829: Even if the reader is not made programmable nor reentrant, a backquoting
        !           830: mechanism could come handy.  You need to study the way the current
        !           831: reader does @code{quote} and hack from there.  This might be a more
        !           832: worthwhile extension than the complete rewrite of the reader.
        !           833: 
        !           834: @subsection Wild Ideas
        !           835: Perhaps there is a way to implement @code{block}, @code{tagbody},
        !           836: @code{return} and friends in spite of the dynamic scoping of Emacs Lisp.
        !           837: By this, I mean an adequate definition that preserves remotely the
        !           838: original intent and still provides a sensible set of constructs.  Other
        !           839: dynamically scoped Lisps have these features, so implementing them is
        !           840: not necessarily impossible.
        !           841: 
        !           842: In the same spirit of these extensions would be to provide a port of
        !           843: something like Flavors 
        !           844: (was there a PD version from Maryland, for Franz perhaps?) and then
        !           845: rephrase the language of major and minor modes in an Object Oriented
        !           846: paradigm. @refill
        !           847: 
        !           848: Also, the rather gross @code{loop} macros that are out there in many
        !           849: Lisp systems could be helpful to some
        !           850: people (but then think of a @code{lisp-indent-hook} that handles them
        !           851: properly). @refill
        !           852: 
        !           853: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.