#lang scribble/doc @(require scribble/bnf "mz.ss") @(define (FmtMark . s) (apply litchar "~" s)) @title{Writing} @defproc[(write [datum any/c][out output-port? (current-output-port)]) void?]{ Writes @scheme[datum] to @scheme[out], normally in such a way that instances of core datatypes can be read back in. If @scheme[out] has a handler associated to it via @scheme[port-write-handler], then the handler is called. Otherwise, the default printer is used (in @scheme[write] mode), as configured by various parameters. See @secref["printing"] for more information about the default printer. In particular, note that @scheme[write] may require memory proportional to the depth of the value being printed, due to the initial cycle check.} @defproc[(display [datum any/c][out output-port? (current-output-port)]) void?]{ Displays @scheme[datum] to @scheme[out], similar to @scheme[write], but usually in such a way that byte- and character-based datatypes are written as raw bytes or characters. If @scheme[out] has a handler associated to it via @scheme[port-display-handler], then the handler is called. Otherwise, the default printer is used (in @scheme[display] mode), as configured by various parameters. See @secref["printing"] for more information about the default printer. In particular, note that @scheme[display] may require memory proportional to the depth of the value being printed, due to the initial cycle check.} @defproc[(print [datum any/c][out output-port? (current-output-port)]) void?]{ Writes @scheme[datum] to @scheme[out], normally the same way as @scheme[write]. If @scheme[out] has a handler associated to it via @scheme[port-print-handler], then the handler is called. Otherwise, the handler specified by @scheme[global-port-print-handler] is called; the default handler uses the default printer in @scheme[write] mode. The rationale for providing @scheme[print] is that @scheme[display] and @scheme[write] both have relatively standard output conventions, and this standardization restricts the ways that an environment can change the behavior of these procedures. No output conventions should be assumed for @scheme[print], so that environments are free to modify the actual output generated by @scheme[print] in any way.} @defproc[(fprintf [out output-port?][form string?][v any/c] ...) void?]{ Prints formatted output to @scheme[out], where @scheme[form] is a string that is printed directly, except for special formatting escapes: @itemize{ @item{@FmtMark{n} or @FmtMark{%} prints a newline, the same as @litchar{\n}} @item{@FmtMark{a} or @FmtMark{A} @scheme[display]s the next argument among the @scheme[v]s} @item{@FmtMark{s} or @FmtMark{S} @scheme[write]s the next argument among the @scheme[v]s} @item{@FmtMark{v} or @FmtMark{V} @scheme[print]s the next argument among the @scheme[v]s} @item{@FmtMark{e} or @FmtMark{E} outputs the next argument among the @scheme[v]s using the current error value conversion handler (see @scheme[error-value->string-handler]) and current error printing width} @item{@FmtMark{c} or @FmtMark{C} @scheme[write-char]s the next argument in @scheme[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 @scheme[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 @scheme[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 @scheme[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 @scheme[char-whitespace?]), skips characters in @scheme[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 @scheme[#\return], @scheme[#\newline], or @scheme[#\return] followed immediately by @scheme[#\newline].} } The @scheme[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 @scheme[v]s than are supplied, the @exnraise[exn:fail:contract]. Similarly, when more @scheme[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 @scheme[(fprintf (current-output-port) form v ...)].} @defproc[(format [form string?][v any/c] ...) string?]{ Formats to a string. The result is the same as @schemeblock[ (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 parameter that control pair printing. If the value is true, then pairs print using @litchar["{"] and @litchar["}"] instead of @litchar["("] and @litchar[")"]. The default is @scheme[#f].} @defboolparam[print-mpair-curly-braces on?]{ A parameter that control pair printing. If the value is true, then mutable pairs print using @litchar["{"] and @litchar["}"] instead of @litchar["("] and @litchar[")"]. The default is @scheme[#t].} @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 @scheme[prop:custom-write]); defaults to @scheme[#t]. See @secref["printing"] for more information.} @defboolparam[print-graph on?]{ A parameter that controls printing data with sharing; defaults to @scheme[#f]. See @secref["printing"] for more information.} @defboolparam[print-struct on?]{ A parameter that controls printing structure values in vector or @tech{prefab} form; defaults to @scheme[#t]. See @secref["printing"] for more information. This parameter has no effect on the printing of structures that have a custom-write procedure (see @scheme[prop:custom-write]).} @defboolparam[print-box on?]{ A parameter that controls printing box values; defaults to @scheme[#t]. See @secref["print-box"] for more information.} @defboolparam[print-vector-length on?]{ A parameter that controls printing vectors; defaults to @scheme[#f]. See @secref["print-vectors"] for more information.} @defboolparam[print-hash-table on?]{ A parameter that controls printing hash tables; defaults to @scheme[#f]. See @secref["print-hashtable"] for more information.} @defboolparam[print-honu on?]{ A parameter that controls printing values in an alternate syntax. See @|HonuManual| for more information.} @defparam*[current-write-relative-directory path (or/c (and/c path-string? complete-path?) false/c) (or/c (and/c path? complete-path?) false/c)]{ A parameter that is used when writing compiled code that contains pathname literals, including source-location pathnames for procedure names. When not @scheme[#f], paths that syntactically extend the parameter's value are converted to relative paths; when the resulting compiled code is read, relative paths are converted back to complete paths using the @scheme[current-load-relative-directory] parameter (if it is not @scheme[#f], otherwise the path is left relative).} @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? . -> . 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 @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["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 @deftech{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["printing"]) in @scheme[write] mode.}