From 1518f6494873c4bc4bced49d3e0e903f37c644c6 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Fri, 1 Oct 2010 11:09:28 +0200 Subject: [PATCH] move read and print options docs to the procedures they parameterize * doc/ref/api-evaluation.texi (Scheme Read): Fold all reader options docs into this section. Undocument read-options-interface. (Scheme Write): New section for `write' and `display', and the print options. print-enable/print-disable are not documented, as there are no boolean print options. print-options-interface is likewise undocumented. * doc/ref/api-options.texi: Remove discussion of options in general. Move read options to Scheme Read, and print options to Scheme Write. * doc/ref/api-io.texi (Reading): Link to Scheme Read. (Writing): Move write and display to Scheme Write, and link there. * doc/ref/srfi-modules.texi: * doc/ref/api-debug.texi: * doc/ref/api-data.texi: Update xrefs. --- doc/ref/api-data.texi | 8 +- doc/ref/api-debug.texi | 2 +- doc/ref/api-evaluation.texi | 120 ++++++++++++++++++++++++----- doc/ref/api-io.texi | 29 ++----- doc/ref/api-options.texi | 150 +----------------------------------- doc/ref/srfi-modules.texi | 2 +- 6 files changed, 113 insertions(+), 198 deletions(-) diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 82982e94b..caa5d8e99 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -2706,8 +2706,7 @@ it can be enabled with the reader option @code{r6rs-hex-escapes}. (read-enable 'r6rs-hex-escapes) @end lisp -More on reader options in general can be found at (@pxref{Reader -options}). +For more on reader options, @xref{Scheme Read}. @node String Predicates @subsubsection String Predicates @@ -5862,9 +5861,8 @@ recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}). Otherwise, tokens of this form are read as symbols. To enable and disable the alternative non-R5RS keyword syntax, you use -the @code{read-set!} procedure documented in @ref{User level options -interfaces} and @ref{Reader options}. Note that the @code{prefix} and -@code{postfix} syntax are mutually exclusive. +the @code{read-set!} procedure documented @ref{Scheme Read}. Note that +the @code{prefix} and @code{postfix} syntax are mutually exclusive. @lisp (read-set! keywords 'prefix) diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 3f22e14e6..04dc25c1c 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -220,7 +220,7 @@ In the latter case, no source properties were stored, so the error doesn't have any source information. The recording of source properties is controlled by the read option -named ``positions'' (@pxref{Reader options}). This option is switched +named ``positions'' (@pxref{Scheme Read}). This option is switched @emph{on} by default. The following procedures can be used to access and set the source diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 036e92a9c..a050a7919 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -13,6 +13,7 @@ loading, evaluating, and compiling Scheme code at run time. @menu * Scheme Syntax:: Standard and extended Scheme syntax. * Scheme Read:: Reading Scheme code. +* Scheme Write:: Writing Scheme values to a port. * Fly Evaluation:: Procedures for on the fly evaluation. * Compilation:: How to compile Scheme files and procedures. * Loading:: Loading Scheme code from file. @@ -265,8 +266,8 @@ Guile-Whuzzy 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}). +reader option @code{case-insensitive}. For more information on reader +options, @xref{Scheme Read}. @lisp (read-enable 'case-insensitive) @@ -307,25 +308,36 @@ 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{User level -options interfaces}. 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? +its read options. +@cindex options - read +@cindex read options @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 +Otherwise if @var{setting} is the symbol @code{help}, a complete options +description is displayed. @end deffn +The set of available options, and their default values, may be had by +invoking @code{read-options} at the prompt. + +@smalllisp +scheme@@(guile-user)> (read-options) +(square-brackets keywords #f positions) +scheme@@(guile-user)> (read-options 'help) +copy no Copy source code expressions. +positions yes Record positions of source code expressions. +case-insensitive no Convert symbols to lower case. +keywords #f Style of keyword recognition: #f, 'prefix or 'postfix. +r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes. +square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility. +@end smalllisp + +The boolean options may be toggled with @code{read-enable} and +@code{read-disable}. The non-boolean @code{keywords} option must be set +using @code{read-set!}. + @deffn {Scheme Procedure} read-enable option-name @deffnx {Scheme Procedure} read-disable option-name @deffnx {Scheme Procedure} read-set! option-name value @@ -334,11 +346,79 @@ 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}. +For example, to make @code{read} fold all symbols to their lower case +(perhaps for compatibility with older Scheme code), you can enter: + +@lisp +(read-enable 'case-insensitive) +@end lisp + +For more information on the effect of the @code{r6rs-hex-escapes} option, see +(@pxref{String Syntax}). + + +@node Scheme Write +@subsection Writing Scheme Values + +Any scheme value may be written to a port. Not all values may be read +back in (@pxref{Scheme Read}), however. + +@rnindex write +@rnindex print +@deffn {Scheme Procedure} write obj [port] +Send a representation of @var{obj} to @var{port} or to the current +output port if not given. + +The output is designed to be machine readable, and can be read back +with @code{read} (@pxref{Scheme Read}). Strings are printed in +double quotes, with escapes if necessary, and characters are printed in +@samp{#\} notation. +@end deffn + +@rnindex display +@deffn {Scheme Procedure} display obj [port] +Send a representation of @var{obj} to @var{port} or to the current +output port if not given. + +The output is designed for human readability, it differs from +@code{write} in that strings are printed without double quotes and +escapes, and characters are printed as per @code{write-char}, not in +@samp{#\} form. +@end deffn + +As was the case with the Scheme reader, there are a few options that +affect the behavior of the Scheme printer. + +@cindex options - print +@cindex print options +@deffn {Scheme Procedure} print-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 if @var{setting} is the symbol @code{help}, a +complete options description is displayed. +@end deffn + +The set of available options, and their default values, may be had by +invoking @code{print-options} at the prompt. + +@smalllisp +scheme@@(guile-user)> (print-options) +(quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{") +scheme@@(guile-user)> (print-options 'help) +highlight-prefix @{ The string to print before highlighted values. +highlight-suffix @} The string to print after highlighted values. +quote-keywordish-symbols reader How to print symbols that have a colon + as their first or last character. The + value '#f' does not quote the colons; + '#t' quotes them; 'reader' quotes them + when the reader option 'keywords' is + not '#f'. +@end smalllisp + +These options may be modified with the print-set! procedure. + +@deffn {Scheme Procedure} print-set! option-name value +Modify the print options. @end deffn diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 83474a166..e2b1b5164 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -174,6 +174,9 @@ created. [Generic procedures for reading from ports.] +These procedures pertain to reading characters and strings from +ports. To read general S-expressions from ports, @xref{Scheme Read}. + @rnindex eof-object? @cindex End of file object @deffn {Scheme Procedure} eof-object? x @@ -299,34 +302,16 @@ Set the current column or line number of @var{port}. [Generic procedures for writing to ports.] +These procedures are for writing characters and strings to +ports. For more information on writing arbitrary Scheme objects to +ports, @xref{Scheme Write}. + @deffn {Scheme Procedure} get-print-state port @deffnx {C Function} scm_get_print_state (port) Return the print state of the port @var{port}. If @var{port} has no associated print state, @code{#f} is returned. @end deffn -@rnindex write -@deffn {Scheme Procedure} write obj [port] -Send a representation of @var{obj} to @var{port} or to the current -output port if not given. - -The output is designed to be machine readable, and can be read back -with @code{read} (@pxref{Reading}). Strings are printed in -double quotes, with escapes if necessary, and characters are printed in -@samp{#\} notation. -@end deffn - -@rnindex display -@deffn {Scheme Procedure} display obj [port] -Send a representation of @var{obj} to @var{port} or to the current -output port if not given. - -The output is designed for human readability, it differs from -@code{write} in that strings are printed without double quotes and -escapes, and characters are printed as per @code{write-char}, not in -@samp{#\} form. -@end deffn - @rnindex newline @deffn {Scheme Procedure} newline [port] @deffnx {C Function} scm_newline (port) diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi index 3c25b196d..fdc8e85f7 100644 --- a/doc/ref/api-options.texi +++ b/doc/ref/api-options.texi @@ -383,162 +383,14 @@ 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}. +configure @emph{reading}, @emph{printing}, or @emph{debugging}. @menu -* Low level options interfaces:: -* User level options interfaces:: -* Reader options:: -* Printing options:: * Debugger options:: * Examples of option use:: @end menu -@node Low level options interfaces -@subsubsection Low Level Options Interfaces - -@deffn {Scheme Procedure} read-options-interface [setting] -@deffnx {Scheme Procedure} print-options-interface [setting] -@deffnx {Scheme Procedure} debug-options-interface [setting] -@deffnx {C Function} scm_read_options (setting) -@deffnx {C Function} scm_print_options (setting) -@deffnx {C Function} scm_debug_options (setting) -If one of these procedures is called with no arguments (or with -@code{setting == SCM_UNDEFINED} in C code), it returns a list describing -the current setting of the read, eval, print, debug or evaluator traps -options respectively. The setting of a boolean option is indicated -simply by the presence or absence of the option symbol in the list. The -setting of a non-boolean option is indicated by the presence of the -option symbol immediately followed by the option's current value. - -If called with a list argument, these procedures interpret the list as -an option setting and modify the relevant options accordingly. [FIXME ---- this glosses over a lot of details!] - -If called with any other argument, such as @code{'help}, these -procedures return a list of entries like @code{(@var{OPTION-SYMBOL} -@var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the -default value and documentation for each option symbol in the relevant -set of options. -@end deffn - - -@node User level options interfaces -@subsubsection User Level Options Interfaces - -@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 {Scheme Procedure} -options [arg] -@deffnx {Scheme Procedure} read-options [arg] -@deffnx {Scheme Procedure} print-options [arg] -@deffnx {Scheme Procedure} debug-options [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{-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 {Scheme Procedure} -enable option-symbol -@deffnx {Scheme Procedure} read-enable option-symbol -@deffnx {Scheme Procedure} print-enable option-symbol -@deffnx {Scheme Procedure} debug-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 {Scheme Procedure} -disable option-symbol -@deffnx {Scheme Procedure} read-disable option-symbol -@deffnx {Scheme Procedure} print-disable option-symbol -@deffnx {Scheme Procedure} debug-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 -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 -These functions set a non-boolean @var{option-symbol} to the specified -@var{value}. -@end deffn - - -@node Reader options -@subsubsection 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 -copy no Copy source code expressions. -positions yes Record positions of source code expressions. -case-insensitive no Convert symbols to lower case. -keywords #f Style of keyword recognition: #f, 'prefix or 'postfix. -r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes. -square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility. -@end smalllisp - -Historically, many Scheme implementations have been case-insensitive, -treating @code{foo} and @code{FOO} as the same symbol. Guile has always -defaulted to case-sensitivity, as allowed since the R4RS and codified in -the R6RS. - -Guile also has a reader option to fold all symbols to their lower -case. To enable this option, perhaps for compatibility with older Scheme -code, you can enter - -@lisp -(read-enable 'case-insensitive) -@end lisp - -For more information on the effect of the @code{r6rs-hex-escapes} option, see -(@pxref{String Syntax}). - -@node Printing options -@subsubsection 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 -quote-keywordish-symbols reader How to print symbols that have a colon - as their first or last character. The - value '#f' does not quote the colons; - '#t' quotes them; 'reader' quotes - them when the reader option - 'keywords' is not '#f'. - -highlight-prefix @{ The string to print before highlighted values. -highlight-suffix @} The string to print after highlighted values. -@end smallexample - - @node Debugger options @subsubsection Debugger options diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 188a71c8f..a277c4be9 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -4244,7 +4244,7 @@ Answer a hash value appropriate for equality predicate @code{equal?}, @dfn{keyword objects}, which are equivalent to Guile's keywords (@pxref{Keywords}). SRFI-88 keywords can be entered using the @dfn{postfix keyword syntax}, which consists of an identifier followed -by @code{:} (@pxref{Reader options, @code{postfix} keyword syntax}). +by @code{:} (@pxref{Scheme Read, @code{postfix} keyword syntax}). SRFI-88 can be made available with: @example -- 2.20.1