13.2 Input Ports🔗ℹ

An input port is a port specifically for input. Moreover, an input string port reads from a byte string.

The Port.Input.using form sets Port.Input.current while evaluating the body result. If ~file is not supplied, then port_expr must produce a Port.Input, otherwise path_expr must produce a PathString. Breaks are disabled during the evaluation of port_expr or opening the file indicated by path_expr, the same as for Closeable.def, and the port is similarly closed on return or escape from the body sequence.

If special_wrap is not #false and if the port can supply “special” non-byte results, then the result can be special_wrap applied to the special result. Supply values as special_wrap to enable special results without extra treatment. The source_name argument can be anything, and it is delivered to the port’s implementation to potentially specialize its behavior.

If wait is #'all, then end-start bytes are written to bytes unless an end-of-file is found in the input. If wait is #'some, then the number of read bytes may be fewer, but reading will wait until at least one byte is read or an end-of-file is found. If wait is #'none, then reading will always return without waiting, even if no bytes are immediately available. If wait is #'enable_break, then waiting is like #'some, but asynchronous break exceptions are enabled during the wait; in that case, if breaks are disabled before the call to Port.Input.read_bytes_to either some bytes will be read or a break exception will be thrown, but not both.

The result can be a non-Char, non-Port.eof value if special_wrap is not #false. The special_wrap and source_name argument as used as by Port.peek_byte.

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.

Like Port.Input.read_bytes_to, but delivering decoded characters to a mutable string, str in its start through end substring.

Bytes 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 wait is not #'all, then progress can be an event produced by Port.Input.Progress.evt(port). Bytes are peeked only when progress is not ready for synchronization, otherwise the result is 0.

The read commits only if progress does not become ready first (i.e., if no other process reads from port first), and only if evt is chosen by a sync within port-commit-peeked (in which case the event result is ignored); the evt must be either a channel-put event, channel, semaphore, semaphore-peek event, “always” event, or “never” event. Suspending the thread that calls Port.Input.Progress.commit may or may not prevent the commit from proceeding.

The result is #true if data has been committed, and #false otherwise.

If no data has been peeked from port and progress is not ready, then an Exn.Fail.Annot exception is thrown. If fewer than amt items have been peeked at the current start of port’s stream, then only the peeked items are committed as read. If port’s stream currently starts at a Port.eof or a non-byte special value, then only the Port.eof or special value is committed as read.

If progress is not a result of Port.Input.Progress.evt(port), then an Exn.Fail.Annot exception is thrown.