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:
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)
|
(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)
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -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)
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue