## Unit ports

This unit contains various extended port definitions. This unit is used by default, unless the program is compiled with the `-explicit-use` option.

### Input/output port extensions

#### with-output-to-port

`(with-output-to-port PORT THUNK)` procedure

  Call procedure `THUNK` with the current output-port temporarily bound to `PORT`.

#### make-input-port

`(make-input-port READ-CHAR CHAR-READY? CLOSE [PEEK-CHAR [READ-STRING! [READ-LINE]]])` procedure

  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`.
  - `CHAR-READY?` is a thunk which is called when `char-ready?` is called on this port and should return `#t` or `#f`.
  - `CLOSE` is a thunk which is called when the port is closed.
  - `PEEK-CHAR` is a thunk which is called when `peek-char` is called on this port and should return a character or `#!eof`. If it is not provided or `#f`, `READ-CHAR` will be used instead and the created port object handles peeking automatically (by calling `READ` and buffering the character).
  - `READ-STRING!` is called when `read-string!` is called (or the higher-level non-mutating `read-string`). It will be invoked with 4 arguments: the port created by `make-input-port`, the number of bytes to read, a string (or sometimes a blob) to read into (which may be assumed to be big enough to hold the data) and the offset 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.

#### make-output-port

`(make-output-port WRITE CLOSE [FLUSH])` procedure

  Returns a custom output port. Common operations on this port are handled by the given parameters, which should be procedures. `WRITE` is called when output is sent to the port and receives a single argument, a string. `CLOSE` is called when the port is closed and should be a procedure of no arguments. `FLUSH` (if provided) is called for flushing the output port.

#### with-error-output-to-port

`(with-error-output-to-port PORT THUNK)` procedure

  Call procedure `THUNK` with the current error output-port temporarily bound to `PORT`.

#### with-input-from-port

`(with-input-from-port PORT THUNK)` procedure

  Call procedure `THUNK` with the current input-port temporarily bound to `PORT`.

### String-port extensions

#### call-with-input-string

`(call-with-input-string STRING PROC)` procedure

  Calls the procedure `PROC` with a single argument that is a string-input-port with the contents of `STRING`.

#### call-with-output-string

`(call-with-output-string PROC)` procedure

  Calls the procedure `PROC` with a single argument that is a string-output-port. Returns the accumulated output-string.

#### with-input-from-string

`(with-input-from-string STRING THUNK)` procedure

  Call procedure `THUNK` with the current input-port temporarily bound to an input-string-port with the contents of `STRING`.

#### with-output-to-string

`(with-output-to-string THUNK)` procedure

  Call procedure `THUNK` with the current output-port temporarily bound to a string-output-port and return the accumulated output string.

### Port iterators

#### port-for-each

`(port-for-each FN THUNK)` procedure

  Apply `FN` to successive results of calling the zero argument procedure `THUNK` (typically `read`) until it returns `#!eof`, discarding the results.

#### port-map

`(port-map FN THUNK)` procedure

  Apply `FN` to successive results of calling the zero argument procedure `THUNK` (typically `read`) until it returns `#!eof`, returning a list of the collected results.

#### port-fold

`(port-fold FN ACC THUNK)` procedure

  Apply `FN` to successive results of calling the zero argument procedure `THUNK`, (typically `read`) passing the `ACC` value as the second argument. The `FN` result becomes the new `ACC` value. When `THUNK` returns `#!eof`, the last `FN` result is returned.

#### copy-port

`(copy-port FROM TO [READ [WRITE]])` procedure

  Reads all remaining data from port `FROM` using the reader procedure `READ` and writes it to port `TO` using the writer procedure `WRITE`. `READ` defaults to `read-char` and `WRITE` to `write-char`. Note that this procedure does not check `FROM` and `TO` for being ports, so the reader and writer procedures may perform arbitrary operations as long as they can be invoked as `(READ FROM)` and `(WRITE X TO)`, respectively. `copy-port` returns an undefined value.

  `copy-port` was introduced in Chicken 4.6.0.

### Funky ports

#### make-broadcast-port

`(make-broadcast-port PORT ...)` procedure

  Returns a custom output port that emits everything written into it to the ports given as `PORT ...`. Closing the broadcast port does not close any of the argument ports.

#### make-concatenated-port

`(make-concatenated-port PORT1 PORT2 ...)` procedure

  Returns a custom input port that reads its input from `PORT1`, until it is empty, then from `PORT2` and so on. Closing the concatenated port does not close any of the argument ports.

Previous: Unit data-structures

Next: Unit files