1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-09 21:40:33 +02:00

* scheme-options.texi (Evaluator trap options): Splitted

section "Evaluator options".

* scheme-evaluation.texi (Evaluator Behaviour): Typo "reader
options" --> "evaluator options".
This commit is contained in:
Mikael Djurfeldt 2001-08-22 09:57:35 +00:00
parent cf504ee0cf
commit 88176879bf
3 changed files with 8 additions and 761 deletions

View file

@ -1,3 +1,11 @@
2001-08-22 Mikael Djurfeldt <mdj@linnaeus.mit.edu>
* scheme-options.texi (Evaluator trap options): Splitted
section "Evaluator options".
* scheme-evaluation.texi (Evaluator Behaviour): Typo "reader
options" --> "evaluator options".
2001-08-17 Rob Browning <rlb@defaultvalue.org>
* Makefile.am (guile_tut_TEXINFOS): remove guile-tut.texi. It's

View file

@ -1,419 +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 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 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
@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:

View file

@ -1,342 +0,0 @@
@page
@node Options and Config
@chapter Runtime Options and Configuration
Guile's behaviour can be modified by setting options. For example, is
the language that Guile accepts case sensitive, or should the debugger
automatically show a backtrace on error?
Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.
Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.
@menu
* General option interface::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Examples of option use::
* Install Config:: Installation and configuration data.
@end menu
@node General option interface
@section General option interface
We will use the expression @code{<group>} to represent @code{read},
@code{print}, @code{debug} or @code{evaluator}.
@subheading Low level
@c NJFIXME
@deffn primitive <group>-options-interface
@deffnx primitive read-options-interface [SOME-INT]
@deffnx primitive print-options-interface [SOME-INT]
@deffnx primitive evaluator-traps-interface [SOME-INT]
@deffnx primitive read-options-interface [SOME-INT]
[FIXME: I have just taken the comments for C routine scm_options that
implements all of these. It needs to be presented better.]
If scm_options is called without arguments, the current option setting
is returned. If the argument is an option setting, options are altered
and the old setting is returned. If the argument isn't a list, a list
of sublists is returned, where each sublist contains option name, value
and documentation string.
@end deffn
@subheading User level
@c @deftp {Data type} scm_option
@c @code{scm_option} is used to represent run time options. It can be a
@c @emph{boolean} type, in which case the option will be set by the strings
@c @code{"yes"} and @code{"no"}. It can be a
@c @end deftp
@c NJFIXME
@deffn procedure <group>-options [arg]
@deffnx procedure read-options [arg]
@deffnx procedure print-options [arg]
@deffnx procedure debug-options [arg]
@deffnx procedure traps [arg]
These functions list the options in their group. The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.
With no arguments, @code{<group>-options} returns the values of the
options in that particular group. If @var{arg} is @code{'help}, a
description of each option is given. If @var{arg} is @code{'full},
programmers' options are also shown.
@var{arg} can also be a list representing the state of all options. In
this case, the list contains single symbols (for enabled boolean
options) and symbols followed by values.
@end deffn
[FIXME: I don't think 'full is ever any different from 'help. What's
up?]
@c NJFIXME
@deffn procedure <group>-enable option-symbol
@deffnx procedure read-enable option-symbol
@deffnx procedure print-enable option-symbol
@deffnx procedure debug-enable option-symbol
@deffnx procedure trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group. They only work if the option is boolean, and throw an error
otherwise.
@end deffn
@c NJFIXME
@deffn procedure <group>-disable option-symbol
@deffnx procedure read-disable option-symbol
@deffnx procedure print-disable option-symbol
@deffnx procedure debug-disable option-symbol
@deffnx procedure trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group. They only work if the option is boolean, and throw an
error otherwise.
@end deffn
@c NJFIXME
@deffn syntax <group>-set! option-symbol value
@deffnx syntax read-set! option-symbol value
@deffnx syntax print-set! option-symbol value
@deffnx syntax debug-set! option-symbol value
@deffnx syntax trap-set! option-symbol value
These functions set a non-boolean @var{option-symbol} to the specified
@var{value}.
@end deffn
@node Reader options
@section Reader options
@cindex options - read
@cindex read options
Here is the list of reader options generated by typing
@code{(read-options 'full)} in Guile. You can also see the default
values.
@smalllisp
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
@end smalllisp
Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.
To make Guile case insensitive, you can type
@smalllisp
(read-enable 'case-insensitive)
@end smalllisp
@node Printing options
@section Printing options
Here is the list of print options generated by typing
@code{(print-options 'full)} in Guile. You can also see the default
values.
@smallexample
source no Print closures with source.
closure-hook #f Hook for printing closures.
@end smallexample
@node Evaluator options
@section Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.
@smallexample
stack 22000 Size of thread stacks (in machine words).
@end smallexample
Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile. You can also see the default values.
@smallexample
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
@end smallexample
@node Debugger options
@section Debugger options
Here is the list of print options generated by typing
@code{(debug-options 'full)} in Guile. You can also see the default
values.
@smallexample
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
@end smallexample
@node Examples of option use
@section Examples of option use
Here is an example of a session in which some read and debug option
handling procedures are used. In this example, the user
@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@item
Reproduces the error of displaying @code{aBc} with backtracing enabled
[FIXME: this last example is lame because there is no depth in the
backtrace. Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate
@smalllisp
guile> (define abc "hello")
guile> abc
"hello"
guile> aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
Type "(backtrace)" to get more information.
guile> (read-options 'help)
keywords #f Style of keyword recognition: #f or 'prefix
case-insensitive no Convert symbols to lower case.
positions yes Record positions of source code expressions.
copy no Copy source code expressions.
guile> (debug-options 'help)
stack 20000 Stack size limit (0 = no check).
debug yes Use the debugging evaluator.
backtrace no Show backtrace on error.
depth 20 Maximal length of printed backtrace.
maxdepth 1000 Maximal number of stored backtrace frames.
frames 3 Maximum number of tail-recursive frames in backtrace.
indent 10 Maximal indentation in backtrace.
backwards no Display backtrace in anti-chronological order.
procnames yes Record procedure names at definition.
trace no *Trace mode.
breakpoints no *Check for breakpoints.
cheap yes *Flyweight representation of the stack at traps.
guile> (read-enable 'case-insensitive)
(keywords #f case-insensitive positions)
guile> aBc
"hello"
guile> (read-disable 'case-insensitive)
(keywords #f positions)
guile> (debug-enable 'backtrace)
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
guile> aBc
Backtrace:
0* aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp
@node Install Config
@section Installation and Configuration Data
It is often useful to have site-specific information about the current
Guile installation. This chapter describes how to find out about
Guile's configuration at run time.
@deffn primitive version
@deffnx primitive major-version
@deffnx primitive minor-version
@deffnx primitive micro-version
Return a string describing Guile's version number, or its major or minor
version numbers, respectively.
@lisp
(version) @result{} "1.6.5"
(major-version) @result{} "1"
(minor-version) @result{} "6"
(micro-version) @result{} "5"
@end lisp
@end deffn
@c NJFIXME not in libguile!
@deffn primitive libguile-config-stamp
Return a string describing the date on which @code{libguile} was
configured. This is used to determine whether the Guile core
interpreter and the ice-9 runtime have grown out of date with one
another.
@end deffn
@deffn primitive %package-data-dir
Return the name of the directory where Scheme packages, modules and
libraries are kept. On most Unix systems, this will be
@samp{/usr/local/share/guile}.
@end deffn
@deffn primitive %library-dir
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
@end deffn
@deffn primitive %site-dir
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
@end deffn
@deffn primitive parse-path path [tail]
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn
@deffn primitive search-path path filename [extensions]
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return
@code{#f}. If @var{filename} is absolute, return it unchanged.
If given, @var{extensions} is a list of strings; for each
directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.
@end deffn
@defvar %load-path
Return the list of directories which should be searched for Scheme
modules and libraries.
@end defvar
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: