► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

► | 13 | Input and Output

13.1 | Ports
13.2 | Byte and String Input
13.3 | Byte and String Output
13.4 | Reading
13.5 | Writing
13.6 | Pretty Printing
13.7 | Reader Extension
13.8 | Printer Extension
13.9 | Serialization
13.10 | Fast-Load Serialization
13.11 | Cryptographic Hashing

▼ | 13.1 | Ports

13.1.1 | Encodings and Locales
13.1.2 | Managing Ports
13.1.3 | Port Buffers and Positions
13.1.4 | Counting Positions, Lines, and Columns
13.1.5 | File Ports
13.1.6 | String Ports
13.1.7 | Pipes
13.1.8 | Structures as Ports
13.1.9 | Custom Ports
13.1.10 | More Port Constructors, Procedures, and Events

► | 13.1.10 | More Port Constructors, Procedures, and Events

13.1.10.1 | Port String and List Conversions
13.1.10.2 | Creating Ports
13.1.10.3 | Port Events
13.1.10.4 | Copying Streams

On this page:

13.1.10.1`` Port String and List Conversions
port->list
port->string
port->bytes
port->lines
port->bytes-lines
display-lines
call-with-output-string
call-with-output-bytes
with-output-to-string
with-output-to-bytes
call-with-input-string
call-with-input-bytes
with-input-from-string
with-input-from-bytes
13.1.10.2`` Creating Ports
input-port-append
make-input-port/ read-to-peek
make-limited-input-port
make-pipe-with-specials
combine-output
merge-input
open-output-nowhere
peeking-input-port
reencode-input-port
reencode-output-port
dup-input-port
dup-output-port
relocate-input-port
relocate-output-port
transplant-input-port
transplant-output-port
filter-read-input-port
special-filter-input-port
13.1.10.3`` Port Events
eof-evt
read-bytes-evt
read-bytes!-evt
read-bytes-avail!-evt
read-string-evt
read-string!-evt
read-line-evt
read-bytes-line-evt
peek-bytes-evt
peek-bytes!-evt
peek-bytes-avail!-evt
peek-string-evt
peek-string!-evt
regexp-match-evt
13.1.10.4`` Copying Streams
convert-stream
copy-port

top ← prev up next →

##### 13.1.10`` More Port Constructors, Procedures, and Events

(require racket/port) | package: base

The bindings documented in this section are provided by the racket/port and racket libraries, but not racket/base.

##### 13.1.10.1`` Port String and List Conversions

> > procedure

> > (port->list [r in]) → (listof any/c)

> r : (input-port? . -> . any/c) = read
> in : input-port? = (current-input-port)

Returns a list whose elements are produced by calling r on in until it produces eof.

Examples:

> > (define (read-number input-port)
> (define char (read-char input-port))
> (if (eof-object? char)
> char
> (string->number (string char))))

> > (port->list read-number (open-input-string "12345"))
> '(1 2 3 4 5)

> > procedure

