Revised straw proposal for heuristic info

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

This is a revision of my straw proposal of last Monday, taking
comments into account.  The main difference between this straw
proposal and the last one is that most of the procedures are now
permitted to return anything whatsoever, although the proposal
specifies an interpretation for only certain types of results.

In the words of Bill Rozas, this revised straw proposal describes

> subprimitives that implementations can agree on, but whose semantics
> is not well-enough defined, specified or guaranteed to constrain the
> implementation of the semantics of the features in the [language] proper.

Matthias Blume asks "what good" is it?

This proposal specifies an interface that allows debugging
tools and other heuristic consumers of information to compute
the greatest common denominator between themselves, the system,
the particular values for which information is sought, and of
course this interface.  Unlike the least common denominator,
the greatest common denominator is not always 1.

Since we seem to be agreed (a miracle?!?!!) that this stuff
doesn't belong in the RnRS, this is the sort of thing that
some random group of implementors could agree upon and publish.
If some university or implementation should choose to bind it
together with the R5RS, let them take whatever flack the R*RS
authors might give them.

Will

--------

Start of revised straw proposal.

----
Extracting heuristic information from procedures.

The procedures that extract heuristic information from procedures
are permitted to return any result whatsoever.  If the type of a
result is not among those listed below, then the result represents
an implementation-dependent extension to this interface, which may
safely be interpreted as though no information were available from
the procedure. Otherwise the result is to be interpreted as described
below.

(procedure-arity _proc_)

  Returns information about the arity of _proc_.  If the result
  is #F, then no information is available.  If the result
  is an exact non-negative integer k, then _proc_ requires
  exactly k arguments.  If the result is an inexact non-negative
  integer n, then _proc_ requires n or more arguments.  If the
  result is a pair, then it is a list of exact non-negative
  integers, each of which is a number of arguments that will be
  accepted by _proc_; the list is not necessarily exhaustive.

(procedure-documentation-string _proc_)

  Returns general information about _proc_.  If the result is
  #F, then no information is available.  If the result is a
  string, then it is to be interpreted as a "documentation
  string" (see Common Lisp).

(procedure-name _proc_)

  Returns information about the name of _proc_.  If the result
  is #F, then no information is available.  If the result is a
  symbol or string, then it represents a name.  If the result
  is a pair, then it is a list of symbols and/or strings
  representing a path of names; the first element of the list
  represents an outer name and the last element represents an
  inner name.

(procedure-source-file _proc_)

  Returns information about the name of a file that contains the
  source code for _proc_.  If the result is #F, then no information
  is available.  If the result is a string, then the string is the
  name of a file.

(procedure-source-position _proc_)

  Returns information about the position of the source code for
  _proc_ within the source file specified by PROCEDURE-SOURCE-FILE.
  If the result is #F, then no information is available.  If the
  result is an exact integer k, then k characters precede the
  opening parenthesis of the source code for _proc_ within that
  source file.

(procedure-expression _proc_)

  Returns information about the source code for _proc_.  If the
  result is #F, then no information is available.  If the result
  is a pair, then it is a lambda expression in the traditional
  representation as a list.

(procedure-environment _proc_)

  Returns information about the environment of _proc_.  If the
  result is #F, then no information is available.  In any case
  the result may be passed to any of the procedures listed
  below.

----
Extracting heuristic information from environments.

Let _env_ be a result returned by PROCEDURE-ENVIRONMENT.
_env_ may be #F.

Let _name_ be a symbol or string.

(environment-variables _env_)

  Returns information about the variables that are bound in _env_.
  If the result is #F, then no information is available.  If the
  result is the empty list, then either no information is available
  or no variables are bound.  If the result is a pair, then it is
  a list of symbols and/or strings that name the variables that are
  bound in _env_.  The result returned by this operation is not
  necessarily related to the results returned by ENVIRONMENT-GETTABLE?
  and ENVIRONMENT-SETTABLE?.

(environment-gettable? _env_ _name_)

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

(environment-settable? _env_ _name_)

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

(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 revised straw proposal.