Issue SYNTACTIC-ENVIRONMENT-ACCESS

[Kim A. Barrett <IIM%ECLA@ECLC.USC.EDU>]

Issue:          SYNTACTIC-ENVIRONMENT-ACCESS
References:     CLtL Chapter 8: Macros,
                Issue MACRO-FUNCTION-ENVIRONMENT,
                Issue GET-SETF-METHOD-ENVIRONMENT,
                Issue COMPILE-FILE-ENVIRONMENT
Related Issues: Issue FUNCTION-NAME,
		Issue PROCLAIM-LEXICAL
Category:       ADDITION
Edit history:   Version 1, 2-Oct-88, Eric Benson
                Version 2, 17-Feb-89, Kim A. Barrett
Status:         For internal discussion

Problem description:

 When macro forms are expanded, the expansion function is called with two
 arguments: the form to be expanded, and the environment in which the form was
 found.  The environment argument is of limited utility.  The only use
 sanctioned currently is as an argument to MACROEXPAND or MACROEXPAND-1 or
 passed directly as an argument to another macro expansion function.  Recent
 cleanup issues propose to allow it as an argument to MACRO-FUNCTION and to
 GET-SETF-METHOD.

 Implementing the FIND-CLASS and ENSURE-GENERIC-FUNCTION functions of CLOS
 requires the ability to distinguish between environments used for compiling to
 a file from those used for processing in-core, such as by EVAL or COMPILE.
 Resolution of the LOAD-TIME-EVAL issue may also require this information.
 This problem has been addressed by the recent cleanup issue
 COMPILE-FILE-ENVIRONMENT.  Also, it has proven impossible to write a portable
 code walker in Common Lisp, due to insufficient access to the information
 contained in environments and the inability to augment environments with local
 function definitions.

