

                                                               encapsulated


    MACRO
ENCAPSULATED ENCAPSULATING-FN SCANNER-OR-COLLECTOR                  [Macro]

    Package
    series

    DESCRIPTION

Some of the features provided by Common Lisp are supported solely by
encapsulating forms.  For example, there is no way to specify a cleanup
expression that will always be run, even when an abort occurs, without
using UNWIND-PROTECT.  ENCAPSULATED makes it possible to take advantage of
forms such as UNWIND-PROTECT when defining a series function.

ENCAPSULATED specifies a function that places an encapsulating form around
the computation performed by its second argument.  The first argument must
be a quoted function that takes a Lisp expression and wraps the appropriate
encapsulating form around it, returning the resulting code.  The second
input must be a literal call on SCAN-FN, SCAN-FN-INCLUSIVE, or COLLECT-FN.
The second argument can count on being evaluated in the scope of the
encapsulating form.  The values returned by the second argument are
returned as the values of ENCAPSULATED.  The following shows how
ENCAPSULATED could be used to define a simplified version of COLLECT-FILE.

(DEFUN COLLECT-FILE-WRAP (FILE NAME BODY) 
  `(WITH-OPEN-FILE (,FILE ,NAME :DIRECTION :OUTPUT) ,BODY)) 

(DEFMACRO SIMPLE-COLLECT-FILE (NAME ITEMS) 
  (LET ((FILE (GENSYM))) 
    `(ENCAPSULATED #'(LAMBDA (BODY) 
                       (COLLECT-FILE-WRAP ',FILE ',NAME BODY)) 
                   (COLLECT-FN T #'(LAMBDA () T) 
                               #'(LAMBDA (STATE ITEM) 
                                   (PRINT ITEM ,FILE) 
                                   STATE) 
                               ,ITEMS))))


     SEE ALSO
     about-series
     about-generators

;Copyright 1989 by the Massachusetts Institute of Technology,
;Cambridge, Massachusetts.

;Permission to use, copy, modify, and distribute this software and its
;documentation for any purpose and without fee is hereby granted,
;provided that this copyright and permission notice appear in all
;copies and supporting documentation, and that the name of M.I.T. not
;be used in advertising or publicity pertaining to distribution of the
;software without specific, written prior permission. M.I.T. makes no
;representations about the suitability of this software for any
;purpose.  It is provided "as is" without express or implied warranty.

;    M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
;    ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
;    M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
;    ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
;    WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
;    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
;    SOFTWARE.



