diff options
Diffstat (limited to 'doc/ref/scheme-evaluation.texi')
-rw-r--r-- | doc/ref/scheme-evaluation.texi | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi new file mode 100644 index 000000000..210f26040 --- /dev/null +++ b/doc/ref/scheme-evaluation.texi @@ -0,0 +1,419 @@ +@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 + +@c FIXME::martin: Review me! + +Comments in Scheme source files are written by starting them with a +semicolon character (@code{;}). The comment then reaches up to the end +of the line. Comments can begin at any column, and the may be inserted +on the same line as Scheme code. + +@lisp +; Comment +;; Comment too +(define x 1) ; Comment after expression +(let ((y 1)) + ;; Display something. + (display y) +;;; Comment at left margin. + (display (+ y 1))) +@end lisp + +It is common to use a single semicolon for comments following +expressions on a line, to use two semicolons for comments which are +indented like code, and three semicolons for comments which start at +column 0, even if they are inside an indented code block. This +convention is used when indenting code in Emacs' Scheme mode. + + +@node Block Comments +@subsection Block Comments + +@c FIXME::martin: Review me! + +@cindex multiline comments +In addition to the standard line comments defined by R5RS, Guile has +another comment type for multiline comments, called @dfn{block +comments}. This type of comment begins with the character sequence +@code{#!} and ends with the characters @code{!#}, which must appear on a +line of their own. These comments are compatible with the block +comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell +(scsh)}). The characters @code{#!} were chosen because they are the +magic characters used in shell scripts for indicating that the name of +the program for executing the script follows on the same line. + +Thus a Guile script often starts like this. + +@lisp +#! /usr/local/bin/guile -s +!# +@end lisp + +More details on Guile scripting can be found in the scripting section +(@pxref{Guile Scripting}). + + +@node Case Sensitivity +@subsection Case Sensitivity + +@c FIXME::martin: Review me! + +Scheme as defined in R5RS is not case sensitive when reading symbols. +Guile, on the contrary is case sensitive by default, so the identifiers + +@lisp +guile-whuzzy +Guile-Whuzzy +@end lisp + +are the same in R5RS Scheme, but are different in Guile. + +It is possible to turn off case sensitivity in Guile by setting the +reader option @code{case-insensitive}. More on reader options can be +found at (@pxref{Reader options}). + +@lisp +(read-enable 'case-insensitive) +@end lisp + +Note that this is seldom a problem, because Scheme programmers tend not +to use uppercase letters in their identifiers anyway. + + +@node Keyword Syntax +@subsection Keyword Syntax + + +@node Reader Extensions +@subsection Reader Extensions + +@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 + +@rnindex 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 + +@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 + +@rnindex eval +@c ARGFIXME environment/environment specifier +@deffn primitive eval exp environment +Evaluate @var{exp}, a list representing a Scheme expression, in the +environment given by @var{environment specifier}. +@end deffn + +@rnindex interaction-environment +@deffn primitive interaction-environment +Return 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 + +@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 + +@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 + +@rnindex 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 + +@rnindex load +@deffn procedure load filename +Load @var{filename} and evaluate its contents in the top-level +environment. The load paths are not 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 + +@deffn procedure load-from-path filename +Similar to @code{load}, but searches for @var{filename} in the load +paths. +@end deffn + +@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 + +@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 + +@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 + +@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] + +@deffn primitive promise? obj +Return true if @var{obj} is a promise, i.e. a delayed computation +(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}). +@end deffn + +@rnindex 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] + +@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 evaluator 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 + +@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 + +@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: |