straw proposal: heuristic info from procedures

[William D Clinger <will@ccs.neu.edu>]

What follows is a straw proposal for extracting heuristic information
from procedures and their environments for the benefit of debuggers
and other uses that should not be allowed to interfere with compiler
optimizations or the requirements of embedded systems.

I would call attention to the following:

  1.  We need a document that is separate from the R*RS series
      to describe this and other interfaces for things that are
      likely to be fairly implementation-dependent in their
      behavior.

  2.  Most implementations are already capable of supplying most
      of this information, although the details vary, so this is
      essentially a standard interface to capabilities that already
      exist.

  3.  A null implementation satisfies the specification below.

  4.  Programmers can request a non-null implementation by some
      conventional means that is orthogonal to this proposal.

I like Aubrey Jaffer's suggestion that documentation strings be
used to mark specific procedures for which a non-null implementation
of this stuff should be provided, but I think a more general
declaration facility is needed also.  I think it is useful to
separate the interface itself from the means used to declare that
this kind of information is needed because:

  *  There will be implementations for which this kind of
     information can always be provided.

  *  There will also be implementations for embedded systems
     in which this kind of information is never needed.  Consider,
     for example, an implementation of Scheme that is used only as
     an UNCOL for a multi-language compiler.  Debugging information
     should be made available in terms of the source program and
     its variables, not in terms of the compiled (that is, Scheme)
     code.

  *  It is easier to reach agreement on separate proposals than
     on proposals that try to solve several problems at once.

Will

Start of straw proposal.

----
Extracting heuristic information from procedures.

(procedure-arity _proc_)

  Returns information about the arity of _proc_.  This information
  can take several forms:

    an exact non-negative integer k: _proc_ requires exactly k 
arguments.
    (k): _proc_ requires at least k arguments.
    (k1 k2): _proc_ requires at least k1 but no more than k2 arguments.
    #F: no information on the arity of _proc_ is available.

(procedure-documentation-string _proc_)

  Returns the documentation string associated with _proc_,
  or #F if no documentation string is associated with _proc_.

(procedure-name _proc_)

  Returns a name of _proc_ as a symbol or string, or returns
  #F if no name is associated with _proc_.

(procedure-source-file _proc_)

  Returns the name of the file that contains the source code for
  _proc_, as a string, or returns #F if this information is not
  available.

(procedure-source-position _proc_)

  Returns an exact integer that specifies the number of characters
  that precede the opening parenthesis of the source code for _proc_
  within the source file returned by PROCEDURE-SOURCE-FILE, or
  returns #F if this information is not available.

(procedure-code _proc_)

  Returns the source code for _proc_ as a lambda expression, in the
  traditional representation as a list, or returns #F if no source
  code is available for _proc_.

(procedure-environment _proc_)

  Returns a representation of the environment in which the source
  code for _proc_ was closed, or #F if no environment information
  is available.  See below for the operations on the environment
  representation that is returned by this operation.

----
Extracting heuristic information from environments.

Let _env_ be the representation of an environment as returned by
PROCEDURE-ENVIRONMENT.  _env_ may be #F.

Let _name_ be a symbol or string.

(environment-variables _env_)

  Returns a list of symbols and/or strings that name the variables
  that are bound in _env_.  The empty list may be returned if this
  information is not available.  The result returned by this
  operation does not necessarily bear any relationship to the
  results returned by ENVIRONMENT-GETTABLE? and ENVIRONMENT-SETTABLE?.

  Rationale:  It is sometimes useful to know the names of variables
  even if they can't be fetched or assigned.

(environment-gettable? _env_ _name_)

  Returns #T if the value of _name_ in _env_ can be obtained by
  calling ENVIRONMENT-GET.

(environment-settable? _env_ _name_)

  Returns #T if the value of _name_ in _env_ can be changed by
  calling ENVIRONMENT-SET!.

(environment-get _env_ _name_)

  Returns the value of _name_ in _env_, or returns #F if this
  value is not available.

(environment-set! _env_ _name_ _obj_)

  Stores _obj_ in the location denoted by _name_ in the environment
  represented by _env_.  It is an error to use this operation unless
  _name_ is settable in _env_ as reported by ENVIRONMENT-SETTABLE?.

(environment-reify _env_)

  Returns the environment represented by _env_ in a form that can
  be passed as the second argument to the R5RS version of EVAL.
  The environment returned by this operation may be identical to
  a standard R5RS environment, regardless of what is returned by
  ENVIRONMENT-VARIABLES, ENVIRONMENT-GETTABLE?, and
  ENVIRONMENT-SETTABLE?.

  Rationale:  Implementations should be encouraged to provide
  information that is useful for debugging, even if they do not
  support anything beyond the minimal R5RS requirements for EVAL.

----

End of straw proposal.