6.52 Input and Output🔗ℹ

A port is an input or output stream for a file, network connection, terminal, etc. An input port is specifically for input, while an output port is specifically for output.

The Port.EOF annotation is satisfied by the Port.eof value.

In #'text mode, strings, symbols, identifiers, and keywords print as their character content, a byte string prints as its raw byte content, and a syntax object prints as unquoted. Any other predefined kind of value prints the same in #'text and #'expr mode, but a class can implement Printable so that its instances print differently in different modes.

When pretty is #true, then compound values like lists may print with line breaks to split the output across lines. When pretty is #false, then printing tends to use a single line, but also prints faster. The value of the Printable.current_pretty context parameter is to match pretty while printing, which affects functions like PrintDesc.list.

> print("apple")

apple

> print("apple", ~mode: #'expr)

"apple"

> print("apple", "banana", "coconut")

apple banana coconut

> print("apple", "banana", "coconut", ~pretty: #true)

apple

banana

coconut

Characters are read from in until a line separator or an end-of-file is read. The line separator is not included in the result string (but it is removed from the port’s stream). If no characters are read before an end-of-file is encountered, Port.eof is returned.

The mode argument determines the line separator(s). It must be one of the following symbols:

• #'linefeed breaks lines on linefeed characters.

• #'return breaks lines on return characters.

• #'return_linefeed breaks lines on return-linefeed combinations. If a return character is not followed by a linefeed character, it is included in the result string; similarly, a linefeed that is not preceded by a return is included in the result string.

• #'any breaks lines on any of a return character, linefeed character, or return-linefeed combination. If a return character is followed by a linefeed character, the two are treated as a combination.

• #'any_one breaks lines on either a return or linefeed character, without recognizing return-linefeed combinations.

If amount is 0, then the empty string is returned. Otherwise, if fewer than amount characters are available before an end-of-file is encountered, then the returned string will contain only those characters before the end-of-file; that is, the returned string’s length will be less than amount. (A temporary string of size amount is allocated while reading the input, even if the size of the result is less than amount characters.) If no characters are available before an end-of-file, then Port.eof is returned.

Port.Output.open_string does the same as Port.Output.open_bytes, but can be used to clarify the intention together with Port.Output.get_string.

Port.Output.get_string is like Port.Output.get_bytes, but returns a string converted from the byte string instead.

An interface that a class can implement (publicly or privately) to customize the way its objects print. In the simplest case, an implementation of the interface’s describe method returns a string to use as an object’s printed form. More generally, a describe method implementation returns a description of how to print a value, where the description is created using functions like PrintDesc.concat, PrintDesc.newline, and PrintDesc.or.

The Printable interface has one method:

• describe(mode, recur) — returns a PrintDesc given a mode, which is either #'text or #'expr, and a recur function, which accepts a value and an optional ~mode like Printable.describe (unlike Printable.describe, the ~mode defaults to #'expr, which is generally desirable when printing subcomponents); the recur function is specific to a particular overall print action so that it can handle cycles and graph references.

The optional column argument indicates the current column for output, in case pd contains a PrintDesc.align description that needs to update indentation based on the current column.

A string or byte string prints as its content. Other PrintDesc values describe concatenations, line breaks, indentation, and formatting options.

• PrintDesc.concat concatenates the pds in order, with nothing in between.

  > Printable.render(     PrintDesc.concat(       "a", "b",     ))

  ab

• PrintDesc.newline prints a newline plus indentation, where indentation is determined by the surrounding description.

  > Printable.render(     PrintDesc.concat(       "a", PrintDesc.newline(),       "b",     ))

  a

  b

• PrintDesc.nest increases the current indentation by n while printing pd.

  > Printable.render(     PrintDesc.concat(       "a",       PrintDesc.nest(         2,         PrintDesc.concat(           PrintDesc.newline(),           "b",         )),     ))

  a

  b

• PrintDesc.align sets the current indentation (independent of the current indentation) to the current output column while printing pd.

  > Printable.render(     PrintDesc.concat(       "a",       PrintDesc.align(         PrintDesc.concat(           "b", PrintDesc.newline(),           "c",         )),     ))

  ab

  c

• PrintDesc.or offers two printign alternatives. Either pd1 or pd2 will be printed, depending on choices made by a pretty-printer configuration and as constrainted by PrintDesc.flat constraints.

  > Printable.render(     PrintDesc.or(       PrintDesc.concat(         "a", "; ", "b",       ),       PrintDesc.concat(         "a", PrintDesc.newline(),         "b",       )))

  a; b

• PrintDesc.flat prints the same as pd, but only if that is possible without any newlines. If all possible ways of rendering pd involve a newline, printing fails. A PrintDesc.flat constraint it particularly useful in one branch of a PrintDesc.or to constrain a description received by recursive description.

  > def sub = PrintDesc.or(     PrintDesc.concat(       "a", "; ", "b",     ),     PrintDesc.concat(       "a", PrintDesc.newline(),       "b",     ))

  > Printable.render(     PrintDesc.or(       PrintDesc.concat(         "f(", PrintDesc.flat(sub), ")",       ),       PrintDesc.concat(         "f(",         PrintDesc.nest(           2,           PrintDesc.concat(             PrintDesc.newline(),             sub,           )),         PrintDesc.newline(),         ")",       )))

  f(a; b)

The single-line variant constrains pre_pd, head, and any member of elements other than the last one to be printed as a single-line, too. If one of those has no single-line option, then the combined single-line variant will not be used (which can cause the description to be unprintable).

> Printable.render(     PrintDesc.list(       "Posn(",       ["x", "y"],       ")"     ))

Posn(x, y)

> Printable.render(     PrintDesc.block(       "begin",       PrintDesc.concat(         "one", PrintDesc.newline(),         "two",       )))

begin:

one

two

Sharing is reported by a #n= prefix on a printed value, and then #n# with the same number n is used for later occurrences of the value.

The same notation is used to show cyclic data, which is shown independent of the value of the Printable.current_graph parameter.