diff options
Diffstat (limited to 'doc/ref/scheme-evaluation.texi')
-rw-r--r-- | doc/ref/scheme-evaluation.texi | 426 |
1 files changed, 0 insertions, 426 deletions
diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi deleted file mode 100644 index b73f8316d..000000000 --- a/doc/ref/scheme-evaluation.texi +++ /dev/null @@ -1,426 +0,0 @@ -@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 {Scheme Procedure} read-hash-extend chr proc -@deffnx {C Function} scm_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 {Scheme Procedure} read [port] -@deffnx {C Function} scm_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 {Scheme 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 {Scheme Procedure} read-enable option-name -@deffnx {Scheme Procedure} read-disable option-name -@deffnx {Scheme 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 {Scheme Procedure} read-options-interface [setting] -@deffnx {C Function} scm_read_options (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 - -@xref{Environments}. - -@rnindex eval -@c ARGFIXME environment/environment specifier -@deffn {Scheme Procedure} eval exp module -@deffnx {C Function} scm_eval (exp, module) -Evaluate @var{exp}, a list representing a Scheme expression, -in the top-level environment specified by @var{module}. -While @var{exp} is evaluated (using @code{primitive-eval}), -@var{module} is made the current module. The current module -is reset to its previous value when @var{eval} returns. -@end deffn - -@rnindex interaction-environment -@deffn {Scheme Procedure} interaction-environment -@deffnx {C Function} scm_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 {Scheme Procedure} eval-string string -@deffnx {C Function} scm_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 {Scheme Procedure} apply:nconc2last lst -@deffnx {C Function} scm_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 {Scheme Procedure} 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 {Scheme Procedure} primitive-eval exp -@deffnx {C Function} scm_primitive_eval (exp) -Evaluate @var{exp} in the top-level environment specified by -the current module. -@end deffn - - -@node Loading -@section Loading Scheme Code from File - -@rnindex load -@deffn {Scheme 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 {Scheme Procedure} load-from-path filename -Similar to @code{load}, but searches for @var{filename} in the load -paths. -@end deffn - -@deffn {Scheme Procedure} primitive-load filename -@deffnx {C Function} scm_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 {Scheme Procedure} primitive-load-path filename -@deffnx {C Function} scm_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 {Scheme Procedure} %search-load-path filename -@deffnx {C Function} scm_sys_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 {Scheme Procedure} current-load-port -@deffnx {C Function} scm_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 {Scheme Procedure} promise? obj -@deffnx {C Function} scm_promise_p (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 {Scheme Procedure} force x -@deffnx {C Function} scm_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 {Scheme Procedure} local-eval exp [env] -@deffnx {C Function} scm_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 {Scheme 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 {Scheme Procedure} eval-enable option-name -@deffnx {Scheme Procedure} eval-disable option-name -@deffnx {Scheme 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 {Scheme Procedure} eval-options-interface [setting] -@deffnx {C Function} scm_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 {Scheme 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 {Scheme Procedure} trap-enable option-name -@deffnx {Scheme Procedure} trap-disable option-name -@deffnx {Scheme 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 {Scheme Procedure} evaluator-traps-interface [setting] -@deffnx {C Function} scm_evaluator_traps (setting) -Option interface for the evaluator trap options. -@end deffn - - -@c Local Variables: -@c TeX-master: "guile.texi" -@c End: |