diff --git a/collects/scribblings/reference/io.scrbl b/collects/scribblings/reference/io.scrbl index 8fe2e0634d..2b0853d90e 100644 --- a/collects/scribblings/reference/io.scrbl +++ b/collects/scribblings/reference/io.scrbl @@ -10,8 +10,6 @@ @include-section["string-output.scrbl"] @include-section["read.scrbl"] @include-section["write.scrbl"] -@include-section["reader.scrbl"] -@include-section["printer.scrbl"] @include-section["pretty-print.scrbl"] @include-section["readtables.scrbl"] @include-section["custom-write.scrbl"] diff --git a/collects/scribblings/reference/model.scrbl b/collects/scribblings/reference/model.scrbl index 1fe4705ce0..494f66de94 100644 --- a/collects/scribblings/reference/model.scrbl +++ b/collects/scribblings/reference/model.scrbl @@ -7,3 +7,5 @@ @include-section["eval-model.scrbl"] @include-section["syntax-model.scrbl"] +@include-section["reader.scrbl"] +@include-section["printer.scrbl"] diff --git a/collects/scribblings/reference/printer.scrbl b/collects/scribblings/reference/printer.scrbl index 4cd517d1d7..4a5ec9c927 100644 --- a/collects/scribblings/reference/printer.scrbl +++ b/collects/scribblings/reference/printer.scrbl @@ -50,7 +50,7 @@ print sharing through graph definitions and references (see then @racket[print-graph] is effectively set to @racket[#t] automatically. -With the exception of displaying byte strings, printing is defined in +With the exception of displaying @tech{byte strings}, printing is defined in terms of Unicode characters; see @secref["ports"] for information on how a character stream is written to a port's underlying byte stream. @@ -58,7 +58,7 @@ stream. @section[#:tag "print-symbol"]{Printing Symbols} -Symbols containing spaces or special characters @racket[write] using +@tech{Symbols} containing spaces or special characters @racket[write] using escaping @litchar{\} and quoting @litchar{|}s. When the @racket[read-case-sensitive] parameter is set to @racket[#f], then symbols containing uppercase characters also use escaping @@ -99,7 +99,7 @@ of printing enclosing datatypes, a symbol is @tech{quotable}. @section{Printing Numbers} -A number prints the same way in @racket[write], @racket[display], and +A @tech{number} prints the same way in @racket[write], @racket[display], and @racket[print] modes. For the purposes of printing enclosing datatypes, a symbol is @tech{quotable}. @@ -128,7 +128,7 @@ printed form of the number's exact negation. @section{Printing Booleans} -The constant @racket[#t] prints as @litchar{#true} or @litchar{#t} in +The @tech{boolean} constant @racket[#t] prints as @litchar{#true} or @litchar{#t} in all modes (@racket[display], @racket[write], and @racket[print]), depending on the value of @racket[print-boolean-long-form], and the constant @racket[#f] prints as @litchar{#false} or @litchar{#f}. For @@ -137,8 +137,8 @@ the purposes of printing enclosing datatypes, a symbol is @section[#:tag "print-pairs"]{Printing Pairs and Lists} -In @racket[write] and @racket[display] modes, an empty list prints as -@litchar{()}. A pair normally prints starting with @litchar{(} +In @racket[write] and @racket[display] modes, an empty @tech{list} prints as +@litchar{()}. A @tech{pair} normally prints starting with @litchar{(} followed by the printed form of its @racket[car]. The rest of the printed form depends on the @racket[cdr]: @@ -221,7 +221,7 @@ is never @tech{quotable}. @section{Printing Strings} -All strings @racket[display] as their literal character sequences. +All @tech{strings} @racket[display] as their literal character sequences. The @racket[write] or @racket[print] form of a string starts with @litchar{"} and ends with another @litchar{"}. Between the @litchar{"}s, each character is @@ -257,7 +257,7 @@ string is @tech{quotable}. @section[#:tag "print-vectors"]{Printing Vectors} -In @racket[display] mode, the printed form of a vector is @litchar{#} +In @racket[display] mode, the printed form of a @tech{vector} is @litchar{#} followed by the printed form of @racket[vector->list] applied to the vector. In @racket[write] mode, the printed form is the same, except that when the @racket[print-vector-length] parameter is @racket[#t], a @@ -279,7 +279,7 @@ its elements are @tech{quotable}. @section[#:tag "print-structure"]{Printing Structures} When the @racket[print-struct] parameter is set to @racket[#t], then -the way that structures print depends on details of the structure type +the way that @tech{structures} print depends on details of the structure type for which the structure is an instance: @itemize[ @@ -372,7 +372,7 @@ unreadable values (see @secref["print-unreadable"]) and count as @section[#:tag "print-hashtable"]{Printing Hash Tables} When the @racket[print-hash-table] parameter is set to @racket[#t], in -@racket[write] and @racket[display] modes, a hash table prints +@racket[write] and @racket[display] modes, a @tech{hash table} prints starting with @litchar{#hash(}, @litchar{#hasheqv(}, or @litchar{#hasheq(} for a table using @racket[equal?], @racket[eqv?], or @racket[eq?] key comparisons, respectively. After the prefix, each @@ -401,7 +401,7 @@ hash table prints as @litchar{#} and counts as @tech{quotable}. @section[#:tag "print-box"]{Printing Boxes} -When the @racket[print-box] parameter is set to @racket[#t], a box +When the @racket[print-box] parameter is set to @racket[#t], a @tech{box} prints as @litchar{#&} followed by the printed form of its content in @racket[write], @racket[display], or @racket[print] mode when @racket[print-as-expression] is @racket[#f] or the @tech{quoting @@ -421,7 +421,7 @@ prints as @litchar{#} and counts as @tech{quotable}. @section{Printing Characters} -Characters with the special names described in +@tech{Characters} with the special names described in @secref["parse-character"] @racket[write] and @racket[print] using the same name. (Some characters have multiple names; the @racket[#\newline] and @racket[#\nul] names are used instead of @@ -441,7 +441,7 @@ For the purposes of printing enclosing datatypes, a character is @section{Printing Keywords} -Keywords @racket[write], @racket[print], and @racket[display] the same +@tech{Keywords} @racket[write], @racket[print], and @racket[display] the same as symbols (see @secref["print-symbol"]) except with a leading @litchar{#:} (after any @litchar{'} prefix added in @racket[print] mode), and without special handling for an initial @litchar{#} or when @@ -454,7 +454,7 @@ For the purposes of printing enclosing datatypes, a keyword is @section{Printing Regular Expressions} -Regexp values @racket[write], @racket[display], and @racket[print] +@tech{Regexp values} @racket[write], @racket[display], and @racket[print] starting with @litchar{#px} (for @racket[pregexp]-based regexps) or @litchar{#rx} (for @racket[regexp]-based regexps) followed by the @racket[write] form of the regexp's source string or byte string. @@ -465,7 +465,7 @@ For the purposes of printing enclosing datatypes, a regexp value is @section[#:tag "print-path"]{Printing Paths} -Paths @racket[write] and @racket[print] as @litchar{#}. A +@tech{Paths} @racket[write] and @racket[print] as @litchar{#}. A path @racket[display]s the same as the string produced by @racket[path->string]. For the purposes of printing enclosing datatypes, a path counts as @tech{quotable}. diff --git a/collects/scribblings/reference/reader.scrbl b/collects/scribblings/reference/reader.scrbl index a184a8c09d..fd84e09fdd 100644 --- a/collects/scribblings/reference/reader.scrbl +++ b/collects/scribblings/reference/reader.scrbl @@ -28,7 +28,7 @@ or @racket[read-syntax] mode. In @racket[read-syntax] mode, the result is always a @techlink{syntax object} that includes source-location and (initially empty) lexical information wrapped around the sort of datum that @racket[read] mode would produce. In the -case of pairs, vectors, and boxes, the content is also +case of @tech{pairs}, @tech{vectors}, and @tech{box}es, the content is also wrapped recursively as a syntax object. Unless specified otherwise, this section describes the reader's behavior in @racket[read] mode, and @racket[read-syntax] mode does the same modulo wrapping of the final @@ -79,15 +79,15 @@ on the next character or characters in the input stream as follows: @dispatch-table[ - @dispatch[@litchar{(}]{starts a pair or list; see @secref["parse-pair"]} - @dispatch[@litchar{[}]{starts a pair or list; see @secref["parse-pair"]} - @dispatch[@litchar["{"]]{starts a pair or list; see @secref["parse-pair"]} + @dispatch[@litchar{(}]{starts a @tech{pair} or @tech{list}; see @secref["parse-pair"]} + @dispatch[@litchar{[}]{starts a @tech{pair} or @tech{list}; see @secref["parse-pair"]} + @dispatch[@litchar["{"]]{starts a @tech{pair} or @tech{list}; see @secref["parse-pair"]} @dispatch[@litchar{)}]{matches @litchar{(} or raises @Exn[exn:fail:read]} @dispatch[@litchar{]}]{matches @litchar{[} or raises @Exn[exn:fail:read]} @dispatch[@litchar["}"]]{matches @litchar["{"] or raises @Exn[exn:fail:read]} - @dispatch[@litchar{"}]{starts a string; see @secref["parse-string"]} + @dispatch[@litchar{"}]{starts a @tech{string}; see @secref["parse-string"]} @dispatch[@litchar{'}]{starts a quote; see @secref["parse-quote"]} @dispatch[@litchar{`}]{starts a quasiquote; see @secref["parse-quote"]} @dispatch[@litchar{,}]{starts a [splicing] unquote; see @secref["parse-quote"]} @@ -97,20 +97,20 @@ on the next character or characters in the input stream as follows: @dispatch[@cilitchar{#t}]{true; see @secref["parse-boolean"]} @dispatch[@cilitchar{#f}]{false; see @secref["parse-boolean"]} - @dispatch[@litchar{#(}]{starts a vector; see @secref["parse-vector"]} - @dispatch[@litchar{#[}]{starts a vector; see @secref["parse-vector"]} - @dispatch[@litchar["#{"]]{starts a vector; see @secref["parse-vector"]} + @dispatch[@litchar{#(}]{starts a @tech{vector}; see @secref["parse-vector"]} + @dispatch[@litchar{#[}]{starts a @tech{vector}; see @secref["parse-vector"]} + @dispatch[@litchar["#{"]]{starts a @tech{vector}; see @secref["parse-vector"]} - @dispatch[@litchar{#s(}]{starts a structure literal; see @secref["parse-structure"]} - @dispatch[@litchar{#s[}]{starts a structure literal; see @secref["parse-structure"]} - @dispatch[@litchar["#s{"]]{starts a structure literal; see @secref["parse-structure"]} + @dispatch[@litchar{#s(}]{starts a @tech{structure} literal; see @secref["parse-structure"]} + @dispatch[@litchar{#s[}]{starts a @tech{structure} literal; see @secref["parse-structure"]} + @dispatch[@litchar["#s{"]]{starts a @tech{structure} literal; see @secref["parse-structure"]} - @dispatch[@litchar{#\}]{starts a character; see @secref["parse-character"]} + @dispatch[@litchar{#\}]{starts a @tech{character}; see @secref["parse-character"]} - @dispatch[@litchar{#"}]{starts a byte string; see @secref["parse-string"]} - @dispatch[@litchar{#%}]{starts a symbol; see @secref["parse-symbol"]} - @dispatch[@litchar{#:}]{starts a keyword; see @secref["parse-keyword"]} - @dispatch[@litchar{#&}]{starts a box; see @secref["parse-box"]} + @dispatch[@litchar{#"}]{starts a @tech{byte string}; see @secref["parse-string"]} + @dispatch[@litchar{#%}]{starts a @tech{symbol}; see @secref["parse-symbol"]} + @dispatch[@litchar{#:}]{starts a @tech{keyword}; see @secref["parse-keyword"]} + @dispatch[@litchar{#&}]{starts a @tech{box}; see @secref["parse-box"]} @dispatch[@litchar{#|}]{starts a block comment; see @secref["parse-comment"]} @dispatch[@litchar{#;}]{starts an S-expression comment; see @secref["parse-comment"]} @@ -122,17 +122,17 @@ on the next character or characters in the input stream as follows: @dispatch[@litchar{#,}]{starts a syntax [splicing] unquote; see @secref["parse-quote"]} @dispatch[@litchar{#~}]{starts compiled code; see @secref["print-compiled"]} - @dispatch[@cilitchar{#i}]{starts a number; see @secref["parse-number"]} - @dispatch[@cilitchar{#e}]{starts a number; see @secref["parse-number"]} - @dispatch[@cilitchar{#x}]{starts a number; see @secref["parse-number"]} - @dispatch[@cilitchar{#o}]{starts a number; see @secref["parse-number"]} - @dispatch[@cilitchar{#d}]{starts a number; see @secref["parse-number"]} - @dispatch[@cilitchar{#b}]{starts a number; see @secref["parse-number"]} + @dispatch[@cilitchar{#i}]{starts a @tech{number}; see @secref["parse-number"]} + @dispatch[@cilitchar{#e}]{starts a @tech{number}; see @secref["parse-number"]} + @dispatch[@cilitchar{#x}]{starts a @tech{number}; see @secref["parse-number"]} + @dispatch[@cilitchar{#o}]{starts a @tech{number}; see @secref["parse-number"]} + @dispatch[@cilitchar{#d}]{starts a @tech{number}; see @secref["parse-number"]} + @dispatch[@cilitchar{#b}]{starts a @tech{number}; see @secref["parse-number"]} - @dispatch[@cilitchar["#<<"]]{starts a string; see @secref["parse-string"]} + @dispatch[@cilitchar["#<<"]]{starts a @tech{string}; see @secref["parse-string"]} - @dispatch[@litchar{#rx}]{starts a regular expression; see @secref["parse-regexp"]} - @dispatch[@litchar{#px}]{starts a regular expression; see @secref["parse-regexp"]} + @dispatch[@litchar{#rx}]{starts a @tech{regular expression}; see @secref["parse-regexp"]} + @dispatch[@litchar{#px}]{starts a @tech{regular expression}; see @secref["parse-regexp"]} @dispatch[@cilitchar{#ci}]{switches case sensitivity; see @secref["parse-symbol"]} @dispatch[@cilitchar{#cs}]{switches case sensitivity; see @secref["parse-symbol"]} @@ -141,7 +141,7 @@ on the next character or characters in the input stream as follows: @dispatch[@litchar{#hx}]{starts a Honu expression; see @secref["parse-honu"]} - @dispatch[@litchar{#hash}]{starts a hash table; see @secref["parse-hashtable"]} + @dispatch[@litchar{#hash}]{starts a @tech{hash table}; see @secref["parse-hashtable"]} @dispatch[@litchar{#reader}]{starts a reader extension use; see @secref["parse-reader"]} @dispatch[@litchar{#lang}]{starts a reader extension use; see @secref["parse-reader"]} @@ -152,7 +152,7 @@ on the next character or characters in the input stream as follows: @dispatch[@graph-defn[]]{binds a graph tag; see @secref["parse-graph"]} @dispatch[@graph-ref[]]{uses a graph tag; see @secref["parse-graph"]} - @dispatch[@italic{otherwise}]{starts a symbol; see @secref["parse-symbol"]} + @dispatch[@italic{otherwise}]{starts a @tech{symbol}; see @secref["parse-symbol"]} ] @@ -162,7 +162,7 @@ on the next character or characters in the input stream as follows: @guideintro["symbols"]{the syntax of symbols} A sequence that does not start with a delimiter or @litchar{#} is -parsed as either a symbol or a number (see +parsed as either a @tech{symbol} or a @tech{number} (see @secref["parse-number"]), except that @litchar{.} by itself is never parsed as a symbol or character (unless the @racket[read-accept-dot] parameter is set to @racket[#f]). A @@ -199,7 +199,7 @@ case-sensitive mode. @section-index["numbers" "parsing"] -A sequence that does not start with a delimiter is parsed as a number +A sequence that does not start with a delimiter is parsed as a @tech{number} when it matches the following grammar case-insenstively for @nonterm{number@sub{10}} (decimal), where @metavar{n} is a meta-meta-variable in the grammar. @@ -293,9 +293,9 @@ single-precision. A @as-index{@litchar{#true}}, @as-index{@litchar{#t}}, @as-index{@litchar{#T}} followed by a delimiter is the input syntax -for the boolean constant ``true,'' and @as-index{@litchar{#false}}, +for the @tech{boolean} constant ``true,'' and @as-index{@litchar{#false}}, @as-index{@litchar{#f}}, or @as-index{@litchar{#F}} followed by a -delimiter is the complete input syntax for the boolean constant +delimiter is the complete input syntax for the @tech{boolean} constant ``false.'' @@ -303,7 +303,7 @@ delimiter is the complete input syntax for the boolean constant When the reader encounters a @as-index{@litchar{(}}, @as-index{@litchar{[}}, or @as-index{@litchar["{"]}, it starts -parsing a pair or list; see @secref["pairs"] for information on pairs +parsing a @tech{pair} or @tech{list}; see @secref["pairs"] for information on pairs and lists. To parse the pair or list, the reader recursively reads data @@ -381,7 +381,7 @@ exception, instead of the infix conversion. @section-index["strings" "parsing"] When the reader encounters @as-index{@litchar{"}}, it begins parsing -characters to form a string. The string continues until it is +characters to form a @tech{string}. The string continues until it is terminated by another @litchar{"} (that is not escaped by @litchar{\}). @@ -450,9 +450,10 @@ constant, the @exnraise[exn:fail:read]. @guideintro["bytestrings"]{the syntax of byte strings} @section-index["byte strings" "parsing"] +@section-index["heredoc"] A string constant preceded by @litchar{#} is parsed as a -byte string. (That is, @as-index{@litchar{#"}} starts a byte-string +@tech{byte string}. (That is, @as-index{@litchar{#"}} starts a byte-string literal.) See @secref["bytestrings"] for information on byte strings. Byte-string constants support the same escape sequences as character strings, except @litchar{\u} and @litchar{\U}. @@ -483,7 +484,7 @@ encountered before a terminating line, the @exnraise[exn:fail:read]. @section[#:tag "parse-quote"]{Reading Quotes} When the reader enounters @as-index{@litchar{'}}, it recursively -reads one datum and forms a new list containing the symbol +reads one datum and forms a new list containing the @tech{symbol} @racket['quote] and the following datum. This convention is mainly useful for reading Racket code, where @racket['s] can be used as a shorthand for @racket[(code:quote s)]. @@ -545,7 +546,7 @@ file. @section[#:tag "parse-vector"]{Reading Vectors} When the reader encounters a @litchar{#(}, @litchar{#[}, or -@litchar["#{"], it starts parsing a vector; see @secref["vectors"] for +@litchar["#{"], it starts parsing a @tech{vector}; see @secref["vectors"] for information on vectors. The @litchar{#[} and @litchar["#{"] forms can be disabled through the @racket[read-square-bracket-as-paren] and @racket[read-curly-brace-as-paren] @tech{parameters}. @@ -608,7 +609,7 @@ indicated @tech{prefab} structure type, the @exnraise[exn:fail:read]. @section[#:tag "parse-hashtable"]{Reading Hash Tables} -A @as-index{@litchar{#hash}} starts an immutable hash-table constant +A @as-index{@litchar{#hash}} starts an immutable @tech{hash-table} constant with key matching based on @racket[equal?]. The characters after @litchar{hash} must parse as a list of pairs (see @secref["parse-pair"]) with a specific use of delimited @litchar{.}: @@ -641,7 +642,7 @@ In all cases, the table is constructed by adding each mapping to the @section[#:tag "parse-box"]{Reading Boxes} When the reader encounters a @as-index{@litchar{#&}}, it starts -parsing a box; see @secref["boxes"] for information on boxes. The +parsing a @tech{box}; see @secref["boxes"] for information on boxes. The content of the box is determined by recursively reading the next datum. @@ -657,7 +658,7 @@ content is also wrapped as a syntax object, and the box is immutable. @guideintro["characters"]{the syntax of characters} -A @as-index{@litchar{#\}} starts a character constant, which has +A @as-index{@litchar{#\}} starts a @tech{character} constant, which has one of the following forms: @itemize[ @@ -705,7 +706,7 @@ one of the following forms: @section[#:tag "parse-keyword"]{Reading Keywords} -A @as-index{@litchar{#:}} starts a keyword. The parsing of a keyword +A @as-index{@litchar{#:}} starts a @tech{keyword}. The parsing of a keyword after the @litchar{#:} is the same as for a symbol, including case-folding in case-insensitive mode, except that the part after @litchar{#:} is never parsed as a number. @@ -718,7 +719,7 @@ case-folding in case-insensitive mode, except that the part after @section[#:tag "parse-regexp"]{Reading Regular Expressions} A @as-index{@litchar{#rx}} or @as-index{@litchar{#px}} starts a -regular expression. The characters immediately after @litchar{#rx} or +@tech{regular expression}. The characters immediately after @litchar{#rx} or @litchar{#px} must parse as a string or byte string (see @secref["parse-string"]). A @litchar{#rx} prefix starts a regular expression as would be constructed by @racket[regexp], @litchar{#px}