1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 11:40:18 +02:00

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.
This commit is contained in:
Andy Wingo 2010-10-01 11:09:28 +02:00
parent 24259edb8b
commit 1518f64948
6 changed files with 113 additions and 198 deletions

View file

@ -2706,8 +2706,7 @@ it can be enabled with the reader option @code{r6rs-hex-escapes}.
(read-enable 'r6rs-hex-escapes) (read-enable 'r6rs-hex-escapes)
@end lisp @end lisp
More on reader options in general can be found at (@pxref{Reader For more on reader options, @xref{Scheme Read}.
options}).
@node String Predicates @node String Predicates
@subsubsection 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. Otherwise, tokens of this form are read as symbols.
To enable and disable the alternative non-R5RS keyword syntax, you use To enable and disable the alternative non-R5RS keyword syntax, you use
the @code{read-set!} procedure documented in @ref{User level options the @code{read-set!} procedure documented @ref{Scheme Read}. Note that
interfaces} and @ref{Reader options}. Note that the @code{prefix} and the @code{prefix} and @code{postfix} syntax are mutually exclusive.
@code{postfix} syntax are mutually exclusive.
@lisp @lisp
(read-set! keywords 'prefix) (read-set! keywords 'prefix)

View file

@ -220,7 +220,7 @@ In the latter case, no source properties were stored, so the error
doesn't have any source information. doesn't have any source information.
The recording of source properties is controlled by the read option 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. @emph{on} by default.
The following procedures can be used to access and set the source The following procedures can be used to access and set the source

View file

@ -13,6 +13,7 @@ loading, evaluating, and compiling Scheme code at run time.
@menu @menu
* Scheme Syntax:: Standard and extended Scheme syntax. * Scheme Syntax:: Standard and extended Scheme syntax.
* Scheme Read:: Reading Scheme code. * Scheme Read:: Reading Scheme code.
* Scheme Write:: Writing Scheme values to a port.
* Fly Evaluation:: Procedures for on the fly evaluation. * Fly Evaluation:: Procedures for on the fly evaluation.
* Compilation:: How to compile Scheme files and procedures. * Compilation:: How to compile Scheme files and procedures.
* Loading:: Loading Scheme code from file. * Loading:: Loading Scheme code from file.
@ -265,8 +266,8 @@ Guile-Whuzzy
are the same in R5RS Scheme, but are different in Guile. are the same in R5RS Scheme, but are different in Guile.
It is possible to turn off case sensitivity in Guile by setting the It is possible to turn off case sensitivity in Guile by setting the
reader option @code{case-insensitive}. More on reader options can be reader option @code{case-insensitive}. For more information on reader
found at (@pxref{Reader options}). options, @xref{Scheme Read}.
@lisp @lisp
(read-enable 'case-insensitive) (read-enable 'case-insensitive)
@ -307,25 +308,36 @@ Any whitespace before the next token is discarded.
@end deffn @end deffn
The behaviour of Guile's Scheme reader can be modified by manipulating The behaviour of Guile's Scheme reader can be modified by manipulating
its read options. For more information about options, @xref{User level its read options.
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?
@cindex options - read
@cindex read options
@deffn {Scheme Procedure} read-options [setting] @deffn {Scheme Procedure} read-options [setting]
Display the current settings of the read options. If @var{setting} is Display the current settings of the read options. If @var{setting} is
omitted, only a short form of the current read options is printed. omitted, only a short form of the current read options is printed.
Otherwise, @var{setting} should be one of the following symbols: Otherwise if @var{setting} is the symbol @code{help}, a complete options
@table @code description is displayed.
@item help
Display the complete option settings.
@item full
Like @code{help}, but also print programmer options.
@end table
@end deffn @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 @deffn {Scheme Procedure} read-enable option-name
@deffnx {Scheme Procedure} read-disable option-name @deffnx {Scheme Procedure} read-disable option-name
@deffnx {Scheme Procedure} read-set! option-name value @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. @code{read-set!} can be used to set an option to a specific value.
@end deffn @end deffn
@deffn {Scheme Procedure} read-options-interface [setting] For example, to make @code{read} fold all symbols to their lower case
@deffnx {C Function} scm_read_options (setting) (perhaps for compatibility with older Scheme code), you can enter:
Option interface for the read options. Instead of using
this procedure directly, use the procedures @code{read-enable}, @lisp
@code{read-disable}, @code{read-set!} and @code{read-options}. (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 @end deffn

View file

@ -174,6 +174,9 @@ created.
[Generic procedures for reading from ports.] [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? @rnindex eof-object?
@cindex End of file object @cindex End of file object
@deffn {Scheme Procedure} eof-object? x @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.] [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 @deffn {Scheme Procedure} get-print-state port
@deffnx {C Function} scm_get_print_state (port) @deffnx {C Function} scm_get_print_state (port)
Return the print state of the port @var{port}. If @var{port} Return the print state of the port @var{port}. If @var{port}
has no associated print state, @code{#f} is returned. has no associated print state, @code{#f} is returned.
@end deffn @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 @rnindex newline
@deffn {Scheme Procedure} newline [port] @deffn {Scheme Procedure} newline [port]
@deffnx {C Function} scm_newline (port) @deffnx {C Function} scm_newline (port)

View file

@ -383,162 +383,14 @@ control interface, and a user-level interface which allows the enabling
or disabling of options. or disabling of options.
Moreover, the options are classified in groups according to whether they Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or configure @emph{reading}, @emph{printing}, or @emph{debugging}.
@emph{evaluating}.
@menu @menu
* Low level options interfaces::
* User level options interfaces::
* Reader options::
* Printing options::
* Debugger options:: * Debugger options::
* Examples of option use:: * Examples of option use::
@end menu @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} <group>-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{<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 {Scheme Procedure} <group>-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} <group>-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 <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
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 @node Debugger options
@subsubsection Debugger options @subsubsection Debugger options

View file

@ -4244,7 +4244,7 @@ Answer a hash value appropriate for equality predicate @code{equal?},
@dfn{keyword objects}, which are equivalent to Guile's keywords @dfn{keyword objects}, which are equivalent to Guile's keywords
(@pxref{Keywords}). SRFI-88 keywords can be entered using the (@pxref{Keywords}). SRFI-88 keywords can be entered using the
@dfn{postfix keyword syntax}, which consists of an identifier followed @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: SRFI-88 can be made available with:
@example @example