diff --git a/doc/ChangeLog b/doc/ChangeLog index 64761ee80..26154476b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,20 @@ +2001-03-20 Martin Grabmueller + + * scheme-options.texi (Evaluator options): Added evaluator + options, corrected docs for evaluator trap options. + + * scheme-evaluation.texi (Scheme Read): New docs for read-options, + read-enable, read-disable and read-set! and cross references to + option nodes. + (Evaluator Options): New docs for eval-options, eval-enable, + eval-disable and eval-set!, traps, trap-enable, trap-disable and + trap-set! and cross references to option nodes. + (Evaluator Behaviour): Renamed node from `Evaluator options' to + avoid name clash. + + * scheme-io.texi (String Ports): Added docs for SRFI-6 procedures. + (Void Ports): Corrected introductory comment. + 2001-03-16 Martin Grabmueller * scheme-data.texi (Arithmetic): Documented the arithmetic diff --git a/doc/scheme-evaluation.texi b/doc/scheme-evaluation.texi index 31e99ad7a..8211aa37a 100644 --- a/doc/scheme-evaluation.texi +++ b/doc/scheme-evaluation.texi @@ -12,7 +12,7 @@ loading and evaluating Scheme code at run time. * Loading:: Loading Scheme code from file. * Delayed Evaluation:: Postponing evaluation until it is needed. * Local Evaluation:: Evaluation in a local environment. -* Evaluator Options:: +* Evaluator Behaviour:: Modifying Guile's evaluator. @end menu @@ -65,13 +65,6 @@ returned will be the return value of @code{read}. @node Scheme Read @section Reading Scheme Code -@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 @var{read-options}. -@end deffn - @r5index read @c docstring begin (texi-doc-string "guile" "read") @deffn primitive read [port] @@ -80,6 +73,41 @@ 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 @@ -254,14 +282,70 @@ is implicit). @end deffn -@node Evaluator Options -@section Evaluator Options +@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 @var{eval-options}. +@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") diff --git a/doc/scheme-io.texi b/doc/scheme-io.texi index a98e96eb7..f3a6a9001 100644 --- a/doc/scheme-io.texi +++ b/doc/scheme-io.texi @@ -762,16 +762,35 @@ port set temporarily to a string port opened on the specified @var{string}. The value yielded by @var{thunk} is returned. @end deffn +@c docstring begin (texi-doc-string "guile" "open-input-string") +@deffn primitive open-input-string str +Takes a string and returns an input port that delivers +characters from the string. The port can be closed by +@code{close-input-port}, though its storage will be reclaimed +by the garbage collector if it becomes inaccessible. +@end deffn + +@c docstring begin (texi-doc-string "guile" "open-output-string") +@deffn primitive open-output-string +Returns an output port that will accumulate characters for +retrieval by @code{get-output-string}. The port can be closed +by the procedure @code{close-output-port}, though its storage +will be reclaimed by the garbage collector if it becomes +inaccessible. +@end deffn + +@c docstring begin (texi-doc-string "guile" "get-output-string") +@deffn primitive get-output-string port +Given an output port created by @code{open-output-string}, +returns a string consisting of the characters that have been +output to the port so far. +@end deffn + A string port can be used in many procedures which accept a port but which are not dependent on implementation details of fports. E.g., seeking and truncating will work on a string port, but trying to extract the file descriptor number will fail. -At present there isn't a procedure that simply returns a new string -port. There's also no way of opening read/write string ports from -Scheme even though it's possible from C. SRFI 6 could be implemented -without much difficulty. - @node Soft Ports @subsection Soft Ports @@ -828,8 +847,8 @@ the port has reached end-of-file. For example: @node Void Ports @subsection Void Ports -This kind of port just causes errors if you try to use it in -a normal way. +This kind of port causes any data to be discarded when written to, and +always returns the end-of-file object when read from. @c docstring begin (texi-doc-string "guile" "%make-void-port") @deffn primitive %make-void-port mode diff --git a/doc/scheme-options.texi b/doc/scheme-options.texi index c8ef7b35b..65e85ba61 100644 --- a/doc/scheme-options.texi +++ b/doc/scheme-options.texi @@ -120,6 +120,7 @@ These functions set a non-boolean @var{option-symbol} to the specified 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. @@ -132,6 +133,7 @@ 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 @@ -142,6 +144,7 @@ To make Guile case insensitive, you can type 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. @@ -151,9 +154,16 @@ closure-hook #f Hook for printing closures. @node Evaluator options @section Evaluator options -Here is the list of print options generated by typing -@code{(traps 'full)} in Guile. You can also see the default -values. +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. @@ -167,6 +177,7 @@ enter-frame no Trap when eval enters new frame. 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.