more i/o reference work
svn: r6807
This commit is contained in:
Matthew Flatt
parent
0a92af34d1
commit
4bf593ddc4
|
|
@ -285,9 +285,13 @@
|
||||||
(define/private (render-toc part base-len skip?)
|
(define/private (render-toc part base-len skip?)
|
||||||
(let ([number (collected-info-number (part-collected-info part))])
|
(let ([number (collected-info-number (part-collected-info part))])
|
||||||
(let ([subs
|
(let ([subs
|
||||||
|
(if (not (and (styled-part? part)
|
||||||
|
(eq? 'quiet (styled-part-style part))
|
||||||
|
(not (= base-len (sub1 (length number))))))
|
||||||
(apply
|
(apply
|
||||||
append
|
append
|
||||||
(map (lambda (p) (render-toc p base-len #f)) (part-parts part)))])
|
(map (lambda (p) (render-toc p base-len #f)) (part-parts part)))
|
||||||
|
null)])
|
||||||
(if skip?
|
(if skip?
|
||||||
subs
|
subs
|
||||||
(let ([l (cons
|
(let ([l (cons
|
||||||
|
|
|
||||||
|
|
@ -331,6 +331,7 @@
|
||||||
|
|
||||||
(define (get-lines* re:begin re:end re:item end-token)
|
(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
|
;; 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 loop ([lvl 0] [r '()])
|
||||||
(let-values ([(line col pos) (port-next-location inp)])
|
(let-values ([(line col pos) (port-next-location inp)])
|
||||||
(define (make-stx sexpr)
|
(define (make-stx sexpr)
|
||||||
|
|
@ -395,9 +396,12 @@
|
||||||
r)))]
|
r)))]
|
||||||
[(*peek #rx#"^$")
|
[(*peek #rx#"^$")
|
||||||
(if end-token
|
(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))]
|
(done-lines r))]
|
||||||
[else (read-error "internal error [get-lines*]")]))))
|
[else (read-error "internal error [get-lines*]")])))))
|
||||||
|
|
||||||
(define (get-lines)
|
(define (get-lines)
|
||||||
(cond [(*skip re:lines-begin)
|
(cond [(*skip re:lines-begin)
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,4 @@
|
||||||
#reader(lib "docreader.ss" "scribble")
|
#reader(lib "docreader.ss" "scribble")
|
||||||
@require[(lib "bnf.ss" "scribble")]
|
|
||||||
@require["mz.ss"]
|
@require["mz.ss"]
|
||||||
|
|
||||||
@title[#:tag "mz:input-and-output" #:style 'toc]{Input and Output}
|
@title[#:tag "mz:input-and-output" #:style 'toc]{Input and Output}
|
||||||
|
|
@ -12,3 +11,5 @@
|
||||||
@include-section["read.scrbl"]
|
@include-section["read.scrbl"]
|
||||||
@include-section["write.scrbl"]
|
@include-section["write.scrbl"]
|
||||||
@include-section["reader.scrbl"]
|
@include-section["reader.scrbl"]
|
||||||
|
@include-section["printer.scrbl"]
|
||||||
|
@include-section["readtables.scrbl"]
|
||||||
|
|
|
||||||
|
|
@ -5,20 +5,20 @@
|
||||||
|
|
||||||
@guideintro["guide:numbers"]{numbers}
|
@guideintro["guide:numbers"]{numbers}
|
||||||
|
|
||||||
All numbers are @idefterm{complex numbers}. Some of them are
|
All numbers are @deftech{complex numbers}. Some of them are
|
||||||
@idefterm{real numbers}, and all of the real numbers that can be
|
@deftech{real numbers}, and all of the real numbers that can be
|
||||||
represented are also @idefterm{rational numbers}. Among the real
|
represented are also @deftech{rational numbers}. Among the real
|
||||||
numbers, some are @idefterm{integers}, because @scheme[round] applied
|
numbers, some are @deftech{integers}, because @scheme[round] applied
|
||||||
to the number produces the same number.
|
to the number produces the same number.
|
||||||
|
|
||||||
Orthogonal to those categories, each number is also either
|
Orthogonal to those categories, each number is also either an
|
||||||
@idefterm{exact} or @idefterm{inexact}. Unless otherwise specified,
|
@deftech{exact number} or an @deftech{inexact number}. Unless
|
||||||
computations that involve an inexact number produce inexact
|
otherwise specified, computations that involve an inexact number
|
||||||
results. Certain operations on inexact numbers, however, produce an
|
produce inexact results. Certain operations on inexact numbers,
|
||||||
exact number, such as multiplying an inexact number with an exact
|
however, produce an exact number, such as multiplying an inexact
|
||||||
@scheme[0]. Some operations, which can produce an irrational number
|
number with an exact @scheme[0]. Some operations, which can produce an
|
||||||
for rational arguments (e.g., @scheme[sqrt]), may produce inexact
|
irrational number for rational arguments (e.g., @scheme[sqrt]), may
|
||||||
results even for exact arguments.
|
produce inexact results even for exact arguments.
|
||||||
|
|
||||||
In the case of complex numbers, either the real and imaginary parts
|
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
|
are both exact or inexact, or the number has an exact zero real part
|
||||||
|
|
|
||||||
8
collects/scribblings/reference/os.scrbl
Normal file
8
collects/scribblings/reference/os.scrbl
Normal file
|
|
@ -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"]
|
||||||
366
collects/scribblings/reference/platform-paths.scrbl
Normal file
366
collects/scribblings/reference/platform-paths.scrbl
Normal file
|
|
@ -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.
|
||||||
|
|
@ -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
|
enabled for @scheme[port], the column and position results can
|
||||||
decrease after reading or writing a byte that ends a UTF-8 encoding
|
decrease after reading or writing a byte that ends a UTF-8 encoding
|
||||||
sequence.}
|
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].}
|
||||||
|
|
||||||
|
|
|
||||||
218
collects/scribblings/reference/printer.scrbl
Normal file
218
collects/scribblings/reference/printer.scrbl
Normal file
|
|
@ -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{#<hash-table>}.
|
||||||
|
|
||||||
|
@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{#<box>}.
|
||||||
|
|
||||||
|
@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.
|
||||||
|
|
||||||
|
|
@ -196,3 +196,44 @@ a module-path datum following @litchar{#reader}. See
|
||||||
A parameter whose value determines a readtable that
|
A parameter whose value determines a readtable that
|
||||||
adjusts the parsing of S-expression input, where @scheme[#f] implies the
|
adjusts the parsing of S-expression input, where @scheme[#f] implies the
|
||||||
default behavior. See @secref["mz:readtables"] for more information.}
|
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.}
|
||||||
|
|
|
||||||
|
|
@ -15,7 +15,7 @@
|
||||||
@define[(graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}}]
|
@define[(graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}}]
|
||||||
@define[(graph-ref) @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
|
Scheme's reader is a recursive-descent parser that can be configured
|
||||||
through a @seclink["mz:readtables"]{readtable} and various other
|
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
|
@secref["mz:ports"] for information on how a byte stream is converted
|
||||||
to a character stream.
|
to a character stream.
|
||||||
|
|
||||||
|
@local-table-of-contents[]
|
||||||
|
|
||||||
@;------------------------------------------------------------------------
|
@;------------------------------------------------------------------------
|
||||||
@section[#:tag "mz:default-readtable-dispatch"]{Delimiters and Dispatch}
|
@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
|
@graph-ref[], which allows the reader to produce a datum that
|
||||||
have graph structure.
|
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
|
reference is replaced by the datum read for the corresponding
|
||||||
@graph-defn[]; the definition @graph-defn[] also produces just the
|
@graph-defn[]; the definition @graph-defn[] also produces just the
|
||||||
datum after it. A @graph-defn[] definition can appear at most
|
datum after it. A @graph-defn[] definition can appear at most once,
|
||||||
once, and a @graph-defn[] definition must appear before a @graph-ref[]
|
and a @graph-defn[] definition must appear before a @graph-ref[]
|
||||||
reference appears.
|
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
|
Although a comment parsed via @litchar{#;} discards the datum
|
||||||
afterward, @graph-defn[] definitions in the discarded 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#)"
|
"#0=(1 . #0#)"
|
||||||
]
|
]
|
||||||
|
|
||||||
|
@local-table-of-contents[]
|
||||||
|
|
||||||
@section[#:tag "mz:parse-reader"]{Reading via an External Reader}
|
@section[#:tag "mz:parse-reader"]{Reading via an External Reader}
|
||||||
|
|
||||||
When the reader encounters @litchar{#reader}, then it loads an
|
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).
|
mode).
|
||||||
|
|
||||||
The resulting procedure should accept the same arguments as
|
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
|
arguments are provided. The procedure is given the port whose stream
|
||||||
contained @litchar{#reader}, and it should produce a datum result. If
|
contained @litchar{#reader}, and it should produce a datum result. If
|
||||||
the result is a syntax object in @scheme[read] mode, then it is
|
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
|
@scheme[#f], then if the reader encounters @litchar{#reader}, the
|
||||||
@exnraise[exn:fail:read].
|
@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}
|
@section[#:tag "mz:parse-honu"]{Honu Parsing}
|
||||||
|
|
|
||||||
293
collects/scribblings/reference/readtables.scrbl
Normal file
293
collects/scribblings/reference/readtables.scrbl
Normal file
|
|
@ -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\" * >")))
|
||||||
|
]]
|
||||||
|
|
@ -23,16 +23,7 @@ language.
|
||||||
@include-section["concurrency.scrbl"]
|
@include-section["concurrency.scrbl"]
|
||||||
@include-section["security.scrbl"]
|
@include-section["security.scrbl"]
|
||||||
@include-section["io.scrbl"]
|
@include-section["io.scrbl"]
|
||||||
|
@include-section["os.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}
|
|
||||||
|
|
||||||
@;------------------------------------------------------------------------
|
@;------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -375,3 +375,18 @@ is committed as read.
|
||||||
|
|
||||||
If @scheme[progress] is not a result of @scheme[port-progress-evt]
|
If @scheme[progress] is not a result of @scheme[port-progress-evt]
|
||||||
applied to @scheme[in], then @exnraise[exn:fail:contract].}
|
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.}
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,7 @@
|
||||||
|
|
||||||
@define[cvt (schemefont "CVT")]
|
@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
|
This section describes the core syntax forms that apear in a fully
|
||||||
expanded expression, plus a many closely-related non-core forms.
|
expanded expression, plus a many closely-related non-core forms.
|
||||||
|
|
|
||||||
|
|
@ -16,7 +16,9 @@ handler is called. Otherwise, the default printer is used (in
|
||||||
@scheme[write] mode), as configured by various parameters.
|
@scheme[write] mode), as configured by various parameters.
|
||||||
|
|
||||||
See @secref["mz:printer"] for more information about the default
|
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)])
|
@defproc[(display [datum any/c][out output-port? (current-output-port)])
|
||||||
void?]{
|
void?]{
|
||||||
|
|
@ -29,7 +31,9 @@ is called. Otherwise, the default printer is used (in @scheme[display]
|
||||||
mode), as configured by various parameters.
|
mode), as configured by various parameters.
|
||||||
|
|
||||||
See @secref["mz:printer"] for more information about the default
|
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)])
|
@defproc[(print [datum any/c][out output-port? (current-output-port)])
|
||||||
void?]{
|
void?]{
|
||||||
|
|
@ -127,3 +131,81 @@ Formats to a string. The result is the same as
|
||||||
@examples[
|
@examples[
|
||||||
(format "~a as a string is ~s.~n" '(3 4) "(3 4)")
|
(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.}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user