guile/doc/scheme-evaluation.texi

@page
@node Read/Load/Eval
@chapter Reading and Evaluating Scheme Code

This chapter describes Guile functions that are concerned with reading,
loading and evaluating Scheme code at run time.

@menu
* Scheme Syntax::               Standard and extended Scheme syntax.
* Scheme Read::                 Reading Scheme code.
* Fly Evaluation::              Procedures for on the fly evaluation.
* Loading::                     Loading Scheme code from file.
* Delayed Evaluation::          Postponing evaluation until it is needed.
* Local Evaluation::            Evaluation in a local environment.
* Evaluator Behaviour::         Modifying Guile's evaluator.
@end menu


@node Scheme Syntax
@section Scheme Syntax: Standard and Guile Extensions

@menu
* Expression Syntax::
* Comments::
* Block Comments::
* Case Sensitivity::
* Keyword Syntax::
* Reader Extensions::
@end menu


@node Expression Syntax
@subsection Expression Syntax


@node Comments
@subsection Comments


@node Block Comments
@subsection Block Comments


@node Case Sensitivity
@subsection Case Sensitivity


@node Keyword Syntax
@subsection Keyword Syntax


@node Reader Extensions
@subsection Reader Extensions

@c docstring begin (texi-doc-string "guile" "read-hash-extend")
@deffn primitive read-hash-extend chr proc
Install the procedure @var{proc} for reading expressions
starting with the character sequence @code{#} and @var{chr}.
@var{proc} will be called with two arguments:  the character
@var{chr} and the port to read further data from. The object
returned will be the return value of @code{read}.
@end deffn


@node Scheme Read
@section Reading Scheme Code

@r5index read
@c docstring begin (texi-doc-string "guile" "read")
@deffn primitive read [port]
Read an s-expression from the input port @var{port}, or from
the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded.
@end deffn

The behaviour of Guile's Scheme reader can be modified by manipulating
its read options.  For more information about options, @xref{General
option interface}.  If you want to know which reader options are
available, @xref{Reader options}.

@c FIXME::martin: This is taken from libguile/options.c.  Is there 
@c actually a difference between 'help and 'full?

@deffn procedure read-options [setting]
Display the current settings of the read options.  If @var{setting} is
omitted, only a short form of the current read options is printed.
Otherwise, @var{setting} should be one of the following symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn

@deffn procedure read-enable option-name
@deffnx procedure read-disable option-name
@deffnx procedure read-set! option-name value
Modify the read options.  @code{read-enable} should be used with boolean
options and switches them on, @code{read-disable} switches them off.
@code{read-set!} can be used to set an option to a specific value.
@end deffn

@c docstring begin (texi-doc-string "guile" "read-options-interface")
@deffn primitive read-options-interface [setting]
Option interface for the read options. Instead of using
this procedure directly, use the procedures @code{read-enable},
@code{read-disable}, @code{read-set!} and @code{read-options}.
@end deffn


@node Fly Evaluation
@section Procedures for On the Fly Evaluation

@r5index eval
@c ARGFIXME environment/environment specifier
@c docstring begin (texi-doc-string "guile" "eval")
@deffn primitive eval exp environment
Evaluate @var{exp}, a list representing a Scheme expression, in the
environment given by @var{environment specifier}.
@end deffn

@r5index interaction-environment
@c docstring begin (texi-doc-string "guile" "interaction-environment")
@deffn primitive interaction-environment
This procedure returns a specifier for the environment that contains
implementation-defined bindings, typically a superset of those listed in
the report.  The intent is that this procedure will return the
environment in which the implementation would evaluate expressions
dynamically typed by the user.
@end deffn

@c docstring begin (texi-doc-string "guile" "eval-string")
@deffn primitive eval-string string
Evaluate @var{string} as the text representation of a Scheme
form or forms, and return whatever value they produce.
Evaluation takes place in the environment returned by the
procedure @code{interaction-environment}.
@end deffn

@c docstring begin (texi-doc-string "guile" "apply:nconc2last")
@deffn primitive apply:nconc2last lst
Given a list (@var{arg1} @dots{} @var{args}), this function
conses the @var{arg1} @dots{} arguments onto the front of
@var{args}, and returns the resulting list. Note that
@var{args} is a list; thus, the argument to this function is
a list whose last element is a list.
Note: Rather than do new consing, @code{apply:nconc2last}
destroys its argument, so use with care.
@end deffn

@r5index apply
@deffn primitive apply proc arg1 @dots{} args
@var{proc} must be a procedure and @var{args} must be a list.  Call
@var{proc} with the elements of the list @code{(append (list @var{arg1}
@dots{}) @var{args})} as the actual arguments.
@end deffn

@deffn primitive primitive-eval exp
Evaluate @var{exp} in the top-level environment specified by
the current module.
@end deffn

@deffn primitive eval2 obj env_thunk
Evaluate @var{exp}, a Scheme expression, in the environment
designated by @var{lookup}, a symbol-lookup function."
Do not use this version of eval, it does not play well
with the module system.  Use @code{eval} or
@code{primitive-eval} instead.
@end deffn

@deffn primitive read-and-eval! [port]
Read a form from @var{port} (standard input by default), and evaluate it
(memoizing it in the process) in the top-level environment.  If no data
is left to be read from @var{port}, an @code{end-of-file} error is
signalled.
@end deffn


@node Loading
@section Loading Scheme Code from File

@r5index load
@deffn procedure load filename
Load @var{file} and evaluate its contents in the top-level environment.
The load paths are searched.  If the variable @code{%load-hook} is
defined, it should be bound to a procedure that will be called before
any code is loaded.  See documentation for @code{%load-hook} later in
this section.
@end deffn

@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load")
@deffn primitive primitive-load filename
Load the file named @var{filename} and evaluate its contents in
the top-level environment. The load paths are not searched;
@var{filename} must either be a full pathname or be a pathname
relative to the current directory.  If the  variable
@code{%load-hook} is defined, it should be bound to a procedure
that will be called before any code is loaded.  See the
documentation for @code{%load-hook} later in this section.
@end deffn

@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load-path")
@deffn primitive primitive-load-path filename
Search @var{%load-path} for the file named @var{filename} and
load it into the top-level environment.  If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled.
@end deffn

@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "%search-load-path")
@deffn primitive %search-load-path filename
Search @var{%load-path} for the file named @var{filename},
which must be readable by the current user.  If @var{filename}
is found in the list of paths to search or is an absolute
pathname, return its full pathname.  Otherwise, return
@code{#f}.  Filenames may have any of the optional extensions
in the @code{%load-extensions} list; @code{%search-load-path}
will try each extension automatically.
@end deffn

@defvar %load-hook
A procedure to be run whenever @code{primitive-load} is called.  If this
procedure is defined, it will be called with the filename argument that
was passed to @code{primitive-load}.

@example
(define %load-hook (lambda (file)
                     (display "Loading ")
                     (display file)
                     (write-line "...."))) @result{} undefined
(load-from-path "foo.scm")
@print{} Loading /usr/local/share/guile/site/foo.scm....
@end example

@end defvar

@c docstring begin (texi-doc-string "guile" "current-load-port")
@deffn primitive current-load-port
Return the current-load-port.
The load port is used internally by @code{primitive-load}.
@end deffn

@defvar %load-extensions
A list of default file extensions for files containing Scheme code.
@code{%search-load-path} tries each of these extensions when looking for
a file to load.  By default, @code{%load-extensions} is bound to the
list @code{("" ".scm")}.
@end defvar


@node Delayed Evaluation
@section Delayed Evaluation

[delay]

@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "promise?")
@deffn primitive promise? obj
Return true if @var{obj} is a promise, i.e. a delayed computation
(@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}).
@end deffn

