summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rwxr-xr-xdoc/ref/api-data.texi8
-rw-r--r--doc/ref/api-debug.texi2
-rw-r--r--doc/ref/api-evaluation.texi120
-rw-r--r--doc/ref/api-io.texi29
-rw-r--r--doc/ref/api-options.texi150
-rw-r--r--doc/ref/srfi-modules.texi2
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} <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
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