13.5 Writing

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | 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

On this page:

write
display
print
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
current-write-relative-directory
port-write-handler
port-display-handler
port-print-handler
global-port-print-handler

top ← 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 (n) n))
> #<procedure>
> > (define o (open-output-string))
> > (write "hello" o)
> > (get-output-string o)
> "\"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 (print datum [out quote-depth]) → void?
> datum : any/c
> out : output-port? = (current-output-port)
> quote-depth : (or/c 0 1) = 0

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 print 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 print 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 print, so that environments are free to modify the actual output generated by print 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 0 1) = 0

The same as (print 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 v ...) → void?
> out : output-port?
> form : string?
> v : 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 displays the next argument among the vs

- ~s or ~S writes the next argument among the vs

- ~v or ~V prints the next argument among the vs

- ~.‹c› where ‹c› is a, A, s, S, v, or V: truncates display, write, or print 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 vs using the current error value conversion handler (see error-value->string-handler) and current error printing width

- ~c or ~C write-chars the next argument in vs; if the next argument is not a character, the exn:fail:contract exception is raised

- ~b or ~B prints the next argument among the vs 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 vs 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 vs in hexadecimal; if the next argument is not an exact number, the exn:fail:contract exception is raised

- ~~ prints a tilde.

- ~‹w›, where ‹w› 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 vs than are supplied, the exn:fail:contract exception is raised. Similarly, when more vs 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)")
> (3 4) as a string is "(3 4)".

> procedure (printf form v ...) → void?
> form : string?
> v : any/c

The same as (fprintf (current-output-port) form v ...).

> procedure (eprintf form v ...) → void?
> form : string?
> v : any/c

The same as (fprintf (current-error-port) form v ...).

> procedure (format form v ...) → string?
> form : string?
> v : any/c

Formats to a string. The result is the same as

> (let ([o (open-output-string)])
> (fprintf o form v ...)
> (get-output-string o))

Example:

> > (format "~a as a string is ~s.\n" '(3 4) "(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

A 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

A 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

A parameter that enables or disables printing of values that have no readable 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

A 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

A 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

A 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

A 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

A parameter that controls printing hash tables; defaults to #f. See Printing Hash Tables for more information.

> parameter (print-boolean-long-form) → boolean?
> (print-boolean-long-form on?) → void?
> on? : any/c

A 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

A 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

A parameter that controls printing in print mode (as opposed to write or display); defaults to #t. See The Printer for more information.

> parameter (print-syntax-width)
> → (or/c +inf.0 0 (and/c exact-integer? (>/c 3)))
> (print-syntax-width width) → void?
> width : (or/c +inf.0 0 (and/c exact-integer? (>/c 3)))

A parameter that controls printing of syntax objects. Up to width characters are used to show the datum form of a syntax object within #<syntax...> (after the syntax object’s source location, if any).

> 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)

A 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 0 1)) . ->* . 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 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 port print handler optionally accepts a third argument, which corresponds to the optional third argument to print; 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 0 1)) any)
> (global-port-print-handler proc) → void?
> | proc |  | : |  |
> (or/c (->* (any/c output-port?) ((or/c 0 1)) any)
> (any/c output-port? . -> . any))

A parameter that determines global port print handler, which is called by the default port print handler (see port-print-handler) to print values into a port. The default value uses the built-in printer (see The Printer) in print mode.

A global port print handler optionally accepts a third argument, which corresponds to the optional third argument to print. 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.

top ← prev up next →