Reading and Printing

In addition to the standard reading procedures, MzScheme provides read-line, read-string, and read-string!:

• (read-line [port mode]) returns a string containing the next line of characters from port. If port is omitted, the current input port is used.

  Characters are read from port 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-f-file is encountered, eof is returned.

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

  • 'linefeed -- break lines on linefeed characters; this is the default.
  • 'return -- break lines on return characters.
  • 'return-linefeed -- break 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 -- break 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 -- break lines on either a return or linefeed character, without recognizing return-linefeed combinations.
  Return and linefeed characters are detected after the conversions that are automatically performed when reading a file in text mode. For example, reading a file in text mode under Windows automatically changes return-linefeed combinations to a linefeed. Thus, when a file is opened in text mode, 'linefeed is usually the appropriate read-line mode.
• (read-string n [port]) returns a string containing the next n characters from port. The default value of port is the current input port.

  If n is 0, then the empty string is returned. Otherwise, if fewer than n characters are available before an end-of-file is encountered, then the returned string will contain only those characters before the end-of-file (i.e., the returned string's length will be less than n). If no characters are available before an end-of-file, then eof is returned.

• (read-string! str [port start end]) reads characters from port and puts them into the string str starting from index start (inclusive) up to end (exclusive). The default value of port is the current input port. The default value of start is 0. The default value of end is the length of the str. Like substring, the exn:application:range:bounds:string exception is raised if start or end is out-of-range for str.

  If n is 0, then 0 is returned and the string is not modified. If no characters are available before an end-of-file, then eof is returned. Otherwise, the return value is the number of characters read. If m characters are read and m < start - end, then str is not modified at indices start + m though end.

In addition to the standard printing procedures, MzScheme provides print, which outputs values to a port by calling the port's print handler (see section 11.1.9):

• (print v [port]) outputs v to port. The default value of port is the current output port.

The print procedure is used to print Scheme values in a context where a programmer expects to see a Scheme value. The rationale for providing print is that display and write both have 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 print so that environments are free to modify the actual output generated by print in any way. Unlike the port display and write handlers, a global port print handler can be installed through the global-port-print-handler parameter (see section 9.4.1.2).

Formatted output is written to a port with fprintf:

• (fprintf port format args ) prints formatted output to port, where format is a string that is printed; format can contain special formatting tags:
  • ~n or ~% prints a newline
  • ~a or ~A displays the next argument in args
  • ~s or ~S writes the next argument in args
  • ~v or ~V prints the next argument in args
  • ~e or ~E outputs the next argument in args using the current error value conversion handler (see section 9.4.1.9) and current error printing width
  • ~c or ~C write-chars the next argument in args; if the next argument is not a character, the exn:application:fprintf:argument-type exception is raised
  • ~b or ~B prints the next argument in args in binary; if the next argument is not an exact number, the exn:application:fprintf:argument-type exception is raised
  • ~o or ~O prints the next argument in args in octal; if the next argument is not an exact number, the exn:application:fprintf:argument-type exception is raised
  • ~x or ~X prints the next argument in args in hexadecimal; if the next argument is not an exact number, the exn:application:fprintf:argument-type exception is raised
  • ~~ prints a tilde (~)
  • ~w, where w is a whitespace character, skips characters in the format string until a non-whitespace character is encountered or until a second end-of-line is encountered (whichever happens first). An end-of-line is either #\return, #\newline, or #\return followed immediately by #\newline (on all platforms).

  The return value is void.

• (printf format args ) same as fprintf with the current output port.
• (format format args ) same as fprintf with a string output port where the final string is returned as the result.

When an illegal format string is supplied to one of these procedures, the exn:application:type exception is raised. When the format string requires more additional arguments than are supplied, the exn:application:fprintf:no-argument exception is raised. When more additional arguments are supplied than are used by the format string, the exn:application:fprintf:extra-arguments exception is raised.

For example,

  (fprintf port "~a as a string is ~s.~n" '(3 4) "(3 4)") 

prints this message to port:

  (3 4) as a string is "(3 4)". 

followed by a newline.