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
parent
24259edb8b
commit
1518f64948
6 changed files with 113 additions and 198 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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} <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
|
||||
@subsubsection Debugger options
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue