chickadee » chicken » port » make-input-port

make-input-port READ-CHAR CHAR-READY? CLOSE #!key peek-char read-bytevector read-lineprocedure
make-binary-input-port READ-U8 U8-READY? CLOSE #!key peek-u8 read-bytevectorprocedure

Returns a custom input port. Common operations on this port are handled by the given parameters, which should be procedures of no arguments. The following arguments are all different kinds of reader procedures:

  • READ-CHAR is the most fundamental reader, and must always be present. It is a thunk which is called when the next character is to be read and it should return a character or #!eof.
  • READ-U8 similar to READ-CHAR but reads and returns a byte.
  • CHAR-READY?/U8-READY? are thunks which are called when char-ready? or u8-ready? are called on this port and should return #t or #f.
  • CLOSE is a thunk which is called when the port is closed.
  • peek-char/peek-u8 are thunks which are called when peek-char or peek-u8 are called on this port and should return a character/byte or #!eof. If not provided or #f, READ-CHAR/READ-U8 will be used instead and the created port object handles peeking automatically (by calling the reader procedure and buffering the character).
  • read-bytevector is called when read-bytevector or read-string! is called (or the higher-level non-mutating read-string and read-bytevector). It will be invoked with 3 arguments: a bytevector to read into (which may be assumed to be big enough to hold the data) and the offsets of the starting and ending position into the buffer at which to put the data to read. It should return the number of bytes that have successfully been read, which should always be equal to the requested bytes unless EOF was hit, in which case it can be less. If this procedure is not provided or #f, the buffer will be filled by repeated reads to READ-CHAR.
  • READ-LINE is called when read-line is called. It will be invoked with two arguments: the port created by make-input-port and the maximum number of characters to read (or #f). If this procedure is not provided or #f, the buffer will be filled by repeated reads to READ-CHAR.

All the optional procedures except for PEEK-CHAR are responsible for updating the port's position, which currently can only be done via low-level slot accessors like ##sys#setslot; slot 4 is the row number (ie, the line) and slot 5 is the column number (ie, the character on the line). If the port's positions are not updated, port-position won't work.

Note that reading binary input from a custom non-binary input port is only possible when the read-bytevector operation is given, as byte-input can currently not ben synthesized from character-input operations.