## Module (chicken port)

This module contains various extended port definitions.

All errors related to failing port operations will signal a condition of kind `exn`.

- New in CHICKEN 5.4.0: Errors caused by underlying C calls that change errno will produce a condition object with an `errno` property, which can be accessed with `(get-condition-property <the-condition-object> 'exn 'errno)`.

### Port attributes

#### port-name

port-name #!optional PORT procedure

  Fetch filename from PORT. This returns the filename that was used to open this file. Returns a special tag string, enclosed into parentheses for non-file ports. PORT defaults to the value of `(current-input-port)`.

#### port-position

port-position #!optional PORT procedure

  Returns the current position of PORT as two values: row and column number. If the port does not support such an operation an error is signaled. This procedure is currently only available for input ports. PORT defaults to the value of `(current-input-port)`.

#### set-port-name!

set-port-name! PORT STRING procedure

  Sets the name of PORT to STRING.

### Setting the file buffering mode

#### set-buffering-mode!

set-buffering-mode! PORT MODE #!optional BUFSIZE procedure

  Sets the buffering-mode for the file associated with PORT to MODE, which should be one of the keywords `#:full`, `#:line` or `#:none`. If BUFSIZE is specified it determines the size of the buffer to be used (if any).

  This procedure doesn't work on custom ports, such as those created with `make-input-port` or `make-output-port`.

### Terminal ports

#### terminal-name

terminal-name PORT procedure

  Returns the name of the terminal that is connected to PORT.

  On Windows, this procedure always raises an exception.

#### terminal-port?

terminal-port? PORT procedure

  Returns `#t` if PORT is connected to a terminal and `#f` otherwise.

#### terminal-size

terminal-size PORT procedure

  Returns two values, the number of rows and columns of the terminal that is connected to PORT or `0`, `0` if the terminal size can not be obtained.

  On Windows, this procedure always raises an exception.

### 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 #!optional 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 #!optional 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.

#### with-error-output-to-string

with-error-output-to-string THUNK procedure

  Call procedure THUNK with the current error 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 #!optional 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-bidirectional-port

make-bidirectional-port INPUT-PORT OUTPUT-PORT procedure

  Returns a joint input/output port that proxies port operations to the given INPUT-PORT and OUTPUT-PORT, respectively. This port satisfies both `input-port?` and `output-port?`, and its two directions may be closed independently.

#### 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: Module (chicken plist)

Next: Module (chicken pretty-print)