> > (port->string [in #:close? close?]) → string?

> in : input-port? = (current-input-port)
> close? : any/c = #f

Reads all characters from in and returns them as a string. The input port is closed unless close? is #f.

Example:

> > (port->string (open-input-string "hello world"))
> "hello world"

Changed in version 6.8.0.2 of package base: Added the #:close? argument.

> > procedure

> > (port->bytes [in #:close? close?]) → bytes?

> in : input-port? = (current-input-port)
> close? : any/c = #f

Reads all bytes from in and returns them as a byte string. The input port is closed unless close? is #f.

Example:

> > (port->bytes (open-input-string "hello world"))
> #"hello world"

Changed in version 6.8.0.2 of package base: Added the #:close? argument.

> > procedure

> > (port->lines | [ | in |  |  |  |
> > |  | #:line-mode line-mode |  |  |  |
> > |  | #:close? close?]) |  | → |  | (listof string?)

> in : input-port? = (current-input-port)

> | line-mode |  | : |  | (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
> |  |  | = |  | 'any

> close? : any/c = #f

Read all characters from in, breaking them into lines. The line-mode argument is the same as the second argument to read-line, but the default is 'any instead of 'linefeed. The input port is closed unless close? is #f.

Example:

> > (port->lines
> (open-input-string "line 1\nline 2\n line 3\nline 4"))

> '("line 1" "line 2" " line 3" "line 4")

Changed in version 6.8.0.2 of package base: Added the #:close? argument.

> > procedure

> > (port->bytes-lines | [ | in |  |  |  |
> > |  | #:line-mode line-mode |  |  |  |
> > |  | #:close? close?]) |  | → |  | (listof bytes?)

> in : input-port? = (current-input-port)

> | line-mode |  | : |  | (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
> |  |  | = |  | 'any

> close? : any/c = #f

Like port->lines, but reading bytes and collecting them into lines like read-bytes-line. The input port is closed unless close? is #f.

Example:

> > (port->bytes-lines
> (open-input-string "line 1\nline 2\n line 3\nline 4"))

> '(#"line 1" #"line 2" #" line 3" #"line 4")

Changed in version 6.8.0.2 of package base: Added the #:close? argument.

> > procedure

> > (display-lines |  | lst |  |  |  |
> > | [ | out |  |  |  |
> > |  | #:separator separator]) |  | → |  | void?

> lst : list?
> out : output-port? = (current-output-port)
> separator : any/c = #"\n"

Uses display on each element of lst to out, adding separator after each element.

> > procedure

> > (call-with-output-string proc) → string?

> proc : (output-port? . -> . any)

Calls proc with an output port that accumulates all output into a string, and returns the string.

The port passed to proc is like the one created by open-output-string, except that it is wrapped via dup-output-port, so that proc cannot access the port’s content using get-output-string. If control jumps back into proc, the port continues to accumulate new data, and call-with-output-string returns both the old data and newly accumulated data.

> > procedure

> > (call-with-output-bytes proc) → bytes?

> proc : (output-port? . -> . any)

Like call-with-output-string, but returns the accumulated result in a byte string instead of a string. Furthermore, the port’s content is emptied when call-with-output-bytes returns, so that if control jumps back into proc and returns a second time, only the newly accumulated bytes are returned.

> > procedure

> > (with-output-to-string proc) → string?

> proc : (-> any)

Equivalent to

> (call-with-output-string
> (lambda (p) (parameterize ([current-output-port p])
> (proc))))

> > procedure

> > (with-output-to-bytes proc) → bytes?

> proc : (-> any)

Equivalent to

> (call-with-output-bytes
> (lambda (p) (parameterize ([current-output-port p])
> (proc))))

> > procedure

> > (call-with-input-string str proc) → any

> str : string?
> proc : (input-port? . -> . any)

Equivalent to (proc (open-input-string str)).

> > procedure

> > (call-with-input-bytes bstr proc) → any

> bstr : bytes?
> proc : (input-port? . -> . any)

Equivalent to (proc (open-input-bytes bstr)).

> > procedure

> > (with-input-from-string str proc) → any

> str : string?
> proc : (-> any)

Equivalent to

> (parameterize ([current-input-port (open-input-string str)])
> (proc))

> > procedure

> > (with-input-from-bytes bstr proc) → any

> bstr : bytes?
> proc : (-> any)

Equivalent to

> (parameterize ([current-input-port (open-input-bytes str)])
> (proc))

##### 13.1.10.2`` Creating Ports

> > procedure

> > (input-port-append |  | close-at-eof? |  |  |  |
> > |  | in ... |  |  |  |
> > | [ | #:name name]) |  | → |  | input-port?

> close-at-eof? : any/c
> in : input-port?
> name : any/c = (map object-name in)

Takes any number of input ports and returns an input port. Reading from the input port draws bytes (and special non-byte values) from the given input ports in order. If close-at-eof? is true, then each port is closed when an end-of-file is encountered from the port, or when the result input port is closed. Otherwise, data not read from the returned input port remains available for reading in its original input port.

The name argument determines the name as reported by object-name for the returned input port.

See also merge-input, which interleaves data from multiple input ports as it becomes available.

Changed in version 6.90.0.19 of package base: Added the name argument.

> > procedure

> > (make-input-port/read-to-peek |  | name |  |  |  |
> > |  | read-in |  |  |  |
> > |  | fast-peek |  |  |  |
> > |  | close |  |  |  |
> > | [ | get-location |  |  |  |
> > |  | count-lines! |  |  |  |
> > |  | init-position |  |  |  |
> > |  | buffer-mode |  |  |  |
> > |  | buffering? |  |  |  |
> > |  | on-consumed]) |  | → |  | input-port?

> name : any/c

> read-in

> :

> (bytes?
> . -> . (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?))

> fast-peek

> :

> (or/c #f
> (bytes? exact-nonnegative-integer?
> (bytes? exact-nonnegative-integer?
> . -> . (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f))
> . -> . (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f)))

> close : (-> any)

> get-location

> :

> (or/c
> (->
> (values
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)
> (or/c exact-positive-integer? #f)))
> #f)

> =

> #f

> count-lines! : (-> any) = void
> init-position : exact-positive-integer? = 1

> buffer-mode

> :

> (or/c (case-> ((or/c 'block 'none) . -> . any)
> (-> (or/c 'block 'none #f)))
> #f)

> |  |  | = |  | #f

> buffering? : any/c = #f

> on-consumed

> :

> (or/c ((or/c exact-nonnegative-integer? eof-object?
> procedure? evt?)
> . -> . any)
> #f)

> |  |  | = |  | #f

Similar to make-input-port, but if the given read-in returns an event, the event’s value must be 0. The resulting port’s peek operation is implemented automatically (in terms of read-in) in a way that can handle special non-byte values. The progress-event and commit operations are also implemented automatically. The resulting port is thread-safe, but not kill-safe (i.e., if a thread is terminated or suspended while using the port, the port may become damaged).

The read-in, close, get-location, count-lines!, init-position, and buffer-mode procedures are the same as for make-input-port.

The fast-peek argument can be either #f or a procedure of three arguments: a byte string to receive a peek, a skip count, and a procedure of two arguments. The fast-peek procedure can either implement the requested peek, or it can dispatch to its third argument to implement the peek. The fast-peek is not used when a peek request has an associated progress event.

The buffering? argument determines whether read-in can be called to read more characters than are immediately demanded by the user of the new port. If buffer-mode is not #f, then buffering? determines the initial buffer mode, and buffering? is enabled after a buffering change only if the new mode is 'block.

If on-consumed is not #f, it is called when data is read (or committed) from the port, as opposed to merely peeked. The argument to on-consumed is the result value of the port’s reading procedure, so it can be an integer or any result from read-in.

> > procedure

> > (make-limited-input-port |  | in |  |  |  |
> > |  | limit |  |  |  |
> > | [ | close-orig?]) |  | → |  | input-port?

> in : input-port?
> limit : exact-nonnegative-integer?
> close-orig? : any/c = #t

Returns a port whose content is drawn from in, but where an end-of-file is reported after limit bytes (and non-byte special values) have been read. If close-orig? is true, then the original port is closed if the returned port is closed.

Bytes are consumed from in only when they are consumed from the returned port. In particular, peeking into the returned port peeks into the original port.

If in is used directly while the resulting port is also used, then the limit bytes provided by the port need not be contiguous parts of the original port’s stream.

> > procedure

> > (make-pipe-with-specials | [ | limit |  |  |  |
> > |  | in-name |  |  |  |

> > out-name])

> > →

> > input-port? |  | output-port?

> limit : exact-nonnegative-integer? = #f
> in-name : any/c = 'pipe
> out-name : any/c = 'pipe

Returns two ports: an input port and an output port. The ports behave like those returned by make-pipe, except that the ports support non-byte values written with procedures such as write-special and read with procedures such as get-byte-or-special.

The limit argument determines the maximum capacity of the pipe in bytes, but this limit is disabled if special values are written to the pipe before limit is reached. The limit is re-enabled after the special value is read from the pipe.

The optional in-name and out-name arguments determine the names of the result ports.

> > procedure

> > (combine-output a-out b-out) → output-port?

> a-out : output-port?
> b-out : output-port?

Accepts two output ports and returns a new output port combining the original ports. When written to, the combined port first writes as many bytes as possible to a-out, and then tries to write the same number of bytes to b-out. If that doesn’t succeed, what is left over is buffered and no further writes can go through until the ports are evened out. The port is ready (for the purposes of synchronization) when each port reports being ready. However, the first port may stop being ready while waiting on the second port to sync, so it cannot be guaranteed that both ports are ready at once. Closing the combined port is done after writing all remaining bytes to b-out.

Added in version 7.7.0.10 of package base.

> > procedure

> > (merge-input a-in b-in [buffer-limit]) → input-port?

> a-in : input-port?
> b-in : input-port?
> buffer-limit : (or/c exact-nonnegative-integer? #f) = 4096

Accepts two input ports and returns a new input port. The new port merges the data from two original ports, so data can be read from the new port whenever it is available from either of the two original ports. The data from the original ports are interleaved. When an end-of-file has been read from an original port, it no longer contributes characters to the new port. After an end-of-file has been read from both original ports, the new port returns end-of-file. Closing the merged port does not close the original ports.

The optional buffer-limit argument limits the number of bytes to be buffered from a-in and b-in, so that the merge process does not advance arbitrarily beyond the rate of consumption of the merged data. A #f value disables the limit. As for make-pipe-with-specials, buffer-limit does not apply when a special value is produced by one of the input ports before the limit is reached.

See also input-port-append, which concatenates input streams instead of interleaving them.

> > procedure

> > (open-output-nowhere [name special-ok?]) → output-port?

> name : any/c = 'nowhere
> special-ok? : any/c = #t

Creates and returns an output port that discards all output sent to it (without blocking). The name argument is used as the port’s name. If the special-ok? argument is true, then the resulting port supports write-special, otherwise it does not.

> > procedure

> > (peeking-input-port |  | in |  |  |  |
> > | [ | name |  |  |  |
> > |  | skip |  |  |  |
> > |  | #:init-position init-position]) |  | → |  | input-port

> in : input-port?
> name : any/c = (object-name in)
> skip : exact-nonnegative-integer? = 0
> init-position : exact-positive-integer? = 1

Returns an input port whose content is determined by peeking into in. In other words, the resulting port contains an internal skip count, and each read of the port peeks into in with the internal skip count, and then increments the skip count according to the amount of data successfully peeked.

The optional name argument is the name of the resulting port. The skip argument is the port initial skip count, and it defaults to 0.

The resulting port’s initial position (as reported by file-position) is (- init-position 1), no matter the position of in.

The resulting port supports buffering, and a 'block buffer mode allows the port to peek further into in than requested. The resulting port’s initial buffer mode is 'block, unless in supports buffer mode and its mode is initially 'none (i.e., the initial buffer mode is taken from in when it supports buffering). If in supports buffering, adjusting the resulting port’s buffer mode via file-stream-buffer-mode adjusts in’s buffer mode.

For example, when you read from a peeking port, you see the same answers as when you read from the original port:

Examples:

> > (define an-original-port (open-input-string "123456789"))
> > (define a-peeking-port (peeking-input-port an-original-port))
> > (file-stream-buffer-mode a-peeking-port 'none)
> > (read-string 3 a-peeking-port)
> "123"
> > (read-string 3 an-original-port)
> "123"

Beware that the read from the original port is invisible to the peeking port, which keeps its own separate internal counter, and thus interleaving reads on the two ports can produce confusing results. Continuing the example before, if we read three more characters from the peeking port, we end up skipping over the 456 in the port (but only because we disabled buffering above):

Example:

> > (read-string 3 a-peeking-port)
> "789"

If we had left the buffer mode of a-peeking-port alone, that last read-string would have likely produced "456" as a result of buffering bytes from an-original-port earlier.

Changed in version 6.1.0.3 of package base: Enabled buffering and buffer-mode adjustments via file-stream-buffer-mode, and set the port’s initial buffer mode to that of in.

> > procedure

> > (reencode-input-port |  | in |  |  |  |
> > |  | encoding |  |  |  |
> > | [ | error-bytes |  |  |  |
> > |  | close? |  |  |  |
> > |  | name |  |  |  |
> > |  | convert-newlines? |  |  |  |
> > |  | enc-error]) |  | → |  | input-port?

> in : input-port?
> encoding : string?
> error-bytes : (or/c #f bytes?) = #f
> close? : any/c = #f
> name : any/c = (object-name in)
> convert-newlines? : any/c = #f

> | enc-error |  | : |  | (string? input-port? . -> . any)
> |  |  | = |  | (lambda (msg port) (error ...))

Produces an input port that draws bytes from in, but converts the byte stream using (bytes-open-converter encoding-str "UTF-8"). In addition, if convert-newlines? is true, then decoded sequences that correspond to UTF-8 encodings of "\r\n", "\r\u0085", "\r", "\u0085", and "\u2028" are all converted to the UTF-8 encoding of "\n".

If error-bytes is provided and not #f, then the given byte sequence is used in place of bytes from in that trigger conversion errors. Otherwise, if a conversion is encountered, enc-error is called, which must raise an exception.

If close? is true, then closing the result input port also closes in. The name argument is used as the name of the result input port.

In non-buffered mode, the resulting input port attempts to draw bytes from in only as needed to satisfy requests. Toward that end, the input port assumes that at least n bytes must be read to satisfy a request for n bytes. (This is true even if the port has already drawn some bytes, as long as those bytes form an incomplete encoding sequence.)

> > procedure

> > (reencode-output-port |  | out |  |  |  |
> > |  | encoding |  |  |  |
> > | [ | error-bytes |  |  |  |
> > |  | close? |  |  |  |
> > |  | name |  |  |  |
> > |  | newline-bytes |  |  |  |
> > |  | enc-error]) |  | → |  | output-port?

> out : output-port?
> encoding : string?
> error-bytes : (or/c #f bytes?) = #f
> close? : any/c = #f
> name : any/c = (object-name out)
> newline-bytes : (or/c #f bytes?) = #f

> | enc-error |  | : |  | (string? output-port? . -> . any)
> |  |  | = |  | (lambda (msg port) (error ...))

Produces an output port that directs bytes to out, but converts its byte stream using (bytes-open-converter "UTF-8" encoding-str). In addition, if newline-bytes is not #f, then bytes written to the port that are the UTF-8 encoding of "\n" are first converted to newline-bytes (before applying the convert from UTF-8 to encoding-str).

If error-bytes is provided and not #f, then the given byte sequence is used in place of bytes that have been sent to the output port and that trigger conversion errors. Otherwise, enc-error is called, which must raise an exception.

If close? is true, then closing the result output port also closes out. The name argument is used as the name of the result output port.

The resulting port supports buffering, and the initial buffer mode is (or (file-stream-buffer-mode out) 'block). In 'block mode, the port’s buffer is flushed only when it is full or a flush is requested explicitly. In 'line mode, the buffer is flushed whenever a newline or carriage-return byte is written to the port. In 'none mode, the port’s buffer is flushed after every write. Implicit flushes for 'line or 'none leave bytes in the buffer when they are part of an incomplete encoding sequence.

The resulting output port does not support atomic writes. An explicit flush or special-write to the output port can hang if the most recently written bytes form an incomplete encoding sequence.

When the port is buffered, a flush callback is registered with the current plumber to flush the buffer.

> > procedure

> > (dup-input-port in [close?]) → input-port?

> in : input-port?
> close? : any/c = #f

Returns an input port that draws directly from in. Closing the resulting port closes in only if close? is #t.

The new port is initialized with the port read handler of in, but setting the handler on the result port does not affect reading directly from in.

> > procedure

> > (dup-output-port out [close?]) → output-port?

> out : output-port?
> close? : any/c = #f

Returns an output port that propagates data directly to out. Closing the resulting port closes out only if close? is #t.

The new port is initialized with the port display handler and port write handler of out, but setting the handlers on the result port does not affect writing directly to out.

> > procedure

> > (relocate-input-port |  | in |  |  |  |
> > |  | line |  |  |  |
> > |  | column |  |  |  |
> > |  | position |  |  |  |
> > | [ | close?] |  |  |  |
> > |  | #:name name) |  | → |  | input-port?

> in : input-port?
> line : (or/c exact-positive-integer? #f)
> column : (or/c exact-nonnegative-integer? #f)
> position : exact-positive-integer?
> close? : any/c = #t
> name : (object-name out)

Produces an input port that is equivalent to in except in how it reports location information (and possibly its name). The resulting port’s content starts with the remaining content of in, and it starts at the given line, column, and position. A #f for the line or column means that the line and column will always be reported as #f.

The line and column values are used only if line counting is enabled for in and for the resulting port, typically through port-count-lines!. The column value determines the column for the first line (i.e., the one numbered line), and later lines start at column 0. The given position is used even if line counting is not enabled.

When line counting is on for the resulting port, reading from in instead of the resulting port increments location reports from the resulting port. Otherwise, the resulting port’s position does not increment when data is read from in.

If close? is true, then closing the resulting port also closes in. If close? is #f, then closing the resulting port does not close in.

The name argument is used as the name for the resulting port; the default value keeps the same name as in.

> > procedure

> > (relocate-output-port |  | out |  |  |  |
> > |  | line |  |  |  |
> > |  | column |  |  |  |
> > |  | position |  |  |  |
> > | [ | close?] |  |  |  |
> > |  | #:name name) |  | → |  | output-port?

> out : output-port?
> line : (or/c exact-positive-integer? #f)
> column : (or/c exact-nonnegative-integer? #f)
> position : exact-positive-integer?
> close? : any/c = #t
> name : (object-name out)

Like relocate-input-port, but for output ports.

> > procedure

> > (transplant-input-port |  | in |  |  |  |
> > |  | get-location |  |  |  |
> > |  | init-pos |  |  |  |
> > | [ | close? |  |  |  |
> > |  | count-lines!] |  |  |  |
> > |  | #:name name) |  | → |  | input-port?

> in : input-port?

> get-location

> :

> (or/c
> (->
> (values
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)
> (or/c exact-positive-integer? #f)))
> #f)

> init-pos : exact-positive-integer?
> close? : any/c = #t
> count-lines! : (-> any) = void
> name : (object-name out)

Like relocate-input-port, except that arbitrary position information can be produced (when line counting is enabled) via get-location, which is used as for make-input-port. If get-location is #f, then the port counts lines in the usual way starting from init-pos, independent of locations reported by in.

If count-lines! is supplied, it is called when line counting is enabled for the resulting port. The default is void.

> > procedure

> > (transplant-output-port |  | out |  |  |  |
> > |  | get-location |  |  |  |
> > |  | init-pos |  |  |  |
> > | [ | close? |  |  |  |
> > |  | count-lines!] |  |  |  |
> > |  | #:name name) |  | → |  | output-port?

> out : output-port?

> get-location

> :

> (or/c
> (->
> (values
> (or/c exact-positive-integer? #f)
> (or/c exact-nonnegative-integer? #f)
> (or/c exact-positive-integer? #f)))
> #f)

> init-pos : exact-positive-integer?
> close? : any/c = #t
> count-lines! : (-> any) = void
> name : (object-name out)

Like transplant-input-port, but for output ports.

> > procedure

> > (filter-read-input-port |  | in |  |  |  |
> > |  | read-wrap |  |  |  |
> > |  | peek-wrap |  |  |  |
> > | [ | close?]) |  | → |  | input-port?

> in : input-port?

> read-wrap

> :

> (bytes? (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?)
> . -> .
> (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?))

> peek-wrap

> :

> (bytes? exact-nonnegative-integer? (or/c evt? #f)
> (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f)
> . -> . (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?
> #f))

> close? : any/c = #t

Creates a port that draws from in, but each result from the port’s read and peek procedures (in the sense of make-input-port) is filtered by read-wrap and peek-wrap. The filtering procedures each receive both the arguments and results of the read and peek procedures on in for each call.

If close? is true, then closing the resulting port also closes in.

> > procedure

> > (special-filter-input-port in proc [close?]) → input-port?

> in : input-port?

> proc

> :

> (procedure? bytes? . -> . (or/c exact-nonnegative-integer?
> eof-object?
> procedure?
> evt?))

> close? : any/c = #t

Produces an input port that is equivalent to in, except that when in produces a procedure to access a special value, proc is applied to the procedure to allow the special value to be replaced with an alternative. The proc is called with the special-value procedure and the byte string that was given to the port’s read or peek function (see make-input-port), and the result is used as the read or peek function’s result. The proc can modify the byte string to substitute a byte for the special value, but the byte string is guaranteed only to hold at least one byte.

If close? is true, then closing the resulting input port also closes in.

##### 13.1.10.3`` Port Events

> > procedure

> > (eof-evt in) → evt?

> in : input-port?

Returns a synchronizable event that is ready when in produces an eof. If in produces a mid-stream eof, the eof is consumed by the event only if the event is chosen in a synchronization.

If attempting to read from in raises an exception during a synchronization attempt, then the exception may be reported during the synchronization attempt, but it will silently discarded if some another event in the same synchronization is selected or if some other event raises an exception first.

Changed in version 7.5.0.3 of package base: Changed handling of read errors so they are propagated to a synchronization attempt, instead of treated as unhandled errors in a background thread.

> > procedure

> > (read-bytes-evt k in) → evt?

> k : exact-nonnegative-integer?
> in : input-port?

Returns a synchronizable event that is ready when k bytes can be read from in, or when an end-of-file is encountered in in. If k is 0, then the event is ready immediately with "". For non-zero k, if no bytes are available before an end-of-file, the event’s result is eof. Otherwise, the event’s result is a byte string of up to k bytes, which contains as many bytes as are available (up to k) before an available end-of-file. (The result is a byte string on less than k bytes only when an end-of-file is encountered.)

Bytes are read from the port if and only if the event is chosen in a synchronization, and the returned bytes always represent contiguous bytes in the port’s stream.

The event can be synchronized multiple times—event concurrently—and each synchronization corresponds to a distinct read request.

The in must support progress events, and it must not produce a special non-byte value during the read attempt.

Exceptions attempting to read from in are handled in the same way as by eof-evt.

> > procedure

> > (read-bytes!-evt bstr in) → evt?

> bstr : (and/c bytes? (not/c immutable?))
> in : input-port?

Like read-bytes-evt, except that the read bytes are placed into bstr, and the number of bytes to read corresponds to (bytes-length bstr). The event’s result is either eof or the number of read bytes.

The bstr may be mutated any time after the first synchronization attempt on the event and until either the event is selected, a non-#f progress-evt is ready, or the current custodian (at the time of synchronization) is shut down. Note that there is no time bound otherwise on when bstr might be mutated if the event is not selected by a synchronzation; nevertheless, multiple synchronization attempts can use the same result from read-bytes!-evt as long as there is no intervening read on in until one of the synchronization attempts selects the event.

Exceptions attempting to read from in are handled in the same way as by eof-evt.

> > procedure

> > (read-bytes-avail!-evt bstr in) → evt?

> bstr : (and/c bytes? (not/c immutable?))
> in : input-port?

Like read-bytes!-evt, except that the event reads only as many bytes as are immediately available, after at least one byte or one eof becomes available.

> > procedure

> > (read-string-evt k in) → evt?

> k : exact-nonnegative-integer?
> in : input-port?

Like read-bytes-evt, but for character strings instead of byte strings.

> > procedure

> > (read-string!-evt str in) → evt?

> str : (and/c string? (not/c immutable?))
> in : input-port?

Like read-bytes!-evt, but for a character string instead of a byte string.

> > procedure

> > (read-line-evt in [mode]) → evt?

> in : input-port?

> | mode |  | : |  | (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
> |  |  | = |  | 'linefeed

Returns a synchronizable event that is ready when a line of characters or end-of-file can be read from in. The meaning of mode is the same as for read-line. The event result is the read line of characters (not including the line separator).

A line is read from the port if and only if the event is chosen in a synchronization, and the returned line always represents contiguous bytes in the port’s stream.

Exceptions attempting to read from in are handled in the same way as by eof-evt.

> > procedure

> > (read-bytes-line-evt in [mode]) → evt?

> in : input-port?

> | mode |  | : |  | (or/c 'linefeed 'return 'return-linefeed 'any 'any-one)
> |  |  | = |  | 'linefeed

Like read-line-evt, but returns a byte string instead of a string.

> > procedure

> > (peek-bytes-evt k skip progress-evt in) → evt?

> k : exact-nonnegative-integer?
> skip : exact-nonnegative-integer?
> progress-evt : (or/c progress-evt? #f)
> in : input-port?
> (peek-bytes!-evt bstr skip progress-evt in) → evt?
> bstr : (and/c bytes? (not/c immutable?))
> skip : exact-nonnegative-integer?
> progress-evt : (or/c progress-evt? #f)
> in : input-port?

> (peek-bytes-avail!-evt |  | bstr |  |  |  |
> |  | skip |  |  |  |
> |  | progress-evt |  |  |  |
> |  | in) |  | → |  | evt?

> bstr : (and/c bytes? (not/c immutable?))
> skip : exact-nonnegative-integer?
> progress-evt : (or/c progress-evt? #f)
> in : input-port?
> (peek-string-evt k skip progress-evt in) → evt?
> k : exact-nonnegative-integer?
> skip : exact-nonnegative-integer?
> progress-evt : (or/c progress-evt? #f)
> in : input-port?
> (peek-string!-evt str skip progress-evt in) → evt?
> str : (and/c string? (not/c immutable?))
> skip : exact-nonnegative-integer?
> progress-evt : (or/c progress-evt? #f)
> in : input-port?

Like the read-bytes-evt, etc., functions, but for peeking. The skip argument indicates the number of bytes to skip, and progress-evt indicates an event that effectively cancels the peek (so that the event never becomes ready). The progress-evt argument can be #f, in which case the event is never canceled.

> > procedure

> > (regexp-match-evt pattern in) → any

> pattern : (or/c string? bytes? regexp? byte-regexp?)
> in : input-port?

Returns a synchronizable event that is ready when pattern matches the stream of bytes/characters from in; see also regexp-match. The event’s value is the result of the match, in the same form as the result of regexp-match.

If pattern does not require a start-of-stream match, then bytes skipped to complete the match are read and discarded when the event is chosen in a synchronization.

Bytes are read from the port if and only if the event is chosen in a synchronization, and the returned match always represents contiguous bytes in the port’s stream. If not-yet-available bytes from the port might contribute to the match, the event is not ready. Similarly, if pattern begins with a start-of-stream ^ and the pattern does not initially match, then the event cannot become ready until bytes have been read from the port.

The event can be synchronized multiple times—even concurrently—and each synchronization corresponds to a distinct match request.

The in port must support progress events. If in returns a special non-byte value during the match attempt, it is treated like eof.

Exceptions attempting to read from in are handled in the same way as by eof-evt.

##### 13.1.10.4`` Copying Streams

> > procedure

> > (convert-stream |  | from-encoding |  |  |  |
> > |  | in |  |  |  |
> > |  | to-encoding |  |  |  |
> > |  | out) |  | → |  | void?

> from-encoding : string?
> in : input-port?
> to-encoding : string?
> out : output-port?

Reads data from in, converts it using (bytes-open-converter from-encoding to-encoding) and writes the converted bytes to out. The convert-stream procedure returns after reaching eof in in.

If opening the converter fails, the exn:fail exception is raised. Similarly, if a conversion error occurs at any point while reading from in, then exn:fail exception is raised.

> > procedure

> > (copy-port in out ...+) → void?

> in : input-port?
> out : output-port?

Reads data from in and writes it back out to out, returning when in produces eof. The copy is efficient, and it is without significant buffer delays (i.e., a byte that becomes available on in is immediately transferred to out, even if future reads on in must block). If in produces a special non-byte value, it is transferred to out using write-special.

This function is often called from a “background” thread to continuously pump data from one stream to another.

If multiple outs are provided, data from in is written to every out. The different outs block output to each other, because each block of data read from in is written completely to one out before moving to the next out. The outs are written in the provided order, so non-blocking ports (e.g., file output ports) should be placed first in the argument list.

top ← prev up next →