13.5 Writing
The Racket Reference
Language Model
Notation for Documentation
Syntactic Forms
Datatypes
Structures
Classes and Objects
Units
Contracts
Pattern Matching
10
Control Flow
11
Concurrency and Parallelism
12
Macros
13
Input and Output
14
Reflection and Security
15
Operating System
16
Memory Management
17
Unsafe Operations
18
Running Racket
Bibliography
Index
13
Input and Output
13.1
Ports
13.2
Byte and String Input
13.3
Byte and String Output
13.4
Reading
13.5
Writing
13.6
Pretty Printing
13.7
Reader Extension
13.8
Printer Extension
13.9
Serialization
13.10
Fast-
Load Serialization
13.11
Cryptographic Hashing
On this page:
write
display
writeln
displayln
println
fprintf
printf
eprintf
format
print-
pair-
curly-
braces
print-
mpair-
curly-
braces
print-
unreadable
print-
graph
print-
struct
print-
box
print-
vector-
length
print-
hash-
table
print-
boolean-
long-
form
print-
reader-
abbreviations
print-
as-
expression
print-
syntax-
width
print-
value-
columns
current-
write-
relative-
directory
port-
write-
handler
port-
display-
handler
port-
print-
handler
global-
port-
print-
handler
default-
global-
port-
print-
handler
Racket
top
contents
← prev
up
next →
13.5
Writing
procedure
write
datum
out
void?
datum
any/c
out
output-port?
current-output-port
Writes
datum
to
out
, normally in such a way that
instances of core datatypes can be read back in. If
out
has a
handler associated to it via
port-write-handler
, then the
handler is called. Otherwise, the
default printer
is used (in
write
mode), as configured by various parameters.
See
The Printer
for more information about the default
printer. In particular, note that
write
may require memory
proportional to the depth of the value being printed, due to the
initial cycle check.
Examples:
write
hi
hi
write
lambda
#
define
open-output-string
write
"hello"
get-output-string
"\"hello\""
procedure
display
datum
out
void?
datum
any/c
out
output-port?
current-output-port
Displays
datum
to
out
, similar to
write
but usually in such a way that byte- and character-based datatypes are
written as raw bytes or characters. If
out
has a handler
associated to it via
port-display-handler
, then the handler
is called. Otherwise, the
default printer
is used (in
display
mode), as configured by various parameters.
See
The Printer
for more information about the default
printer. In particular, note that
display
may require memory
proportional to the depth of the value being printed, due to the
initial cycle check.
procedure
datum
out
quote-depth
void?
datum
any/c
out
output-port?
current-output-port
quote-depth
or/c
Prints
datum
to
out
. If
out
has a handler
associated to it via
port-print-handler
, then the handler is
called. Otherwise, the handler specified by
global-port-print-handler
is called; the default handler uses
the
default printer
in
mode.
The optional
quote-depth
argument adjusts printing when the
print-as-expression
parameter is set to
#t
. In that
case,
quote-depth
specifies the starting quote depth for
printing
datum
The rationale for providing
is that
display
and
write
both have specific output conventions, and those
conventions restrict the ways that an environment can change the
behavior of
display
and
write
procedures. No output
conventions should be assumed for
, so that environments
are free to modify the actual output generated by
in
any way.
procedure
writeln
datum
out
void?
datum
any/c
out
output-port?
current-output-port
The same as
write
datum
out
followed by
newline
out
Added in version 6.1.1.8 of package
base
procedure
displayln
datum
out
void?
datum
any/c
out
output-port?
current-output-port
The same as
display
datum
out
followed by
newline
out
which is similar to
println
in Pascal or Java.
procedure
println
datum
out
quote-depth
void?
datum
any/c
out
output-port?
current-output-port
quote-depth
or/c
The same as
datum
out
quote-depth
followed by
newline
out
The
println
function is not equivalent to
println
in
other languages, because
println
uses printing conventions
that are closer to
write
than to
display
. For a closer
analog to
println
in other languages, use
displayln
Added in version 6.1.1.8 of package
base
procedure
fprintf
out
form
...
void?
out
output-port?
form
string?
any/c
Prints formatted output to
out
, where
form
is a string
that is printed directly, except for special formatting
escapes:
~n
or
~%
prints a newline character (which
is equivalent to
\n
in a literal format string)
~a
or
~A
display
s the next argument
among the
~s
or
~S
write
s the next argument
among the
~v
or
~V
s the next argument
among the
~.
where
is
, or
truncates default-handler
display
write
, or
output
to
error-print-width
characters, using
...
as
the last three characters if the untruncated output would be longer
~e
or
~E
outputs the next argument among the
s using the current error value conversion handler (see
error-value->string-handler
) and current error printing
width
~c
or
~C
write-char
s the
next argument in
s; if the next argument is not a
character, the
exn:fail:contract
exception is raised
~b
or
~B
prints the next argument among the
s in binary; if the next argument is not an exact number, the
exn:fail:contract
exception is raised
~o
or
~O
prints the next argument among the
s in octal; if the next argument is not an exact number, the
exn:fail:contract
exception is raised
~x
or
~X
prints the next argument among the
s in hexadecimal; if the next argument is not an exact
number, the
exn:fail:contract
exception is raised
~~
prints a tilde.
, where
is a whitespace
character (see
char-whitespace?
), skips characters in
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
#\return
#\newline
, or
#\return
followed immediately by
#\newline
The
form
string must not contain any
that is
not one of the above escapes, otherwise the
exn:fail:contract
exception is raised. When the format string requires more
s than are supplied, the
exn:fail:contract
exception is raised. Similarly, when more
s are
supplied than are used by the format string, the
exn:fail:contract
exception is raised.
Example:
fprintf
current-output-port
"~a as a string is ~s.\n"
"(3 4)"
(3 4) as a string is "(3 4)".
procedure
printf
form
...
void?
form
string?
any/c
The same as
fprintf
current-output-port
form
...
procedure
eprintf
form
...
void?
form
string?
any/c
The same as
fprintf
current-error-port
form
...
procedure
format
form
...
string?
form
string?
any/c
Formats to a string. The result is the same as
let
open-output-string
fprintf
form
...
get-output-string
Example:
format
"~a as a string is ~s.\n"
"(3 4)"
"(3 4) as a string is \"(3 4)\".\n"
parameter
print-pair-curly-braces
boolean?
print-pair-curly-braces
on?
void?
on?
any/c
parameter
that controls pair printing. If the value is true, then
pairs print using
and
instead of
and
. The default is
#f
parameter
print-mpair-curly-braces
boolean?
print-mpair-curly-braces
on?
void?
on?
any/c
parameter
that controls pair printing. If the value is true, then
mutable pairs print using
and
instead of
and
. The default is
#t
parameter
print-unreadable
boolean?
print-unreadable
on?
void?
on?
any/c
parameter
that enables or disables
and
write
of values that have no
read
able form (using the default reader), including
structures that have a custom-write procedure (see
prop:custom-write
), but not including
uninterned
symbols and
unreadable symbols
(which print the same as
interned
symbols). If the parameter value is
#f
, an
attempt to print an unreadable value raises
exn:fail
. The
parameter value defaults to
#t
. See
The Printer
for
more information.
parameter
print-graph
boolean?
print-graph
on?
void?
on?
any/c
parameter
that controls printing data with sharing; defaults to
#f
. See
The Printer
for more information.
parameter
print-struct
boolean?
print-struct
on?
void?
on?
any/c
parameter
that controls printing structure values in vector or
prefab
form; defaults to
#t
. See
The Printer
for more information. This parameter has no effect on the printing of
structures that have a custom-write procedure (see
prop:custom-write
).
parameter
print-box
boolean?
print-box
on?
void?
on?
any/c
parameter
that controls printing box values; defaults to
#t
. See
Printing Boxes
for more information.
parameter
print-vector-length
boolean?
print-vector-length
on?
void?
on?
any/c
parameter
that controls printing vectors; defaults to
#f
. See
Printing Vectors
for more information.
parameter
print-hash-table
boolean?
print-hash-table
on?
void?
on?
any/c
parameter
that controls printing hash tables; defaults to
#t
. See
Printing Hash Tables
for more information.
parameter
print-boolean-long-form
boolean?
print-boolean-long-form
on?
void?
on?
any/c
parameter
that controls printing of booleans. When the parameter’s
value is true,
#t
and
#f
print as
#true
and
#false
, otherwise they print as
#t
and
#f
. The default is
#f
parameter
print-reader-abbreviations
boolean?
print-reader-abbreviations
on?
void?
on?
any/c
parameter
that controls printing of two-element lists that start
with
quote
quasiquote
unquote
unquote-splicing
syntax
quasisyntax
unsyntax
, or
unsyntax-splicing
; defaults to
#f
. See
Printing Pairs and Lists
for more information.
parameter
print-as-expression
boolean?
print-as-expression
on?
void?
on?
any/c
parameter
that controls printing in
mode (as opposed
to
write
or
display
); defaults to
#t
. See
The Printer
for more information.
parameter
print-syntax-width
or/c
+inf.0
and/c
exact-integer?
>/c
print-syntax-width
width
void?
width
or/c
+inf.0
and/c
exact-integer?
>/c
parameter
that controls printing of
syntax objects
. Up to
width
characters are used to show the datum form of a syntax
object within
#
(after the
syntax object
’s source location, if any), where
...
is
used as the last three characters if the printed form would otherwise be longer
than
width
characters. A value of
for
width
means that the datum is not shown at all.
parameter
print-value-columns
or/c
+inf.0
and/c
exact-integer?
>/c
print-value-columns
columns
void?
columns
or/c
+inf.0
and/c
exact-integer?
>/c
parameter
that contains a recommendation for the number of
columns that should be used for printing values via
May or may not be respected by
- the current default
handler for
does not. It is expected that REPLs that use
some form of pretty-printing for values respect this parameter.
Added in version 8.0.0.13 of package
base
parameter
current-write-relative-directory
or/c
and/c
path?
complete-path?
cons/c
and/c
path?
complete-path?
and/c
path?
complete-path?
#f
current-write-relative-directory
path
void?
path
or/c
and/c
path-string?
complete-path?
cons/c
and/c
path-string?
complete-path?
and/c
path-string?
complete-path?
#f
parameter
that is used when writing compiled code (see
Printing Compiled Code
) that contains
pathname literals, including source-location pathnames for procedure
names. When the parameter’s value is a
path
, paths that syntactically extend
path
are converted to relative paths; when the resulting
compiled code is read, relative paths are converted back to complete
paths using the
current-load-relative-directory
parameter (if
it is not
#f
; otherwise, the path is left relative).
When the parameter’s value is
cons
rel-to-path
base-path
, then
paths that syntactically extend
base-path
are converted as relative to
rel-to-path
the
rel-to-path
must extend
base-path
, in which case
up
path elements (in the sense of
build-path
) may be used to make a path relative
to
rel-to-path
procedure
port-write-handler
out
any/c
output-port?
->
any
out
output-port?
port-write-handler
out
proc
void?
out
output-port?
proc
any/c
output-port?
->
any
procedure
port-display-handler
out
any/c
output-port?
->
any
out
output-port?
port-display-handler
out
proc
void?
out
output-port?
proc
any/c
output-port?
->
any
procedure
port-print-handler
out
any/c
output-port?
or/c
->
any
out
output-port?
port-print-handler
out
proc
void?
out
output-port?
proc
any/c
output-port?
->
any
Gets or sets the
port write handler
port display
handler
, or
port print handler
for
out
. This
handler is called to output to the port when
write
display
, or
(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.
port print handler
optionally accepts a third argument, which
corresponds to the optional third argument to
; if a
procedure given to
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
The Printer
). The
default print handler calls the global port print handler (the value
of the
global-port-print-handler
parameter); the default
global port print handler is the same as the default write handler.
procedure
global-port-print-handler
->
any/c
output-port?
or/c
any
global-port-print-handler
proc
void?
proc
or/c
->
any/c
output-port?
or/c
any
any/c
output-port?
->
any
parameter
that determines
global port print handler
which is called by the default port print handler (see
port-print-handler
) to
values into a port.
The default value is equivalent to
default-global-port-print-handler
global port print handler
optionally accepts a third
argument, which corresponds to the optional third argument to
. If a procedure given to
global-port-print-handler
does not accept a third argument,
it is wrapped with a procedure that discards the optional third
argument.
procedure
default-global-port-print-handler
out
print-depth
void?
any/c
out
output-port?
print-depth
or/c
Prints
to
out
using the built-in printer (see
The Printer
) in
mode.
Added in version 8.8.0.6 of package
base
top
contents
← prev
up
next →
US