From 55f920223e3ec2249343cf4e52bf0eebc02c031b Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Sun, 28 Feb 2016 20:26:34 -0800 Subject: [PATCH] Document parser and unparser parameters. --- doc/ref-manual/io.texi | 93 +++++++++++++++++++++++++++++------------- 1 file changed, 64 insertions(+), 29 deletions(-) diff --git a/doc/ref-manual/io.texi b/doc/ref-manual/io.texi index 763b166f3..413fbb4c1 100644 --- a/doc/ref-manual/io.texi +++ b/doc/ref-manual/io.texi @@ -591,7 +591,7 @@ but the written representation is incomplete and therefore not parsable, an error is signalled. @var{Environment} is used to look up the values of control variables -such as @samp{*parser-radix*} (@pxref{reader-controls}). If not +such as @code{param:parser-radix} (@pxref{reader-controls}). If not supplied, it defaults to the @acronym{REP} environment. @end deffn @@ -710,33 +710,38 @@ amounts of data. @anchor{reader-controls} @subsection Reader Controls -The following names control the behavior of the @code{read} procedure. -They are looked up in the environment that is passed to @code{read}, -and so may have different values in different environments. The -global parameters may be dynamically bound by @code{parameterize}, but -should not be mutated. Make persistent, local changes by shadowing -the global bindings in the local environment and assigning new -parameters to them. +The following parameters control the behavior of the @code{read} +procedure. They are looked up in the environment that is passed to +@code{read}, and so may have different values in different +environments. The global parameters may be dynamically bound by +@code{parameterize}, but should not be mutated. Make persistent, +local changes by shadowing the global bindings in the local +environment and assigning new parameters to them. -@defvr variable *parser-radix* +@defvr parameter param:parser-radix This parameter defines the radix used by the reader when it parses numbers. This is similar to passing a radix argument to @code{string->number}. The value of the parameter must be one of -@code{2}, @code{8}, @code{10}, or @code{16}; any other value is ignored, -and the reader uses radix @code{10}. +@code{2}, @code{8}, @code{10}, or @code{16}; an error is signaled if +the parameter is bound to any other value. Note that much of the number syntax is invalid for radixes other than @code{10}. The reader detects cases where such invalid syntax is used and signals an error. However, problems can still occur when -@code{*parser-radix*} is set to @code{16}, because syntax that normally -denotes symbols can now denote numbers (e.g.@: @code{abc}). Because of -this, it is usually undesirable to set this parameter to anything other -than the default. +@code{param:parser-radix} is bound to @code{16}, because syntax that +normally denotes symbols can now denote numbers (e.g.@: @code{abc}). +Because of this, it is usually undesirable to bind this parameter to +anything other than the default. The default value of this parameter is @code{10}. @end defvr -@defvr variable *parser-canonicalize-symbols?* +@defvr variable *parser-radix* +This variable is @strong{deprecated}; use @code{param:parser-radix} +instead. +@end defvr + +@defvr parameter param:parser-canonicalize-symbols? This parameter controls how the parser handles case-sensitivity of symbols. If it is bound to its default value of @code{#t}, symbols read by the parser are converted to lower case before being interned. @@ -747,6 +752,11 @@ make Scheme case-sensitive, and therefore can break features of the Scheme runtime that depend on case-insensitive symbols. @end defvr +@defvr variable *parser-canonicalize-symbols?* +This variable is @strong{deprecated}; use +@code{param:parser-canonicalize-symbols?} instead. +@end defvr + @node Output Procedures, Format, Input Procedures, Input/Output @section Output Procedures @cindex output procedures @@ -893,14 +903,19 @@ performs discretionary output flushing and returns an unspecified value. The following variables may be dynamically bound to change the behavior of the @code{write} and @code{display} procedures. -@defvr variable *unparser-radix* +@defvr parameter param:unparser-radix This parameter specifies the default radix used to print numbers. Its value must be one of the exact integers @code{2}, @code{8}, @code{10}, -or @code{16}; the default is @code{10}. If @code{*unparser-radix*} is -not @code{10}, numbers are prefixed to indicate their radix. +or @code{16}; the default is @code{10}. For values other than +@code{10}, numbers are prefixed to indicate their radix. @end defvr -@defvr variable *unparser-list-breadth-limit* +@defvr variable *unparser-radix* +This variable is @strong{deprecated}; use @code{param:unparser-radix} +instead. +@end defvr + +@defvr parameter param:unparser-list-breadth-limit This parameter specifies a limit on the length of the printed representation of a list or vector; for example, if the limit is @code{4}, only the first four elements of any list are printed, followed @@ -910,11 +925,11 @@ limit; the default is @code{#f}. @example @group -(parameterize ((*unparser-list-breadth-limit* 4)) +(parameterize ((param:unparser-list-breadth-limit 4)) (lambda () (write-to-string '(a b c d)))) @result{} "(a b c d)" -(parameterize ((*unparser-list-breadth-limit* 4)) +(parameterize ((param:unparser-list-breadth-limit 4)) (lambda () (write-to-string '(a b c d e)))) @result{} "(a b c d ...)" @@ -922,7 +937,12 @@ limit; the default is @code{#f}. @end example @end defvr -@defvr variable *unparser-list-depth-limit* +@defvr variable *unparser-list-breadth-limit* +This variable is @strong{deprecated}; use +@code{param:unparser-list-breadth-limit} instead. +@end defvr + +@defvr parameter param:unparser-list-depth-limit This parameter specifies a limit on the nesting of lists and vectors in the printed representation. If lists (or vectors) are more deeply nested than the limit, the part of the representation that exceeds the @@ -932,11 +952,11 @@ is @code{#f}. @example @group -(parameterize((*unparser-list-depth-limit* 4)) +(parameterize ((param:unparser-list-depth-limit 4)) (lambda () (write-to-string '((((a))) b c d)))) @result{} "((((a))) b c d)" -(parameterize ((*unparser-list-depth-limit* 4)) +(parameterize ((param:unparser-list-depth-limit 4)) (lambda () (write-to-string '(((((a)))) b c d)))) @result{} "((((...))) b c d)" @@ -944,7 +964,12 @@ is @code{#f}. @end example @end defvr -@defvr variable *unparser-string-length-limit* +@defvr variable *unparser-list-depth-limit* +This variable is @strong{deprecated}; use +@code{param:unparser-list-depth-limit} instead. +@end defvr + +@defvr parameter param:unparser-string-length-limit This parameter specifies a limit on the length of the printed representation of strings. If a string's length exceeds this limit, the part of the printed representation for the characters exceeding the @@ -954,11 +979,11 @@ is @code{#f}. @example @group -(parameterize ((*unparser-string-length-limit* 4)) +(parameterize ((param:unparser-string-length-limit 4)) (lambda () (write-to-string "abcd"))) @result{} "\"abcd\"" -(parameterize ((*unparser-string-length-limit* 4)) +(parameterize ((param:unparser-string-length-limit 4)) (lambda () (write-to-string "abcde"))) @result{} "\"abcd...\"" @@ -966,7 +991,12 @@ is @code{#f}. @end example @end defvr -@defvr variable *unparse-with-maximum-readability?* +@defvr variable *unparser-string-length-limit* +This variable is @strong{deprecated}; use +@code{param:unparser-string-length-limit} instead. +@end defvr + +@defvr parameter param:unparse-with-maximum-readability? This parameter, which takes a boolean value, tells the printer to use a special printed representation for objects that normally print in a form that cannot be recognized by @code{read}. These objects are printed @@ -978,6 +1008,11 @@ recognized by the Scheme program in which it was generated, because these hash numbers are different for each invocation of Scheme. @end defvr +@defvr variable *unparse-with-maximum-readability?* +This variable is @strong{deprecated}; use +@code{param:unparse-with-maximum-readability?} instead. +@end defvr + @node Format, Custom Output, Output Procedures, Input/Output @section Format -- 2.25.1