[[tags: manual]]
[[toc:]]

== 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

<procedure>(with-output-to-port PORT THUNK)</procedure>

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

==== make-input-port

<procedure>(make-input-port READ READY? CLOSE [PEEK])</procedure>

Returns a custom input port. Common operations on this
port are handled by the given parameters, which should be
procedures of no arguments. {{READ}} is called when the
next character is to be read and should return a character or
{{#!eof}}. {{READY?}} is called
when {{char-ready?}} is called on this port and should return
{{#t}} or {{#f}}.  {{CLOSE}} is called when the port is
closed. {{PEEK}} is called when {{peek-char}} is called on this
port and should return a character or {{#!eof}}.
if the argument {{PEEK}} is not given, then {{READ}} is used
instead and the created port object handles peeking automatically (by
calling {{READ}} and buffering the character).


==== make-output-port

<procedure>(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

<procedure>(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

<procedure>(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

<procedure>(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

<procedure>(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

<procedure>(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

<procedure>(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

<procedure>(port-for-each FN THUNK)</procedure>

Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
until it returns {{#!eof}}, discarding the results.

==== port-map

<procedure>(port-map FN THUNK)</procedure>

Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}
until it returns {{#!eof}}, returning a list of the collected results.

==== port-fold

<procedure>(port-fold FN ACC THUNK)</procedure>

Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}},
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

<procedure>(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.


=== Funky ports

==== make-broadcast-port

<procedure>(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

<procedure>(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]]