@r5index force
@c docstring begin (texi-doc-string "guile" "force")
@deffn primitive force x
If the promise @var{x} has not been computed yet, compute and
return @var{x}, otherwise just return the previously computed
value.
@end deffn


@node Local Evaluation
@section Local Evaluation

[the-environment]

@c docstring begin (texi-doc-string "guile" "local-eval")
@deffn primitive local-eval exp [env]
Evaluate @var{exp} in its environment.  If @var{env} is supplied,
it is the environment in which to evaluate @var{exp}.  Otherwise,
@var{exp} must be a memoized code object (in which case, its environment
is implicit).
@end deffn


@node Evaluator Behaviour
@section Evaluator Behaviour

@c FIXME::martin: Maybe this node name is bad, but the old name clashed with
@c `Evaluator options' under `Options and Config'.

The behaviour of Guile's evaluator can be modified by manipulating the
evaluator options.  For more information about options, @xref{General
option interface}.  If you want to know which reader options are
available, @xref{Evaluator options}.

@c FIXME::martin: This is taken from libguile/options.c.  Is there 
@c actually a difference between 'help and 'full?

@deffn procedure eval-options [setting]
Display the current settings of the evaluator options.  If @var{setting}
is omitted, only a short form of the current evaluator options is
printed.  Otherwise, @var{setting} should be one of the following
symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn

@deffn procedure eval-enable option-name
@deffnx procedure eval-disable option-name
@deffnx procedure eval-set! option-name value
Modify the evaluator options.  @code{eval-enable} should be used with boolean
options and switches them on, @code{eval-disable} switches them off.
@code{eval-set!} can be used to set an option to a specific value.
@end deffn

@c docstring begin (texi-doc-string "guile" "eval-options-interface")
@deffn primitive eval-options-interface [setting]
Option interface for the evaluation options. Instead of using
this procedure directly, use the procedures @code{eval-enable},
@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
@end deffn

@c FIXME::martin: Why aren't these procedure named like the other options
@c procedures?

@deffn procedure traps [setting]
Display the current settings of the evaluator traps options.  If
@var{setting} is omitted, only a short form of the current evaluator
traps options is printed.  Otherwise, @var{setting} should be one of the
following symbols:
@table @code
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn

@deffn procedure trap-enable option-name
@deffnx procedure trap-disable option-name
@deffnx procedure trap-set! option-name value
Modify the evaluator options.  @code{trap-enable} should be used with boolean
options and switches them on, @code{trap-disable} switches them off.
@code{trap-set!} can be used to set an option to a specific value.
@end deffn

@c docstring begin (texi-doc-string "guile" "evaluator-traps-interface")
@deffn primitive evaluator-traps-interface [setting]
Option interface for the evaluator trap options.
@end deffn


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: