diff --git a/collects/scribble/base-render.ss b/collects/scribble/base-render.ss index d47de35db6..3236539d34 100644 --- a/collects/scribble/base-render.ss +++ b/collects/scribble/base-render.ss @@ -285,9 +285,13 @@ (define/private (render-toc part base-len skip?) (let ([number (collected-info-number (part-collected-info part))]) (let ([subs - (apply - append - (map (lambda (p) (render-toc p base-len #f)) (part-parts part)))]) + (if (not (and (styled-part? part) + (eq? 'quiet (styled-part-style part)) + (not (= base-len (sub1 (length number)))))) + (apply + append + (map (lambda (p) (render-toc p base-len #f)) (part-parts part))) + null)]) (if skip? subs (let ([l (cons diff --git a/collects/scribble/reader.ss b/collects/scribble/reader.ss index 5b2c384956..1c76e41131 100644 --- a/collects/scribble/reader.ss +++ b/collects/scribble/reader.ss @@ -331,6 +331,7 @@ (define (get-lines* re:begin re:end re:item end-token) ;; re:begin, re:end, end-token can be false if start-inside? is #t + (let-values ([(start-line start-col start-pos) (port-next-location inp)]) (let loop ([lvl 0] [r '()]) (let-values ([(line col pos) (port-next-location inp)]) (define (make-stx sexpr) @@ -395,9 +396,12 @@ r)))] [(*peek #rx#"^$") (if end-token - (read-error 'eof "missing closing `~a'" end-token) + (read-error 'eof "missing closing `~a'~a" end-token + (if start-line + (format " (started at ~a:~a)" start-line start-col) + "")) (done-lines r))] - [else (read-error "internal error [get-lines*]")])))) + [else (read-error "internal error [get-lines*]")]))))) (define (get-lines) (cond [(*skip re:lines-begin) diff --git a/collects/scribblings/reference/io.scrbl b/collects/scribblings/reference/io.scrbl index e1a21f2844..81cc0fe4fc 100644 --- a/collects/scribblings/reference/io.scrbl +++ b/collects/scribblings/reference/io.scrbl @@ -1,5 +1,4 @@ #reader(lib "docreader.ss" "scribble") -@require[(lib "bnf.ss" "scribble")] @require["mz.ss"] @title[#:tag "mz:input-and-output" #:style 'toc]{Input and Output} @@ -12,3 +11,5 @@ @include-section["read.scrbl"] @include-section["write.scrbl"] @include-section["reader.scrbl"] +@include-section["printer.scrbl"] +@include-section["readtables.scrbl"] diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index 42795ca3a0..ce85f656c8 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -5,20 +5,20 @@ @guideintro["guide:numbers"]{numbers} -All numbers are @idefterm{complex numbers}. Some of them are -@idefterm{real numbers}, and all of the real numbers that can be -represented are also @idefterm{rational numbers}. Among the real -numbers, some are @idefterm{integers}, because @scheme[round] applied +All numbers are @deftech{complex numbers}. Some of them are +@deftech{real numbers}, and all of the real numbers that can be +represented are also @deftech{rational numbers}. Among the real +numbers, some are @deftech{integers}, because @scheme[round] applied to the number produces the same number. -Orthogonal to those categories, each number is also either -@idefterm{exact} or @idefterm{inexact}. Unless otherwise specified, -computations that involve an inexact number produce inexact -results. Certain operations on inexact numbers, however, produce an -exact number, such as multiplying an inexact number with an exact -@scheme[0]. Some operations, which can produce an irrational number -for rational arguments (e.g., @scheme[sqrt]), may produce inexact -results even for exact arguments. +Orthogonal to those categories, each number is also either an +@deftech{exact number} or an @deftech{inexact number}. Unless +otherwise specified, computations that involve an inexact number +produce inexact results. Certain operations on inexact numbers, +however, produce an exact number, such as multiplying an inexact +number with an exact @scheme[0]. Some operations, which can produce an +irrational number for rational arguments (e.g., @scheme[sqrt]), may +produce inexact results even for exact arguments. In the case of complex numbers, either the real and imaginary parts are both exact or inexact, or the number has an exact zero real part diff --git a/collects/scribblings/reference/os.scrbl b/collects/scribblings/reference/os.scrbl new file mode 100644 index 0000000000..ef106222ac --- /dev/null +++ b/collects/scribblings/reference/os.scrbl @@ -0,0 +1,8 @@ +#reader(lib "docreader.ss" "scribble") +@require["mz.ss"] + +@title[#:tag "mz:os" #:style 'toc]{Operating System} + +@local-table-of-contents[] + +@include-section["platform-paths.scrbl"] diff --git a/collects/scribblings/reference/platform-paths.scrbl b/collects/scribblings/reference/platform-paths.scrbl new file mode 100644 index 0000000000..a76a6307ce --- /dev/null +++ b/collects/scribblings/reference/platform-paths.scrbl @@ -0,0 +1,366 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "bnf.ss" "scribble")] +@require["mz.ss"] + +@define[(fileFirst s) (index (list s) (file s))] +@define[MzAdd (italic "Scheme-specific:")] + +@title{Platform-Specific Path Conventions} + +@section[#:tag "mz:unixpaths"]{@|AllUnix| Paths} + +In @|AllUnix| paths, a @litchar{/} separates elements of the path, +@litchar{.} as a path element always means the directory indicated by +preceding path, and @litchar{..} as a path element always means the +parent of the directory indicated by the preceding path. A path that +starts with a @litchar{~} indicates a user's home directory; the +username follows the @litchar{~} (before a @litchar{/} or the end of +the path), where @litchar{~} by itself indicates the home directory of +the current user. No other character or byte has a special meaning +within a path. Multiple adjacent @litchar{/} are equivalent to a +single @litchar{/} (i.e., they act as a single path separator). + +A path root is either @litchar{/} or a home-directory specification +starting with @litchar{~}. A relative path whose first element starts +with a @litchar{~} is encoded by prefixing the path with @litchar{./}. + +Any pathname that ends with a @litchar{/} syntactically refers to a +directory, as does any path whose last element is @litchar{.} or +@litchar{..}, or any path that contains only a root. + +A @|AllUnix| path is @tech{expanded} by replacing a home-directory +specification (starting with @litchar{~}) with an absolute path, and by +replacing multiple adjacent @litchar{/}s with a single @litchar{/}. + +For @scheme[(bytes->path-element _bstr)], @scheme[bstr] can start with +a @litchar{~}, and it is encoded as a literal part of the path element +using a @litchar{./} prefix. The @scheme[_bstr] argument must not +contain @litchar{/}, otherwise the @exnraise[exn:fail:contract]. + +For @scheme[(path-element->bytes _path)] or +@scheme[(path-element->string _path)], if the bytes form of +@scheme[_path] starts with @litchar{~/.}, the @litchar{./} prefix is +not included in the result. + +For @scheme[(build-path _base-path _sub-path ...)], when a +@scheme[_sub-path] starts with @litchar{./~}, the @litchar{./} is +removed before adding the path. This conversion is performed because +an initial sequence @litchar{./~} is the canonical way of representing +relative paths whose first element's name starts with @litchar{~}. + +For @scheme[(simplify-path _path _use-filesystem?)], if @scheme[_path] +starts @litchar{./~}, the leading period is the only indicator, and +there are no redundant @litchar{/}s, then @scheme[_path] is returned. + +For @scheme[(split-path _path)] producing @scheme[_base], +@scheme[_name], and @scheme[_must-be-dir?], the result @scheme[name] +can start with @litchar{./~} if the result would otherwise start with +@litchar{~} and it is not the start of @scheme[_path]. Furthermore, if +@scheme[path] starts with @litchar{./~} with any non-zero number of +@litchar{/}s between @litchar{.} and @litchar{~}, then the +@litchar{./} is kept with the following element (i.e., they are not +split separately). + +Under Mac OS X, Finder aliases are zero-length files. + +@;------------------------------------------------------------------------ +@section[#:tag "mz:windowspaths"]{Windows Path Conventions} + +In general, a Windows pathname consists of an optional drive specifier +and a drive-specific path. As noted in @secref["mz:filesystem"], a +Windows path can be @defterm{absolute} but still relative to the +current drive; such paths start with a @litchar{/} or @litchar["\\"] +separator and are not UNC paths or paths that start with +@litchar["\\\\?\\"]. + +A path that starts with a drive specification is @defterm{complete}. +Roughly, a drive specification is either a Roman letter followed by a +colon, a UNC path of the form +@litchar["\\\\"]@nonterm{machine}@litchar["\\"]@nonterm{volume}, or a +@litchar["\\\\?\\"] form followed by something other than +@litchar["REL\\"]@nonterm{element}, or +@litchar["RED\\"]@nonterm{element}. (Variants of @litchar["\\\\?\\"] +paths are described further below.) + +Scheme fails to implement the usual Windows path syntax in one +way. Outside of Scheme, a pathname @file{C:rant.txt} can be a +drive-specific relative path. That is, it names a file @file{rant.txt} +on drive @file{C:}, but the complete path to the file is determined by +the current working directory for drive @file{C:}. Scheme does not +support drive-specific working directories (only a working directory +across all drives, as reflected by the @scheme[current-directory] +parameter). Consequently, Scheme implicitly converts a path like +@file{C:rant.txt} into @file["C:\\rant.txt"]. + +@itemize{ + + @item{@|MzAdd| Whenever a path starts with a drive specifier + @nonterm{letter}@litchar{:} that is not followed by a + @litchar{/} or @litchar["\\"], a @litchar["\\"] is inserted as + the path is expanded.} + +} + + +Otherwise, Scheme follows standard Windows path conventions, but also + adds @litchar["\\\\?\\REL"] and @litchar["\\\\?\\RED"] conventions to + deal with paths inexpressible in the standard conventsion, plus + conventions to deal with excessive @litchar["\\"]s in @litchar["\\\\?\\"] + paths. + +In the following, @nonterm{letter} stands for a Roman letter (case +does not matter), @nonterm{machine} stands for any sequence of +characters that does not include @litchar["\\"] or @litchar{/} and is +not @litchar{?}, @nonterm{volume} stands for any sequence of +characters that does not include @litchar["\\"] or @litchar{/} , and +@nonterm{element} stands for any sequence of characters that does not +include @litchar["\\"]. + + @itemize{ + + @item{Trailing spaces and @litchar{.} in a path element are ignored + when the element is the last one in the path, unless the path + starts with @litchar["\\\\?\\"] or the element consists of only + spaces and @litchar{.}s.} + + @item{The following special ``files'', which access devices, exist in + all directories, case-insensitively, and with all possible + endings after a period or colon, except in pathnames that start + with @litchar["\\\\?\\"]: @fileFirst{NUL}, @fileFirst{CON}, + @fileFirst{PRN}, @fileFirst{AUX}, @fileFirst{COM1}, + @fileFirst{COM2}, @fileFirst{COM3}, @fileFirst{COM4}, + @fileFirst{COM5}, @fileFirst{COM6}, @fileFirst{COM7}, + @fileFirst{COM8}, @fileFirst{COM9}, @fileFirst{LPT1}, + @fileFirst{LPT2}, @fileFirst{LPT3}, @fileFirst{LPT4}, + @fileFirst{LPT5}, @fileFirst{LPT6}, @fileFirst{LPT7}, + @fileFirst{LPT8}, @fileFirst{LPT9}.} + + @item{Except for @litchar["\\\\?\\"] paths, @litchar{/}s are + equivalent to @litchar["\\"]s. Except for @litchar["\\\\?\\"] + paths and the start of UNC paths, multiple adjacent + @litchar{/}s and @litchar["\\"]s count as a single + @litchar["\\"]. In a path that starts @litchar["\\\\?\\"] + paths, elements can be separated by either a single or double + @litchar["\\"].} + + @item{A directory can be accessed with or without a trailing + separator. In the case of a non-@litchar["\\\\?\\"] path, the + trailing separator can be any number of @litchar{/}s and + @litchar["\\"]s; in the case of a @litchar["\\\\?\\"] path, a + trailing separator must be a single @litchar["\\"], except that + two @litchar["\\"]s can follow + @litchar["\\\\?\\"]@nonterm{letter}@litchar{:}.} + + @item{Except for @litchar["\\\\?\\"] paths, a single @litchar{.} as a + path element means ``the current directory,'' and a + @litchar{..} as a path element means ``the parent directory.'' + Up-directory path elements (i.e., @litchar{..}) immediately + after a drive are ignored.} + + @item{A pathname that starts + @litchar["\\\\"]@nonterm{machine}@litchar["\\"]@nonterm{volume} + (where a @litchar{/} can replace any @litchar["\\"]) is a UNC + path, and the starting + @litchar["\\\\"]@nonterm{machine}@litchar["\\"]@nonterm{volume} + counts as the drive specifier.} + + @item{Normally, a path element cannot contain any of the following + characters: + + @centerline{@litchar{<} @litchar{>} @litchar{:} @litchar{"} @litchar{/} @litchar["\\"] @litchar["|"]} + + Except for @litchar["\\"], path elements containing these + characters can be accessed using a @litchar["\\\\?\\"] path + (assuming that the underlying filesystem allows the + characters).} + + @item{In a pathname that starts + @litchar["\\\\?\\"]@nonterm{letter}@litchar[":\\"], the + @litchar["\\\\?\\"]@nonterm{letter}@litchar[":\\"] prefix + counts as the path's drive, as long as the path does not both + contain non-drive elements and end with two consecutive + @litchar["\\"]s, and as long as the path contains no sequence + of three or more @litchar["\\"]s. Two @litchar["\\"]s can + appear in place of the @litchar["\\"] before + @nonterm{letter}. A @litchar{/} cannot be used in place of a + @litchar["\\"] (but @litchar{/}s can be used in element names, + though the result typically does not name an actual directory + or file).} + + @item{In a pathname that starts + @litchar["\\\\?\\UNC\\"]@nonterm{machine}@litchar["\\"]@nonterm{volume}, + the + @litchar["\\\\?\\UNC\\"]@nonterm{machine}@litchar["\\"]@nonterm{volume} + prefix counts as the path's drive, as long as the path does + not end with two consecutive @litchar["\\"]s, and as long as + the path contains no sequence of three or more + @litchar["\\"]s. Two @litchar["\\"]s can appear in place of + the @litchar["\\"] before @litchar{UNC}, the @litchar["\\"]s + after @litchar{UNC}, and/or the @litchar["\\"]s + after@nonterm{machine}. The letters in the @litchar{UNC} part + can be uppercase or lowercase, and @litchar{/} cannot be used + in place of @litchar["\\"]s (but @litchar{/} can be used in + element names).} + + @item{@|MzAdd| A pathname that starts + @litchar["\\\\?\\REL\\"]@nonterm{element} or + @litchar["\\\\?\\REL\\\\"]@nonterm{element} is a relative + path, as long as the path does not end with two consecutive + @litchar["\\"]s, and as long as the path contains no sequence of + three or more @litchar["\\"]s. This Scheme-specific path form + supports relative paths with elements that are not normally + expressible in Windows paths (e.g., a final element that ends + in a space). The @litchar{REL} part must be exactly the three + uppercase letters, and @litchar{/}s cannot be used in place + of @litchar["\\"]s. If the path starts + @litchar["\\\\?\\REL\\.."] then for as long as the + path continues with repetitions of @litchar["\\.."], + each element counts as an up-directory element; a single + @litchar["\\"] must be used to separate the up-directory + elements. As soon as a second @litchar["\\"] is used to separate + the elements, or as soon as a non-@litchar{..} element is + encountered, the remaining elements are all literals (never + up-directory elements). When a @litchar["\\\\?\\REL"] path + value is converted to a string (or when the path value is + written or displayed), the string does not contain the + starting @litchar["\\\\?\\REL"] or the immediately following + @litchar["\\"]s; converting a path value to a byte string + preserves the @litchar["\\\\?\\REL"] prefix.} + + @item{@|MzAdd| A pathname that starts + @litchar["\\\\?\\RED\\"]@nonterm{element} or + @litchar["\\\\?\\RED\\\\"]@nonterm{element} is a + drive-relative path, as long as the path does not end with two + consecutive @litchar["\\"]s, and as long as the path contains + no sequence of three or more @litchar["\\"]s. This + Scheme-specific path form supports drive-relative paths (i.e., + absolute given a drive) with elements that are not normally + expressible in Windows paths. The @litchar{RED} part must be + exactly the three uppercase letters, and @litchar{/}s cannot + be used in place of @litchar["\\"]s. Unlike + @litchar["\\\\?\\REL"] paths, a @litchar{..} element is always + a literal path element. When a @litchar["\\\\?\\RED"] path + value is converted to a string (or when the path value is + written or displayed), the string does not contain the + starting @litchar["\\\\?\\RED"] and it contains a single + starting @litchar["\\"]; converting a path value to a byte + string preserves the @litchar["\\\\?\\RED"] prefix.} + +} + +Three additional Scheme-specific rules provide meanings to character +sequences that are otherwise ill-formed as Windows paths: + +@itemize{ + + @item{@|MzAdd| In a pathname of the form + @litchar["\\\\?\\"]@nonterm{any}@litchar["\\\\"] where + @nonterm{any} is any non-empty sequence of characters other + than @nonterm{letter}@litchar{:} or + @litchar["\\"]@nonterm{letter}@litchar{:}, the entire path + counts as the path's (non-existent) drive.} + + @item{@|MzAdd| In a pathname of the form + @litchar["\\\\?\\"]@nonterm{any}@litchar["\\\\\\"]@nonterm{elements}, + where @nonterm{any} is any non-empty sequence of characters + and @nonterm{elements} is any sequence that does not start + with a @litchar["\\"], does not end with two @litchar["\\"]s, + and does not contain a sequence of three @litchar["\\"]s, then + @litchar["\\\\?\\"]@nonterm{any}@litchar["\\\\"] counts as the + path's (non-existent) drive.} + + @item{@|MzAdd| In a pathname that starts @litchar["\\\\?\\"] and + does not match any of the patterns from the preceding bullets, + @litchar["\\\\?\\"] counts as the path's (non-existent) + drive.} + +} + +Outside of Scheme, except for @litchar["\\\\?\\"] paths, pathnames are + typically limited to 259 characters. Scheme internally converts + pathnames to @litchar["\\\\?\\"] form as needed to avoid this + limit. The operating system cannot access files through + @litchar["\\\\?\\"] paths that are longer than 32,000 characters or + so. + +Where the above descriptions says ``character,'' substitute ``byte'' +for interpreting byte strings as paths. The encoding of Windows paths +into bytes preserves ASCII characters, and all special characters +mentioned above are ASCII, so all of the rules are the same. + +Beware that the @litchar["\\"] path separator is an escape character +in Scheme strings. Thus, the path @litchar["\\\\?\\REL\\..\\\\.."] as +a string must be written @scheme["\\\\?\\REL\\..\\\\.."]. + +A path that ends with a directory separator syntactically refers to a +directory. In addition, a path syntactcially refers to a directory if +its last element is a same-directory or up-directory indicator (not +quoted by a @litchar["\\\\?\\"] form), or if it refers to a root. + +Windows paths are expanded as follows: In paths that start +@litchar["\\\\?\\"], redundant @litchar["\\"]s are removed, an extra +@litchar["\\"] is added in a @litchar["\\\\?\\REL"] if an extra one is +not already present to separate up-directory indicators from literal +path elements, and an extra @litchar["\\"] is similarly added after +@litchar["\\\\?\\RED"] if an extra one is not already present. When +@litchar["\\\\?\\"] acts as the root and the path contains, to +additional @litchar{/}s (which might otherwise be redundant) are +included after the root. For other paths, multiple @litchar{/}s are +converted to single @litchar{/}s (except at the beginning of a shared +folder name), a @litchar{/} is inserted after the colon in a drive +specification if it is missing. + +For @scheme[(bytes->path-element _bstr)], @litchar{/}s, colons, +trailing dots, trailing whitespace, and special device names (e.g., +``aux'') in @scheme[_bstr] are encoded as a literal part of the path +element by using a @litchar["\\\\?\\REL"] prefix. The @scheme[bstr] +argument must not contain a @litchar["\\"], otherwise the +@exnraise[exn:fail:contract]. + +For @scheme[(path-element->bytes _path)] or +@scheme[(path-element->string _path)], if the byte-string form of +@scheme[_path] starts with a @litchar["\\\\?\\REL"], the prefix is not +included in the result. + +For @scheme[(build-path _base-path _sub-path ...)], trailing spaces +and periods are removed from the last element of @scheme[_base-path] +and all but the last @scheme[_sub-path] (unless the element consists of +only spaces and peroids), except for those that start with +@litchar["\\\\?\\"]. If @scheme[_base-path] starts @litchar["\\\\?\\"], +then after each non-@litchar["\\\\?\\REL\\"] and +non-@litchar["\\\\?\\RED\\"] @scheme[_sub-path] is added, all +@litchar{/}s in the addition are converted to @litchar["\\"]s, +multiple consecutive @litchar["\\"]s are converted to a single +@litchar["\\"], added @litchar{.} elements are removed, and added +@litchar{..} elements are removed along with the preceding element; +these conversions are not performed on the original @scheme[_base-path] +part of the result or on any @litchar["\\\\?\\REL\\"] or +@litchar["\\\\?\\RED\\"] or @scheme[_sub-path]. If a +@litchar["\\\\?\\REL\\"] or @litchar["\\\\?\\RED\\"] +@scheme[_sub-path] is added to a non-@litchar["\\\\?\\"] +@scheme[_base-path], the the @scheme[_base-path] (with any additions up +to the @litchar["\\\\?\\REL\\"] or @litchar["\\\\?\\RED\\"] +@scheme[_sub-path]) is simplified and converted to a +@litchar["\\\\?\\"] path. In other cases, a @litchar["\\"] may be +added or removed before combining paths to avoid changing the root +meaning of the path (e.g., combining @litchar{//x} and @litchar{y} +produces @litchar{/x/y}, because @litchar{//x/y} would be a UNC path +instead of a drive-relative path). + +For @scheme[(simplify-path _path _use-filesystem?)], @scheme[_path] is +expanded, and if @scheme[_path] does not start with +@litchar["\\\\?\\"], trailing spaces and periods are removed, a +@litchar{/} is inserted after the colon in a drive specification if it +is missing, and a @litchar["\\"] is inserted after @litchar["\\\\?\\"] +as a root if there are elements and no extra @litchar["\\"] +already. Otherwise, if no indicators or redundant separators are in +@scheme[_path], then @scheme[_path] is returned. + +For @scheme[(split-path _path)] producing @scheme[_base], +@scheme[_name], and @scheme[_must-be-dir?], splitting a path that does +not start with @litchar["\\\\?\\"] can produce parts that start with +@litchar["\\\\?\\"]. For example, splitting @litchar{C:/x~/aux/} +produces @litchar["\\\\?\\C:\\x~\\"] and @litchar["\\\\?\\REL\\\\aux"]; +the @litchar["\\\\?\\"] is needed in these cases to preserve a +trailing space after @litchar{x} and to avoid referring to the AUX +device instead of an @file{aux} file. diff --git a/collects/scribblings/reference/port-line-counting.scrbl b/collects/scribblings/reference/port-line-counting.scrbl index 4ba6137184..e64f807e4c 100644 --- a/collects/scribblings/reference/port-line-counting.scrbl +++ b/collects/scribblings/reference/port-line-counting.scrbl @@ -61,3 +61,10 @@ read from or written to the port, but if line/character counting is enabled for @scheme[port], the column and position results can decrease after reading or writing a byte that ends a UTF-8 encoding sequence.} + +@defboolparam[port-count-lines-enabled on?]{ + +A parameter that determines whether line counting is enabled +automatically for newly created ports. The default value is +@scheme[#f].} + diff --git a/collects/scribblings/reference/printer.scrbl b/collects/scribblings/reference/printer.scrbl new file mode 100644 index 0000000000..c607450ec2 --- /dev/null +++ b/collects/scribblings/reference/printer.scrbl @@ -0,0 +1,218 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "bnf.ss" "scribble")] +@require["mz.ss"] + +@title[#:tag "mz:printing" #:style 'quiet]{The Printer} + +The default printer generally prints core datatypes in such a way that +using @scheme[read] on the output produces a value that is +@scheme[equal?] to the printed value---when the printed is used in +@scheme[write]. When the printer is used in @scheme[display] mode, the +printing of strings, byte strings, characters, and symbols changes to +render the character/byte content directly to the output port. + +When the @scheme[print-graph] parameter is set to @scheme[#t], then +the printer first scans an object to detect cycles. The scan traverses +the components of pairs, vectors, boxes (when @scheme[print-box] is +@scheme[#t]), hash tables (when @scheme[print-hash-table] is +@scheme[#t]), and fields of structures exposed by +@scheme[struct->vector] (when @scheme[print-struct] is +@scheme[#t]). If @scheme[print-graph] is @scheme[#t], then this +information is used to display sharing by printing graph definitions +and references (see @secref["mz:parse-graph"]). If a cycle is detected +in the initial scan, then @scheme[print-graph] is effectively set to +@scheme[#t] automatically. + +With the exception of displaying byte strings, printing is defined in +terms of Unicode characters; see @secref["mz:ports"] for information +on how a character stream is written to an port's underlying byte +stream. + +@local-table-of-contents[] + +@section[#:tag "mz:print-symbol"]{Printing Symbols} + +Symbols containing spaces or special characters @scheme[write] using +escaping @litchar["\\"] and quoting @litchar{|}s. When the +@scheme[read-case-sensitive] parameter is set to @scheme[#f], then +symbols containing uppercase characters also use escaping escaping +@litchar["\\"] and quoting @litchar{|}s. In addition, symbols are +quoted with @litchar{|}s or leading @litchar["\\"] when they would +otherwise print the same as a numerical constant or as a delimited +@scheme{.} (when @scheme[read-accept-dot] is @scheme[#t]). + +When @scheme[read-accept-bar-quote] is @scheme[#t], @litchar{|}s are +used in printing when one @litchar{|} at the beginning and one +@litchar{|} at the end suffices to correctly print the +symbol. Otherwise, @litchar["\\"]s are always used to escape special +characters, instead of quoting them with @litchar{|}s. + +When @scheme[read-accept-bar-quote] is @scheme[#f], then @litchar{|} +is not treated as a special character. The following are always +special characters: + +@t{ + @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} + @litchar["["] @litchar["]"] + @litchar{"} @litchar{,} @litchar{'} @litchar{`} + @litchar{;} @litchar{\} +} + +In addition, @litchar{#} is a special character when it appears at the +beginning of the symbol, and when it is not followed by @litchar{%}. + +Symbols @scheme[display] without escaping or quoting special +characters. That is, the display form of a symbol is the same as the +display form of @scheme[symbol->string] applied to the symbol. + +@section{Printing Numbers} + +A number prints the same way in @scheme[write] and @scheme[display] +modes. + +A @tech{complex number} that is not a @tech{real number} always prints +as @nonterm{m}@litchar{+}@nonterm{n}@litchar{i}, where @nonterm{m} and +@nonterm{n} are the printed forms of its real and imaginary parts, +respectively. + +An inexact real number prints with either a @litchar{.} decimal +point, an @litchar{e} exponent marker, or both. The form is selected +so that the output is as short as possible, with the constraint that +reading the printed form back in produces an @scheme{equal?} number. + +An exact @scheme[0] prints as @litchar{0}. + +A positive, exact integer prints as a sequence of decimal digits that +does not start with @scheme[0]. + +A positive, exact, real, non-integer number prints as +@nonterm{m}@litchar{/}@nonterm{n}, where @nonterm{m} and @nonterm{n} +are the printed forms of the number's numerators and denominator (as +determined by @scheme[numerator] and @scheme[denominator]). + +A negative @tech{exact number} prints with a @litchar{-} prefix on the +printed form of its exact negation. + +@section{Printing Booleans} + +The constant @scheme[#t] prints as @litchar{#t}, and the constant +@scheme[#f] prints as @litchar{#f} in both @scheme[display] and +@scheme[write] modes. + +@section{Printing Pairs and Lists} + +A pair prints starting with @litchar{(} followed by the printed form +of its @scheme[car]. The rest of the printed form depends on the +@scheme[cdr]: + +@itemize{ + + @item{If the @scheme[cdr] is a pair or the empty list, then the + printed form of the pair completes with the printed form of the + @scheme[cdr], except that the leading @litchar{(} in the + @scheme[cdr]'s printed form is omitted.} + + @item{Otherwise, the printed for of the pair continues with a space, + @litchar{.}, another space, the printed form of the + @scheme[cdr], and a @litchar{)}.} + +} + +The printed form of a pair is the same in both @scheme[write] and +@scheme[display] modes, except as the printed form of the pair's +@scheme[car]and @scheme[cdr] vary with the mode. + +@section{Printing Strings} + +All strings @scheme[display] as their literal character sequences. + +The @scheme[write] form of a string starts with @litchar{"} and ends +with another @litchar{"}. Between the @litchar{"}s, each character is +represented. Each graphic or blank character is represented as itself, +with two exceptions: @litchar{"} is printed as @litchar{\"}, and +@litchar{\} is printed as @litchar{\\}. Each non-graphic, non-blank +character (according to @scheme[char-graphic?] and +@scheme[char-blank?]) is printed using the escape sequences described +in @secref["mz:parse-string"], using @litchar{\a}, @litchar{\b}, +@litchar{\t}, @litchar{\n}, @litchar{\v}, @litchar{\f}, @litchar{\r}, +or @litchar{\e} if possible, otherwise using @litchar{\u} with four +hexadecimal digits or @litchar{\U} with eight hexadecimal digits +(using the latter only if the character value does not fit into four +digits). + +All byte strings @scheme[display] as their literal byte sequence; this +byte sequence may not be a valid UTF-8 encoding, so it may not +correspond to a sequence of characters. + +The @scheme[write] form a byte string starts with @litchar{#"} and +ends with another @litchar{"}. Between the @litchar{"}s, each byte is +written using the corresponding ASCII decoding if the byte is between +0 and 127 and the character is graphic or blank (according to +@scheme[char-graphic?] and @scheme[char-blank?]). Otherwise, the byte +is written using @litchar{\a}, @litchar{\b}, @litchar{\t}, +@litchar{\n}, @litchar{\v}, @litchar{\f}, @litchar{\r}, or +@litchar{\e} if possible, otherwise using @litchar{\} followed by one +to three octal digits (only as many as necessary). + +@section{Printing Vectors} + +In @scheme[display] mode, the printed form of a vector is @litchar{#} +followed by the printed form of @scheme[vector->list] applied to the +vector. In @scheme[write] mode, the printed form is the same, except +that a decimal integer is printed after the @litchar{#} when the +@scheme[print-vector-length] parameter is @scheme[#t]. + +@section{Printing Hash Tables} + +When the @scheme[print-hash-table] parameter is set to @scheme[#t], a +hash table prints starting with @litchar{#hash(} or @litchar{#hasheq(} +for a table using @scheme[equal?] or @scheme[eq?] key comparisons, +respectively. After this prefix, each key--value mapping is shown as +@litchar{(}, the printed form of a key, a space, @litchar{.}, a space, +the printed form the corresponding value, and @litchar{)}, with an +addition space if the key--value pairs is not the last to be printed. +After all key-value pairs, the printed form completes with +@litchar{)}. + +When the @scheme[print-hash-table] parameter is set to @scheme[#f], a +hash table prints (un@scheme[read]ably) as @litchar{#}. + +@section{Printing Boxes} + +When the @scheme[print-box] parameter is set to @scheme[#t], +a box prints as @litchar{#&} followed by the printed form of its content. + +When the @scheme[print-box] parameter is set to @scheme[#f], a box +prints (un@scheme[read]ably) as @litchar{#}. + +@section{Printing Characters} + +Characters with the special names described in +@secref["mz:parse-character"] @scheme[write] using the same name. +(Some characters have multiple names; the @scheme[#\newline] and +@scheme[#\nul] names are used instead of @scheme[#\linefeed] and +@scheme[#\null]). Other graphic characters (according to +@scheme[char-graphic?]) @scheme[write] as @litchar{#\} followed by the +single character, and all others characters are written in +@scheme[#\u] notation with four digits or @scheme[#\U] notation with +eight digits (using the latter only if the character value it does not +fit in four digits). + +All characters @scheme[display] directly as themselves (i.e., a single +character). + +@section{Printing Keywords} + +Keywords @scheme[write] and @scheme[display] the same as symbols, +except (see @secref["mz:print-symbol"]) with a leading @litchar{#:}, +and without special handing for an initial @litchar{#} or when the +printed form would matches a number or a delimited @litchar{.} (since +@litchar{#:} distinguishes the keyword). + +@section{Printing Regular Expressions} + +Regexp values in both @scheme[write] and @scheme[display] mode print +starting with @litchar{#px} (for @scheme[pregexp]-based regexps) or +@litchar{#rx} (for @scheme[regexp]-based regexps) followed by the +@scheme[write] form of the regexp's source string or byte string. + diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl index 9ad6d81610..2a3f8a9dcd 100644 --- a/collects/scribblings/reference/read.scrbl +++ b/collects/scribblings/reference/read.scrbl @@ -195,4 +195,45 @@ a module-path datum following @litchar{#reader}. See A parameter whose value determines a readtable that adjusts the parsing of S-expression input, where @scheme[#f] implies the -default behavior. See @secref["mz:readtables"] for more information.} \ No newline at end of file +default behavior. See @secref["mz:readtables"] for more information.} + +@defproc*[([(port-read-handler [in input-port?]) (case-> + (input-port? . -> . any) + (input-port? any/c . -> . any))] + [(port-read-handler [in input-port?] + [proc (case-> + (input-port? . -> . any) + (input-port? any/c . -> . any))]) + void?])]{ + +Gets or sets the @deftech{port read handler} for @scheme[in]. The +handler called to read from the port when the built-in @scheme[read] +or @scheme[read-syntax] procedure is applied to the port. (The +port read handler is not used for @scheme[read/recursive] or +@scheme[read-syntax/recursive].) + +A port read handler is applied to either one argument or two +arguments: + +@itemize{ + + @item{A single argument is supplied when the port is used + with @scheme[read]; the argument is the port being read. The return + value is the value that was read from the port (or end-of-file).} + + @item{Two arguments are supplied when the port is used with + @scheme[read-syntax]; the first argument is the port being read, and + the second argument is a value indicating the source. The return + value is a syntax object that was read from the port (or end-of-file).} + +} + +The default port read handler reads standard Scheme expressions with +Scheme's built-in parser (see @secref["mz:reader"]). It handles a +special result from a custom input port (see +@secref["mz:custominput"]) by treating it as a single expression, +except that special-comment values (see +@secref["mz:special-comments"]) are treated as whitespace. + +The default port read handler itself can be customized through a +readtable; see @secref["mz:readtables"] for more information.} diff --git a/collects/scribblings/reference/reader.scrbl b/collects/scribblings/reference/reader.scrbl index 2d7301b32e..71ac79aac9 100644 --- a/collects/scribblings/reference/reader.scrbl +++ b/collects/scribblings/reference/reader.scrbl @@ -15,7 +15,7 @@ @define[(graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}}] @define[(graph-ref) @elem{@litchar{#}@graph-tag[]@litchar{#}}] -@title[#:tag "mz:reader"]{The Reader} +@title[#:tag "mz:reader" #:style 'quiet]{The Reader} Scheme's reader is a recursive-descent parser that can be configured through a @seclink["mz:readtables"]{readtable} and various other @@ -41,6 +41,8 @@ Reading is defined in terms of Unicode characters; see @secref["mz:ports"] for information on how a byte stream is converted to a character stream. +@local-table-of-contents[] + @;------------------------------------------------------------------------ @section[#:tag "mz:default-readtable-dispatch"]{Delimiters and Dispatch} @@ -680,12 +682,15 @@ A @graph-defn[] tags the following datum for reference via @graph-ref[], which allows the reader to produce a datum that have graph structure. -For a specific @graph-tag in a single read result, each @graph-ref[] +For a specific @graph-tag[] in a single read result, each @graph-ref[] reference is replaced by the datum read for the corresponding @graph-defn[]; the definition @graph-defn[] also produces just the -datum after it. A @graph-defn[] definition can appear at most -once, and a @graph-defn[] definition must appear before a @graph-ref[] -reference appears. +datum after it. A @graph-defn[] definition can appear at most once, +and a @graph-defn[] definition must appear before a @graph-ref[] +reference appears, otherwise the @exnraise[exn:fail:read]. If the +@scheme[read-accept-graph] parameter is set to @scheme[#f], then +@graph-defn[] or @graph-ref[] triggers a @scheme[exn:fail:read] +exception. Although a comment parsed via @litchar{#;} discards the datum afterward, @graph-defn[] definitions in the discarded datum @@ -699,6 +704,8 @@ neither defines nor uses graph tags for other top-level forms. "#0=(1 . #0#)" ] +@local-table-of-contents[] + @section[#:tag "mz:parse-reader"]{Reading via an External Reader} When the reader encounters @litchar{#reader}, then it loads an @@ -713,7 +720,7 @@ whether the reader is in @scheme[read] or @scheme[read-syntax] mode). The resulting procedure should accept the same arguments as -@scheme[read] or @scheme[read-syntax] in the case thar all optional +@scheme[read] or @scheme[read-syntax] in the case that all optional arguments are provided. The procedure is given the port whose stream contained @litchar{#reader}, and it should produce a datum result. If the result is a syntax object in @scheme[read] mode, then it is @@ -727,9 +734,4 @@ If the @scheme[read-accept-reader] @tech{parameter} is set to @scheme[#f], then if the reader encounters @litchar{#reader}, the @exnraise[exn:fail:read]. -@section[#:tag "mz:readtables"]{Readtables} - -The dispatch table in @secref["mz:default-readtable-dispatch"] -corresponds to the default @idefterm{readtable}. - @section[#:tag "mz:parse-honu"]{Honu Parsing} diff --git a/collects/scribblings/reference/readtables.scrbl b/collects/scribblings/reference/readtables.scrbl new file mode 100644 index 0000000000..df306007aa --- /dev/null +++ b/collects/scribblings/reference/readtables.scrbl @@ -0,0 +1,293 @@ +#reader(lib "docreader.ss" "scribble") +@require[(lib "bnf.ss" "scribble")] +@require["mz.ss"] + +@title[#:tag "mz:readtables"]{Readtables} + +The dispatch table in @secref["mz:default-readtable-dispatch"] +corresponds to the default @deftech{readtable}. By creating a new +readtable and installing it via the @scheme[current-readtable] +parameter, the reader's behavior can be extended. + +A readtable is consulted at specific times by the reader: + +@itemize{ + + @item{when looking for the start of a datum;} + + @item{when determining how to parse a datum that starts with + @litchar{#};} + + @item{when looking for a delimiter to terminate a symbol or number;} + + @item{when looking for an opener (such as @litchar{(}), closer (such + as @litchar{)}), or @litchar{.} after the first character parsed as + a sequence for a pair, list, vector, or hash table; or} + + @item{when looking for an opener after @litchar{#}@nonterm{n} in a + vector of specified length @nonterm{n}.} + +} + +The readtable is ignored at other times. In particular, after parsing +a character that is mapped to the default behavior of @litchar{;}, the +readtable is ignored until the comment's terminating newline is +discovered. Similarly, the readtable does not affect string parsing +until a closing double-quote is found. Meanwhile, if a character is +mapped to the default behavior of @litchar{(}, then it starts sequence +that is closed by any character that is mapped to a close parenthesis +@litchar{)}. An apparent exception is that the default parsing of +@litchar{|} quotes a symbol until a matching character is found, but +the parser is simply using the character that started the quote; it +does not consult the readtable. + +For many contexts, @scheme[#f] identifies the default readtable. In +particular, @scheme[#f] is the initial value for the +@scheme[current-readtable] parameter, which causes the reader to +behave as described in @secref["mz:reader"]. + +@defproc[(make-readtable [readtable readtable?] + [key (or/c character? false/c)] + [mode (or/c (one-of 'terminating-macro + 'non-terminating-macro + 'dispatch-macro) + character?)] + [action (or/c procedure? + readtable?)] + ...+) + readtable?]{ + +Creates a new readtable that is like @scheme[readtable] (which can be +@scheme[#f]), except that the reader's behavior is modified for each +@scheme[key] according to the given @scheme[mode] and +@scheme[action]. The @scheme[...+] for @scheme[make-readtable] applies +to all three of @scheme[key], @scheme[mode], and @scheme[action]; in +other words, the total number of arguments to @scheme[make-readtable] +must be @math{1} modulo @math{3}. + +The possible combinations for @scheme[key], @scheme[mode], and +@scheme[action] are as follows: + +@itemize{ + + @item{@scheme[(code:line _char 'terminating-macro _proc)] --- causes + @scheme[_char] to be parsed as a delimiter, and an + unquoted/uncommented @scheme[_char] in the input string triggers a + call to the @deftech{reader macro} @scheme[_proc]; the activity of + @scheme[_proc] is described further below. Conceptually, characters + like @litchar{;}, @litchar{(}, and @litchar{)} are mapped to + terminating reader macros in the default readtable.} + + @item{@scheme[(code:line _char 'non-terminating-macro _proc)] --- like + the @scheme['terminating-macro] variant, but @scheme[_char] is not + treated as a delimiter, so it can be used in the middle of an + identifier or number. Conceptually, @litchar{#} is mapped to a + non-terminating macro in the default readtable.} + + @item{@scheme[(code:line _char 'dispatch-macro _proc)] --- like the + @scheme['non-terminating-macro] variant, but for @scheme[_char] only + when it follows a @litchar{#} (or, more precisely, when the character + follows one that has been mapped to the behavior of @litchar{#}hash + in the default readtable).} + + @item{@scheme[(code:line _char _like-char _readtable)] --- causes + @scheme[_char] to be parsed in the same way that @scheme[_like-char] + is parsed in @scheme[_readtable], where @scheme[_readtable] can be + @scheme[#f] to indicate the default readtable. Mapping a character to + the same actions as @litchar{|} in the default reader means that the + character starts quoting for symbols, and the same character + terminates the quote; in contrast, mapping a character to the same + action as a @litchar{"} means that the character starts a string, but + the string is still terminated with a closing @litchar{"}. Finally, + mapping a character to an action in the default readtable means that + the character's behavior is sensitive to parameters that affect the + original character; for example, mapping a character to the same + action is a curly brace @litchar["{"] in the default readtable means + that the character is disallowed when the + @scheme[read-curly-brace-as-paren] parameter is set to @scheme[#f].} + + @item{@scheme[(code:line #f 'non-terminating-macro _proc)] --- + replaces the macro used to parse characters with no specific mapping: + i.e., characters (other than @litchar{#} or @litchar{|}) that can + start a symbol or number with the default readtable.} + +} + +If multiple @scheme['dispatch-macro] mappings are provided for a +single @scheme[_char], all but the last one are ignored. Similarly, if +multiple non-@scheme['dispatch-macro] mappings are provided for a +single @scheme[_char], all but the last one are ignored. + +A reader macro @scheme[_proc] must accept six arguments, and it can +optionally accept two arguments. See @secref["mz:reader-procs"] for +information on the procedure's arguments and results. + +A reader macro normally reads characters from the given input port to +produce a value to be used as the ``reader macro-expansion'' of the +consumed characters. The reader macro might produce a special-comment +value (see @secref["mz:special-comments"]) to cause the consumed +character to be treated as whitespace, and it might use +@scheme[read/recursive] or @scheme[read-syntax/recursive].} + +@defproc[(readtable-mapping [readtable readtable?][char character?]) + (values (or/c character? + (one-of 'terminating-macro + 'non-terminating-macro)) + (or/c false/c procedure?) + (or/c false/c procedure?))]{ + +Produces information about the mappings in @scheme[readtable] for +@scheme[char]. The result is three values: + +@itemize{ + + @item{either a character (mapping is to same behavior as the + character in the default readtable), @scheme['terminating-macro], or + @scheme['non-terminating-macro]; this result reports the main (i.e., + non-@scheme['dispatch-macro]) mapping for @scheme[key]. When the result + is a character, then @scheme[key] is mapped to the same behavior as the + returned character in the default readtable.} + + @item{either @scheme[#f] or a reader-macro procedure; the result is a + procedure when the first result is @scheme['terminating-macro] or + @scheme['non-terminating-macro].} + + @item{either @scheme[#f] or a reader-macro procedure; the result is a + procedure when the character has a @scheme['dispatch-macro] mapping in + @scheme[readtable] to override the default dispatch behavior.} + +} + +Note that reader-macro procedures for the default readtable are not +directly accessible. To invoke default behaviors, use +@scheme[read/recursive] or @scheme[read-syntax/recursive] with a +character and the @scheme[#f] readtable.} + +@begin[ +#reader(lib "comment-reader.ss" "scribble") +[examples +;; Provides @scheme[raise-read-error] and @scheme[raise-read-eof-error] +(require (lib "readerr.ss" "syntax")) + +(define (skip-whitespace port) + ;; Skips whitespace characters, sensitive to the current + ;; readtable's definition of whitespace + (let ([ch (peek-char port)]) + (unless (eof-object? ch) + ;; Consult current readtable: + (let-values ([(like-ch/sym proc dispatch-proc) + (readtable-mapping (current-readtable) ch)]) + ;; If like-ch/sym is whitespace, then ch is whitespace + (when (and (char? like-ch/sym) + (char-whitespace? like-ch/sym)) + (read-char port) + (skip-whitespace port)))))) + +(define (skip-comments read-one port src) + ;; Recursive read, but skip comments and detect EOF + (let loop () + (let ([v (read-one)]) + (cond + [(special-comment? v) (loop)] + [(eof-object? v) + (let-values ([(l c p) (port-next-location port)]) + (raise-read-eof-error + "unexpected EOF in tuple" src l c p 1))] + [else v])))) + +(define (parse port read-one src) + ;; First, check for empty tuple + (skip-whitespace port) + (if (eq? #\> (peek-char port)) + null + (let ([elem (read-one)]) + (if (special-comment? elem) + ;; Found a comment, so look for > again + (parse port read-one src) + ;; Non-empty tuple: + (cons elem + (parse-nonempty port read-one src)))))) + +(define (parse-nonempty port read-one src) + ;; Need a comma or closer + (skip-whitespace port) + (case (peek-char port) + [(#\>) (read-char port) + ;; Done + null] + [(#\,) (read-char port) + ;; Read next element and recur + (cons (skip-comments read-one port src) + (parse-nonempty port read-one src))] + [else + ;; Either a comment or an error; grab location (in case + ;; of error) and read recursively to detect comments + (let-values ([(l c p) (port-next-location port)] + [(v) (read-one)]) + (cond + [(special-comment? v) + ;; It was a comment, so try again + (parse-nonempty port read-one src)] + [else + ;; Wasn't a comment, comma, or closer; error + ((if (eof-object? v) + raise-read-eof-error + raise-read-error) + "expected `,' or `>'" src l c p 1)]))])) + +(define (make-delims-table) + ;; Table to use for recursive reads to disallow delimiters + ;; (except those in sub-expressions) + (letrec ([misplaced-delimiter + (case-lambda + [(ch port) (unexpected-delimiter ch port #f #f #f #f)] + [(ch port src line col pos) + (raise-read-error + (format "misplaced `~a' in tuple" ch) + src line col pos 1)])]) + (make-readtable (current-readtable) + #\, 'terminating-macro misplaced-delimiter + #\> 'terminating-macro misplaced-delimiter))) + +(define (wrap l) + `(make-tuple (list ,@l))) + +(define parse-open-tuple + (case-lambda + [(ch port) + ;; `read' mode + (wrap (parse port + (lambda () + (read/recursive port #f + (make-delims-table))) + (object-name port)))] + [(ch port src line col pos) + ;; `read-syntax' mode + (datum->syntax-object + #f + (wrap (parse port + (lambda () + (read-syntax/recursive src port #f + (make-delims-table))) + src)) + (let-values ([(l c p) (port-next-location port)]) + (list src line col pos (and pos (- p pos)))))])) + + +(define tuple-readtable + (make-readtable #f #\< 'terminating-macro parse-open-tuple)) + +(parameterize ([current-readtable tuple-readtable]) + (read (open-input-string "<1 , 2 , \"a\">"))) + +(parameterize ([current-readtable tuple-readtable]) + (read (open-input-string + "< #||# 1 #||# , #||# 2 #||# , #||# \"a\" #||# >"))) + +(define tuple-readtable+ + (make-readtable tuple-readtable + #\* 'terminating-macro (lambda a (make-special-comment #f)) + #\_ #\space #f)) +(parameterize ([current-readtable tuple-readtable+]) + (read (open-input-string "< * 1 __,__ 2 __,__ * \"a\" * >"))) +]] \ No newline at end of file diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index 4a435df11e..67a0770409 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/collects/scribblings/reference/reference.scrbl @@ -23,16 +23,7 @@ language. @include-section["concurrency.scrbl"] @include-section["security.scrbl"] @include-section["io.scrbl"] - -@;------------------------------------------------------------------------ - -@section{Operating System} - -@subsection{Platform-Specific Path Conventions} - -@subsubsection[#:tag "mz:unix-path"]{Unix and Mac OS X Paths} - -@subsubsection[#:tag "mz:windows-path"]{Windows Paths} +@include-section["os.scrbl"] @;------------------------------------------------------------------------ diff --git a/collects/scribblings/reference/string-input.scrbl b/collects/scribblings/reference/string-input.scrbl index f748a2a0c8..cb5834a7d0 100644 --- a/collects/scribblings/reference/string-input.scrbl +++ b/collects/scribblings/reference/string-input.scrbl @@ -375,3 +375,18 @@ is committed as read. If @scheme[progress] is not a result of @scheme[port-progress-evt] applied to @scheme[in], then @exnraise[exn:fail:contract].} + +@defproc[(byte-ready? [in input-port? (current-input-port)]) + boolean?]{ + +Returns @scheme[#t] if @scheme[(read-byte in)] would not block (at the +time that @scheme[byte-ready?] was called, at least). Equivalent to +@scheme[(and (sync/timeout 0 in) #t)].} + +@defproc[(char-ready? [in input-port? (current-input-port)]) + boolean?]{ + +Returns @scheme[#t] if @scheme[(read-char in)] would not block (at the +time that @scheme[char-ready?] was called, at least). Depending on the +initial bytes of the stream, multiple bytes may be needed to form a +UTF-8 encoding.} diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index ca6a11b94c..8f5275b6a4 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -3,7 +3,7 @@ @define[cvt (schemefont "CVT")] -@title[#:tag "mz:syntax" #:style 'toc]{Syntactic Forms} +@title[#:tag "mz:syntax" #:style 'toc]{Core Syntactic Forms} This section describes the core syntax forms that apear in a fully expanded expression, plus a many closely-related non-core forms. diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl index 5fe3294add..d8a0b9ba1a 100644 --- a/collects/scribblings/reference/write.scrbl +++ b/collects/scribblings/reference/write.scrbl @@ -16,7 +16,9 @@ handler is called. Otherwise, the default printer is used (in @scheme[write] mode), as configured by various parameters. See @secref["mz:printer"] for more information about the default -printer.} +printer. In particular, note that @scheme[write] may require memory +proportional to the depth of the value being printed, due to the +initial cycle check.} @defproc[(display [datum any/c][out output-port? (current-output-port)]) void?]{ @@ -29,7 +31,9 @@ is called. Otherwise, the default printer is used (in @scheme[display] mode), as configured by various parameters. See @secref["mz:printer"] for more information about the default -printer.} +printer. In particular, note that @scheme[display] may require memory +proportional to the depth of the value being printed, due to the +initial cycle check.} @defproc[(print [datum any/c][out output-port? (current-output-port)]) void?]{ @@ -127,3 +131,81 @@ Formats to a string. The result is the same as @examples[ (format "~a as a string is ~s.~n" '(3 4) "(3 4)") ]} + +@defboolparam[print-unreadable on?]{ + +A parameter that controls printing values that have no +@scheme[read]able form (using the default reader), including +structures that have a custom-write procedure (see +@secref["mz:custom-write"]); defaults to @scheme[#t]. See +@secref["mz:printing"] for more information.} + +@defboolparam[print-graph on?]{ + +A parameter that controls printing data with sharing; defaults to +@scheme[#f]. See @secref["mz:sexpressions"] for more information.} + +@defboolparam[print-struct on?]{ + +A parameter that controls printing structure values in vector form; +defaults to @scheme[#t]. See @secref["mz:printing"] for more +information. This parameter has no effect on the printing of +structures that have a custom-write procedure (see +@secref["mz:custom-write"]).} + +@defboolparam[print-box on?]{ + +A parameter that controls printing box values; defaults to +@scheme[#t]. See @secref["mz:printing"] for more information.} + +@defboolparam[print-vector-length on?]{ + +A parameter that controls printing vectors; defaults to +@scheme[#t]. See @secref["mz:printing"] for more information.} + +@defboolparam[print-hash-table on?]{ + +A parameter that controls printing hash tables; defaults to +@scheme[#f]. See @secref["mz:printing"] for more information.} + +@defboolparam[print-honu on?]{ + +A parameter that controls printing values in an alternate syntax. See +@secref["mz:honu"] for more information.} + + +@defproc*[([(port-write-handler [out output-port?]) (any/c output-port? . -> . any)] + [(port-write-handler [in input-port?] + [proc (any/c output-port? . -> . any)]) + void?])]{} + +@defproc*[([(port-display-handler [out output-port?]) (any/c output-port? . -> . any)] + [(port-display-handler [in input-port?] + [proc (any/c output-port? . -> . any)]) + void?])]{} + +@defproc*[([(port-print-handler [out output-port?]) (any/c output-port? . -> . any)] + [(port-print-handler [in input-port?] + [proc (any/c output-port? . -> . any)]) + void?])]{ + +Gets or sets the @deftech{port write handler}, @deftech{port display +handler}, or @deftech{port print handler} for @scheme[out]. This +handler is call to output to the port when @scheme[write], +@scheme[display], or @scheme[print] (respectively) is applied to the +port. Each handler takes a two arguments: the value to be printed and +the destination port. The handler's return value is ignored. + +The default port display and write handlers print Scheme expressions +with Scheme's built-in printer (see @secref["mz:printing"]). The +default print handler calls the global port print handler (the value +of the @scheme[global-port-print-handler] parameter); the default +global port print handler is the same as the default write handler.} + +@defparam[global-port-print-handler proc (any/c output-port? . -> . any)]{ + +A parameter that determines @idefterm{global port print handler}, +which is called by the default port print handler (see +@scheme[port-print-handler]) to @scheme[print] values into a port. +The default value uses the built-in printer (see +@secref["mz:printing"]) in @scheme[write] mode.}