Proposal (SYNACTIC-ENVIRONMENT-ACCESS:ADD-FUNCTIONAL-INTERFACE):

 The following functions provide information about syntactic environment
 objects.  In all of the functions the argument named ENV is a environment, of
 the sort received by the &ENVIRONMENT argument to a macro, or as the
 environment argument for EVALHOOK.  In all cases it is an error to supply an
 argument which is not a syntactic environment.

 ENVIRONMENT-TARGET env                         [Function]

  This function returns one of the three symbols :EVAL, :COMPILE or
  :COMPILE-FILE, depending on whether the environment is from the interpreter,
  the in-core compiler, or the file compiler.  If MACROEXPAND or MACROEXPAND-1
  is called directly without supplying the environment argument, the
  environment passed to any expander functions will have target :EVAL.

 ENVIRONMENT-VARIABLE-KIND variable env         [Function]

  VARIABLE is a symbol.  This function returns one of the folloing symbols,
  depending on the type of definition or binding which is apparent in ENV.

    NIL            There is no apparent definition or binding for variable.
    :SPECIAL       VARIABLE refers to a special variable, either declared or
                   proclaimed. 
    :LEXICAL       VARIABLE refers to a lexical variable.
    :SYMBOL-MACRO  VARIABLE refers to a SYMBOL-MACROLET binding.
    :CONSTANT      VARIABLE refers to a named constant, defined by DEFCONSTANT.

 [Note: If issue PROCLAIM-LEXICAL passes, then the :LEXICAL result will also
  refer to variables proclaimed lexical.] 

 Example:

  (DEFMACRO KIND-OF-VARIABLE (VAR &ENVIRONMENT ENV)
    `',(ENVIRONMENT-VARIABLE-KIND VAR ENV))

  (DEFVAR A)

  (DEFUN TEST ()
    (LET (B)
      (LET (C)
        (DECLARE (SPECIAL C))
        (SYMBOL-MACROLET ((D ANYTHING))
          (LIST (KIND-OF-VARIABLE A)
                (KIND-OF-VARIABLE B)
                (KIND-OF-VARIABLE C)
                (KIND-OF-VARIABLE D)
                (KIND-OF-VARIABLE E))))))

  (TEST) -> (:SPECIAL :LEXICAL :SPECIAL :SYMBOL-MACRO NIL)
      

 ENVIRONMENT-FUNCTION-KIND function env         [Function]

  FUNCTION is a function name.  This function returns two values, depending on
  the type of function definition or function binding which is apparent for
  FUNCTION in ENV.

    NIL            There is no apparent definition for FUNCTION.
    :FUNCTION      FUNCTION refers to a function.
    :MACRO         FUNCTION refers to a macro.
    :SPECIAL-FORM  FUNCTION refers to a special-form.

  The second value specifies whether the definition is local or global.  If
  local, the second value is true, and it is false when the definition is
  global. 

  Some function names may refer to both a global macro and a global special
  form.  In such a case, the macro takes precedence, and :MACRO is returned as
  the first value.

  [Note: The use of "function name" rather than "symbol" as the description of
   the function argument is intended to be compatible with the various proposals
   to extend the syntax of function specifiers.  If no such change actually
   occurs then this would only refer to symbols.]

 Example:

  (DEFMACRO KIND-OF-FUNCTION (FUNCTION-NAME &ENVIRONMENT ENV)
    `',(ENVIRONMENT-FUNCTION-KIND FUNCTION-NAME ENV))

  (DEFUN A ())

  (DEFMACRO B ())

  (DEFUN TEST ()
    (FLET ((C ()))
      (MACROLET ((D ()))
        (MULTIPLE-VALUE-CALL #'LIST
              (KIND-OF-FUNCTION A)
              (KIND-OF-FUNCTION B)
              (KIND-OF-FUNCTION QUOTE)
              (KIND-OF-FUNCTION C)
              (KIND-OF-FUNCTION D)
              (KIND-OF-FUNCTION E)))))

  (TEST) -> (:FUNCTION      NIL
             :MACRO         NIL
             :SPECIAL-FORM  NIL
             :FUNCTION      T
             :MACRO         T
             NIL            NIL)

 ENVIRONMENT-TYPE variable env                  [Function]

  VARIABLE is a symbol.  This function returns the type specifier
  associated with the variable named by the symbol in the environment.
  If no explicit association exists, either by PROCLAIM or DECLARE, then
  the result is the type specifier T.

 Example:

  (DEFMACRO VARTYPE (VAR &ENVIRONMENT ENV)
    `',(ENVIRONMENT-VARIABLE-TYPE VAR ENV))

  (DEFVAR A 1)

  (PROCLAIM '(FIXNUM A))

  (DEFUN TEST ()
    (LET ((B (AREF "X" 0))
          (C 3))
      (DECLARE (STRING-CHAR B))
      (LIST (VARTYPE A) (VARTYPE B) (VARTYPE C))))

  (TEST) -> (FIXNUM STRING-CHAR NIL)

 ENVIRONMENT-FTYPE function env                 [Function]

  FUNCTION is a function name.  This function returns the functional type
  specifier associated with the function in the environment, or NIL if there is
  no functional type declaration or proclamation associated with the function.

 Example:

  (DEFMACRO FUNTYPE (FUN &ENVIRONMENT ENV)
    `',(ENVIRONMENT-FTYPE FUN ENV))

  (DEFUN A-FUNCTION (X)
    (+ X 3))

  (PROCLAIM '(FTYPE (FUNCTION (FIXNUM) FIXNUM) A-FUNCTION))

  (DEFUN TEST ()
    (FLET ((ANOTHER-FUNCTION (X)
             (+ X 2)))
      (DECLARE (FTYPE (FUNCTION (INTEGER) INTEGER) ANOTHER-FUNCTION))
      (LIST (FUNTYPE A-FUNCTION) (FUNTYPE ANOTHER-FUNCTION))))

  (TEST) -> ((FUNCTION (FIXNUM) FIXNUM) (FUNCTION (INTEGER) INTEGER))

 AUGMENT-ENVIRONMENT env &KEY lexical
                              special
			      symbol-macro
                              function
                              macro
                              type
                              ftype		[Function]

  This function returns a new environment augmented with the information
  provided by the keyword arguments.  The arguments are supplied as follows:

  :LEXICAL	A list of symbols which shall be visible as lexical variables
		in the new environment. 

  :SPECIAL	A list of symbols which shall be visible as dynamic variables
		in the new environment.

  :SYMBOL-MACRO An alist of symbols and macroexpansion functions.  The new
		environment will have local symbol-macro bindings of each
		symbol to the corresponding expander function, so that 
		MACROEXPAND will be able to expand them properly.

  :FUNCTION	A list of function names which shall be visible as local
		function bindings in the new environment.

  :MACRO	An alist of function names and macroexpansion functions.  The
		new environment will have local macro bindings of each name to
		the corresponding expander function, which will be returned by
		MACRO-FUNCTION and used by MACROEXPAND.

  :TYPE		An alist of symbols and type specifiers.  The new environment
		will have the type specifier associated with the currently
		visible binding of the symbol (defaulting to the global special
		binding if there is no binding present).  Note that in a single
		call to AUGMENT-ENVIRONMENT the :TYPE argument can be thought
		of as being processed after all the variable arguments have
		been processed, thus allowing bindings and declarations to be
		updated with a single call.

  :FTYPE	An alist of function names and functional type specifiers.
		This is analogous to :TYPE, exept operating in the function
		namespace. 

  While an environment argument from EVALHOOK may be used as the environment
  argument for this function, the reverse is not true.  It is an error to
  attempt to use the result of AUGMENT-ENVIRONMENT as the environment argument
  for EVALHOOK.  The environment returned by AUGMENT-ENVIRONMENT may only be
  used for syntactic analysis.

 ENVIRONMENT-PROPERTY env name property &optional default

  This function and its SETF method allow the association of arbitrary 'global'
  properties with names.  An environment can be thought of as having a local
  property list associated with any name, and this function provides access to
  that property list.  The association between names and property lists uses
  EQUAL to match names.  The search of the property list uses EQ to match
  properties.  If the property is not found in the environment's local property
  list, the global property list of the name is searched.  If the property is
  not found on the global property list, then default is returned.

  Note that the global property list of a name is not necessarily the
  symbol-plist of the name. 

  [Note: The use of EQUAL as the matching function for names is to allow for
   proposed extensions to function names.  If no such extension occurs, then EQ
   could be used instead.]

Rationale:

 This proposal provides a portable interface to environment information which
 must otherwise be obtained by implementation-dependent means.  The
 ENSURE-GENERIC-FUNCTION and FIND-CLASS functions of CLOS require the
 ENVIRONMENT-TARGET function and some mechanism similar to that supplied by the
 ENVIRONMENT-PROPERTY function.  A useful code walker requires the capability
 of adding local function definitions to an environment.

Cost to Implementors:

 Most implementations already store some of this information in some form.
 Providing these functions should not be too difficult, but it is a more than
 trivial amount of work.

Cost to Users:

 This change is upward compatible with user code.

Current practice:

 No implementation provides all of this interface currently.  Portable Common
 Loops defines a subset of this functionality for its code walker and
 implements it on a number of diffent versions of Common Lisp.  IIM uses the
 functionality provided by ENVIRONMENT-TARGET and ENVIRONMENT-PROPERTY (under
 other names) to implement the association between names and remote metaobjects
 (macro and type definitions, CLOS remote metaobjects, &etc).

Discussion:

 The first version of this proposal expressly did not deal with the objects
 which are used as environments by EVALHOOK.  This version is extended to
 support them in the belief that such environments share a lot of functionality
 with the syntactic environments needed by a compiler.  While the two types of
 environments may have very different implementations, there are many
 operations which are reasonable to perform on either type, including all of
 the accessor functions described by this proposal.
-------
-------
-------