329 lines
14 KiB
Racket
329 lines
14 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/bnf "mz.rkt")
|
|
|
|
@(define (FmtMark . s) (apply litchar "~" s))
|
|
|
|
@title{Writing}
|
|
|
|
@defproc[(write [datum any/c] [out output-port? (current-output-port)])
|
|
void?]{
|
|
|
|
Writes @racket[datum] to @racket[out], normally in such a way that
|
|
instances of core datatypes can be read back in. If @racket[out] has a
|
|
handler associated to it via @racket[port-write-handler], then the
|
|
handler is called. Otherwise, the default printer is used (in
|
|
@racket[write] mode), as configured by various parameters.
|
|
|
|
See @secref["printing"] for more information about the default
|
|
printer. In particular, note that @racket[write] may require memory
|
|
proportional to the depth of the value being printed, due to the
|
|
initial cycle check.
|
|
|
|
@examples[
|
|
(write 'hi)
|
|
(write (lambda (n) n))
|
|
(define o (open-output-string))
|
|
(write "hello" o)
|
|
(get-output-string o)
|
|
]}
|
|
|
|
@defproc[(display [datum any/c] [out output-port? (current-output-port)])
|
|
void?]{
|
|
|
|
Displays @racket[datum] to @racket[out], similar to @racket[write],
|
|
but usually in such a way that byte- and character-based datatypes are
|
|
written as raw bytes or characters. If @racket[out] has a handler
|
|
associated to it via @racket[port-display-handler], then the handler
|
|
is called. Otherwise, the default printer is used (in @racket[display]
|
|
mode), as configured by various parameters.
|
|
|
|
See @secref["printing"] for more information about the default
|
|
printer. In particular, note that @racket[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)]
|
|
[quote-depth (or/c 0 1) 0])
|
|
void?]{
|
|
|
|
Writes @racket[datum] to @racket[out], normally the same way as
|
|
@racket[write]. If @racket[out] has a handler associated to it via
|
|
@racket[port-print-handler], then the handler is called. Otherwise,
|
|
the handler specified by @racket[global-port-print-handler] is called;
|
|
the default handler uses the default printer in @racket[write] mode.
|
|
|
|
The optional @racket[quote-depth] argument adjusts printing when the
|
|
@racket[print-as-expression] parameter is set to @racket[#t]. In that
|
|
case, @racket[quote-depth] specifies the starting quote depth for
|
|
printing @racket[datum].
|
|
|
|
The rationale for providing @racket[print] is that @racket[display]
|
|
and @racket[write] both have specific output conventions, and those
|
|
conventions restrict the ways that an environment can change the
|
|
behavior of @racket[display] and @racket[write] procedures. No output
|
|
conventions should be assumed for @racket[print], so that environments
|
|
are free to modify the actual output generated by @racket[print] in
|
|
any way.}
|
|
|
|
|
|
@defproc[(displayln [datum any/c] [out output-port? (current-output-port)])
|
|
void?]{
|
|
|
|
The same as @racket[(display datum out)] followed by @racket[(newline out)],
|
|
which is similar to @as-index{@tt{println}} in Pascal or Java.}
|
|
|
|
@defproc[(fprintf [out output-port?] [form string?] [v any/c] ...) void?]{
|
|
|
|
Prints formatted output to @racket[out], where @racket[form] is a string
|
|
that is printed directly, except for special formatting
|
|
escapes:
|
|
|
|
@itemize[
|
|
|
|
@item{@FmtMark{n} or @FmtMark{%} prints a newline character (which
|
|
is equivalent to @litchar{\n} in a literal format string)}
|
|
|
|
@item{@FmtMark{a} or @FmtMark{A} @racket[display]s the next argument
|
|
among the @racket[v]s}
|
|
|
|
@item{@FmtMark{s} or @FmtMark{S} @racket[write]s the next argument
|
|
among the @racket[v]s}
|
|
|
|
@item{@FmtMark{v} or @FmtMark{V} @racket[print]s the next argument
|
|
among the @racket[v]s}
|
|
|
|
@item{@FmtMark{.}@nonterm{c} where @nonterm{c} is @litchar{a},
|
|
@litchar{A}, @litchar{s}, @litchar{S}, @litchar{v}, or @litchar{V}:
|
|
truncates @racket[display], @racket[write], or @racket[print] output
|
|
to @racket[(error-print-width)] characters, using @litchar{...} as
|
|
the last three characters if the untruncated output would be longer}
|
|
|
|
@item{@FmtMark{e} or @FmtMark{E} outputs the next argument among the
|
|
@racket[v]s using the current error value conversion handler (see
|
|
@racket[error-value->string-handler]) and current error printing
|
|
width}
|
|
|
|
@item{@FmtMark{c} or @FmtMark{C} @racket[write-char]s the
|
|
next argument in @racket[v]s; if the next argument is not a
|
|
character, the @exnraise[exn:fail:contract]}
|
|
|
|
@item{@FmtMark{b} or @FmtMark{B} prints the next argument among the
|
|
@racket[v]s in binary; if the next argument is not an exact number, the
|
|
@exnraise[exn:fail:contract]}
|
|
|
|
@item{@FmtMark{o} or @FmtMark{O} prints the next argument among the
|
|
@racket[v]s in octal; if the next argument is not an exact number, the
|
|
@exnraise[exn:fail:contract]}
|
|
|
|
@item{@FmtMark{x} or @FmtMark{X} prints the next argument among the
|
|
@racket[v]s in hexadecimal; if the next argument is not an exact
|
|
number, the @exnraise[exn:fail:contract]}
|
|
|
|
@item{@FmtMark{~} prints a tilde.}
|
|
|
|
@item{@FmtMark{}@nonterm{w}, where @nonterm{w} is a whitespace
|
|
character (see @racket[char-whitespace?]), skips characters in
|
|
@racket[form] until a non-whitespace character is encountered or
|
|
until a second end-of-line is encountered (whichever happens
|
|
first). On all platforms, an end-of-line can be @racket[#\return],
|
|
@racket[#\newline], or @racket[#\return] followed immediately by
|
|
@racket[#\newline].}
|
|
|
|
]
|
|
|
|
The @racket[form] string must not contain any @litchar{~} that is
|
|
not one of the above escapes, otherwise the
|
|
@exnraise[exn:fail:contract]. When the format string requires more
|
|
@racket[v]s than are supplied, the
|
|
@exnraise[exn:fail:contract]. Similarly, when more @racket[v]s are
|
|
supplied than are used by the format string, the
|
|
@exnraise[exn:fail:contract].
|
|
|
|
@examples[
|
|
(fprintf (current-output-port)
|
|
"~a as a string is ~s.\n"
|
|
'(3 4)
|
|
"(3 4)")
|
|
]}
|
|
|
|
@defproc[(printf [form string?] [v any/c] ...) void?]{
|
|
The same as @racket[(fprintf (current-output-port) form v ...)].}
|
|
|
|
@defproc[(eprintf [form string?] [v any/c] ...) void?]{
|
|
The same as @racket[(fprintf (current-error-port) form v ...)].}
|
|
|
|
@defproc[(format [form string?] [v any/c] ...) string?]{
|
|
Formats to a string. The result is the same as
|
|
|
|
@racketblock[
|
|
(let ([o (open-output-string)])
|
|
(fprintf o form v ...)
|
|
(get-output-string o))
|
|
]
|
|
|
|
@examples[
|
|
(format "~a as a string is ~s.\n" '(3 4) "(3 4)")
|
|
]}
|
|
|
|
@defboolparam[print-pair-curly-braces on?]{
|
|
|
|
A @tech{parameter} that controls pair printing. If the value is true, then
|
|
pairs print using @litchar["{"] and @litchar["}"] instead of
|
|
@litchar{(} and @litchar{)}. The default is @racket[#f].}
|
|
|
|
|
|
@defboolparam[print-mpair-curly-braces on?]{
|
|
|
|
A @tech{parameter} that controls pair printing. If the value is true, then
|
|
mutable pairs print using @litchar["{"] and @litchar["}"] instead of
|
|
@litchar{(} and @litchar{)}. The default is @racket[#t].}
|
|
|
|
@defboolparam[print-unreadable on?]{
|
|
|
|
A @tech{parameter} that enables or disables printing of values that have no
|
|
@racket[read]able form (using the default reader), including
|
|
structures that have a custom-write procedure (see
|
|
@racket[prop:custom-write]), but not including @tech{uninterned}
|
|
symbols and @tech{unreadable symbols} (which print the same as
|
|
@tech{interned} symbols). If the parameter value is @racket[#f], an
|
|
attempt to print an unreadable value raises @racket[exn:fail]. The
|
|
parameter value defaults to @racket[#t]. See @secref["printing"] for
|
|
more information.}
|
|
|
|
@defboolparam[print-graph on?]{
|
|
|
|
A @tech{parameter} that controls printing data with sharing; defaults to
|
|
@racket[#f]. See @secref["printing"] for more information.}
|
|
|
|
@defboolparam[print-struct on?]{
|
|
|
|
A @tech{parameter} that controls printing structure values in vector or
|
|
@tech{prefab} form; defaults to @racket[#t]. See @secref["printing"]
|
|
for more information. This parameter has no effect on the printing of
|
|
structures that have a custom-write procedure (see
|
|
@racket[prop:custom-write]).}
|
|
|
|
@defboolparam[print-box on?]{
|
|
|
|
A @tech{parameter} that controls printing box values; defaults to
|
|
@racket[#t]. See @secref["print-box"] for more information.}
|
|
|
|
@defboolparam[print-vector-length on?]{
|
|
|
|
A @tech{parameter} that controls printing vectors; defaults to
|
|
@racket[#f]. See @secref["print-vectors"] for more information.}
|
|
|
|
@defboolparam[print-hash-table on?]{
|
|
|
|
A @tech{parameter} that controls printing hash tables; defaults to
|
|
@racket[#f]. See @secref["print-hashtable"] for more information.}
|
|
|
|
|
|
@defboolparam[print-boolean-long-form on?]{
|
|
|
|
A @tech{parameter} that controls printing of booleans. When the parameter's
|
|
value is true, @racket[#t] and @racket[#f] print as @litchar{#true}
|
|
and @litchar{#false}, otherwise they print as @litchar{#t}
|
|
and @litchar{#f}. The default is @racket[#f].}
|
|
|
|
|
|
@defboolparam[print-reader-abbreviations on?]{
|
|
|
|
A @tech{parameter} that controls printing of two-element lists that start
|
|
with @racket[quote], @racket['quasiquote], @racket['unquote],
|
|
@racket['unquote-splicing], @racket['syntax], @racket['quasisyntax],
|
|
@racket['unsyntax], or @racket['unsyntax-splicing]; defaults to
|
|
@racket[#f]. See @secref["print-pairs"] for more information.}
|
|
|
|
@defboolparam[print-as-expression on?]{
|
|
|
|
A @tech{parameter} that controls printing in @racket[print] mode (as opposed
|
|
to @racket[write] or @racket[display]); defaults to @racket[#t]. See
|
|
@secref["printing"] for more information.}
|
|
|
|
|
|
@defparam[print-syntax-width width (or/c +inf.0 0 (and/c exact-integer? (>/c 3)))]{
|
|
|
|
A @tech{parameter} that controls printing of @tech{syntax objects}. Up to
|
|
@racket[width] characters are used to show the datum form of a syntax
|
|
object within @litchar{#<syntax}...@litchar{>} (after the
|
|
@tech{syntax object}'s source location, if any).}
|
|
|
|
|
|
@defparam*[current-write-relative-directory path
|
|
(or/c (and/c path-string? complete-path?)
|
|
(cons/c (and/c path-string? complete-path?)
|
|
(and/c path-string? complete-path?))
|
|
#f)
|
|
(or/c (and/c path? complete-path?)
|
|
(cons/c (and/c path? complete-path?)
|
|
(and/c path? complete-path?))
|
|
#f)]{
|
|
|
|
A @tech{parameter} that is used when writing compiled code (see @secref["print-compiled"]) that contains
|
|
pathname literals, including source-location pathnames for procedure
|
|
names. When the parameter's value is a @racket[_path], paths that syntactically extend @racket[_path]
|
|
are converted to relative paths; when the resulting
|
|
compiled code is read, relative paths are converted back to complete
|
|
paths using the @racket[current-load-relative-directory] parameter (if
|
|
it is not @racket[#f]; otherwise, the path is left relative).
|
|
When the parameter's value is @racket[(cons _rel-to-path _base-path)], then
|
|
paths that syntactically extend @racket[_base-path] are converted as relative to @racket[_rel-to-path];
|
|
the @racket[_rel-to-path] must extend @racket[_base-path], in which case @racket['up]
|
|
path elements (in the sense of @racket[build-path]) may be used to make a path relative
|
|
to @racket[_rel-to-path].}
|
|
|
|
|
|
|
|
@deftogether[(
|
|
@defproc*[([(port-write-handler [out output-port?]) (any/c output-port? . -> . any)]
|
|
[(port-write-handler [out output-port?]
|
|
[proc (any/c output-port? . -> . any)])
|
|
void?])]
|
|
@defproc*[([(port-display-handler [out output-port?]) (any/c output-port? . -> . any)]
|
|
[(port-display-handler [out output-port?]
|
|
[proc (any/c output-port? . -> . any)])
|
|
void?])]
|
|
@defproc*[([(port-print-handler [out output-port?]) ((any/c output-port?) ((or/c 0 1)) . ->* . any)]
|
|
[(port-print-handler [out output-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 @racket[out]. This
|
|
handler is called to output to the port when @racket[write],
|
|
@racket[display], or @racket[print] (respectively) is applied to the
|
|
port. Each handler must accept two arguments: the value to be printed and
|
|
the destination port. The handler's return value is ignored.
|
|
|
|
A @tech{port print handler} optionally accepts a third argument, which
|
|
corresponds to the optional third argument to @racket[print]; if a
|
|
procedure given to @racket[port-print-handler] does not accept a third
|
|
argument, it is wrapped with a procedure that discards the optional
|
|
third argument.
|
|
|
|
The default port display and write handlers print Racket expressions
|
|
with Racket's built-in printer (see @secref["printing"]). The
|
|
default print handler calls the global port print handler (the value
|
|
of the @racket[global-port-print-handler] parameter); the default
|
|
global port print handler is the same as the default write handler.}
|
|
|
|
@defproc*[([(global-port-print-handler) (->* (any/c output-port?) ((or/c 0 1)) any)]
|
|
[(global-port-print-handler [proc (or/c (->* (any/c output-port?) ((or/c 0 1)) any)
|
|
(any/c output-port? . -> . any))])
|
|
void?])]{
|
|
|
|
A @tech{parameter} that determines @deftech{global port print handler},
|
|
which is called by the default port print handler (see
|
|
@racket[port-print-handler]) to @racket[print] values into a port.
|
|
The default value uses the built-in printer (see
|
|
@secref["printing"]) in @racket[print] mode.
|
|
|
|
A @tech{global port print handler} optionally accepts a third
|
|
argument, which corresponds to the optional third argument to
|
|
@racket[print]. If a procedure given to
|
|
@racket[global-port-print-handler] does not accept a third argument,
|
|
it is wrapped with a procedure that discards the optional third
|
|
argument.}
|