Procedures and Macros
*********************

Lambda: Basic Procedure Creation
================================

Optional Arguments
==================

Procedure Properties and Metainformation
========================================

 -- primitive: procedure-properties proc
     Return OBJ's property list.

 -- primitive: procedure-property p k
     Return the property of OBJ with name KEY.

 -- primitive: set-procedure-properties! proc new_val
     Set OBJ's property list to ALIST.

 -- primitive: set-procedure-property! p k v
     In OBJ's property list, set the property named KEY to VALUE.

 -- primitive: procedure-documentation proc
     Return the documentation string associated with proc.  By convention, if a procedure contains more than one expression and the first expression is a string constant, that string is assumed to contain documentation for that procedure.

 -- primitive: closure? obj
     Return #t if OBJ is a closure.

 -- primitive: procedure? obj
     Return #t if OBJ is a procedure.

 -- primitive: thunk? obj
     Return #t if OBJ is a thunk.

 -- primitive: set-source-properties! obj plist
     Install the association list PLIST as the source property list for OBJ.

 -- primitive: set-source-property! obj key datum
     Set the source property of object OBJ, which is specified by KEY to DATUM.  Normally, the key will be a symbol.

 -- primitive: source-properties obj
     Return the source property association list of OBJ.

 -- primitive: source-property obj key
     Return the source property specified by KEY from OBJ's source property list.

Procedures with Setters
=======================

 -- primitive: make-procedure-with-setter procedure setter
     Create a new procedure which behaves like PROCEDURE, but with the associated setter SETTER.

 -- primitive: procedure-with-setter? obj
     Return #t if OBJ is a procedure with an associated setter procedure.

 -- primitive: procedure proc
     Return the procedure of PROC, which must be either a procedure with setter, or an operator struct.

 -- primitive: setter proc

Macros
======

[FIXME: This needs some more text on the difference between procedures, macros and memoizing macros.  Also, any definitions listed here should be double-checked by someone who knows what's going on.  Ask Mikael, Jim or Aubrey for help. -twp]

 -- primitive: procedure->syntax code
     Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, returns the result of applying CODE to the expression and the environment.

 -- primitive: procedure->macro code
     Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the result of applying CODE to the expression and the environment.  The value returned from CODE which has been passed to procedure->memoizing-macro replaces the form passed to CODE.  For example:

          (define trace
            (procedure->macro
             (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

          (trace foo) == (set! foo (tracef foo 'foo)).

 -- primitive: procedure->memoizing-macro code
     Return a macro which, when a symbol defined to this value appears as the first symbol in an expression, evaluates the result of applying PROC to the expression and the environment.  The value returned from PROC which has been passed to procedure->memoizing-macro replaces the form passed to PROC.  For example:

          (define trace
            (procedure->macro
             (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

          (trace foo) == (set! foo (tracef foo 'foo)).

 -- primitive: macro? obj
     Return #t if OBJ is a regular macro, a memoizing macro or a syntax transformer.

 -- primitive: macro-type m
     Return one of the symbols syntax, macro or macro!, depending on whether M is a syntax tranformer, a regular macro, or a memoizing macro, respectively.  If M is not a macro, #f is returned.

 -- primitive: macro-name m
     Return the name of the macro M.

 -- primitive: macro-transformer m
     Return the transformer of the macro M.

 -- primitive: cons-source xorig x y
     Create and return a new pair whose car and cdr are X and Y. Any source properties associated with XORIG are also associated with the new pair.