Handle Type

Handles are the entities through which Idio performs input and output.

A handle is opaque about its implementation although there are several flavours. There are the obvious File Handles and a similar form, Pipe Handles. File and pipe handles can be abstracted to FD Handles (file descriptor handles).

There are also String Handles which are useful for pseudo I/O, capturing output or creating strings.

You cannot open handles directly but must use a file, pipe or string handle creation method.

Ordinarily you might simply cease using a handle and have it collected by the GC in due course but in the case of all forms of FD handles you may want to be more careful in ensuring you do not retain a reference to them as otherwise the GC cannot collect the handle and close the file descriptor.

Idio has no defence against you using up limited resources unwisely.

Handle Predicates

function handle? o

test if o is a handle

Param o:

object to test

Return:

#t if o is a handle, #f otherwise

Rtype:

boolean

function input-handle? o

test if o is an input handle

Param o:

object to test

Return:

#t if o is an input handle, #f otherwise

Rtype:

boolean

function output-handle? o

test if o is an output handle

Param o:

object to test

Return:

#t if o is an output handle, #f otherwise

Rtype:

boolean

function closed-handle? handle

Is handle handle closed?

Param handle:

handle to test

Type handle:

handle

Return:

#t if handle is closed, #f otherwise

Rtype:

boolean

function ready-handle? [handle]

test if handle has input available or is at end-of-file

Param handle:

handle to test, defaults to the current input handle

Type handle:

handle, optional

Return:

#t if handle has input available or is at end-of-file, #f otherwise

Rtype:

boolean

function eof-handle? [handle]

test if handle is not supplied is at end-of-file

Param handle:

handle to test, defaults to the current input handle

Type handle:

handle, optional

Return:

#t if handle is at end-of-file, #f otherwise

Rtype:

boolean

Handle Attributes

function handle-line handle

Return the current line number of handle handle

Param handle:

handle to report on

Type handle:

handle

Return:

line number

Rtype:

integer

The handle’s line can be invalidated by seek-handle.

function handle-pos handle

Return the current position of handle handle

Param handle:

handle to report on

Type handle:

handle

Return:

position

Rtype:

integer

function handle-name handle

return the name associated with handle handle

Param handle:

handle to query

Type handle:

handle

Return:

name

Rtype:

string

function handle-location handle

Return a string representation of the current location in handle handle

name:line number

Param handle:

handle to report on

Type handle:

handle

Return:

handle location

Rtype:

string

The handle’s line can be invalidated by seek-handle.

Handle Functions

function close-handle handle

Close the handle handle

Param handle:

handle to close

Type handle:

handle

Return:

#<unspec>

function close-input-handle handle

Close the input handle handle

Param handle:

handle to close

Type handle:

input handle

Return:

#<unspec>

function close-output-handle handle

Close the output handle handle

Param handle:

handle to close

Type handle:

output handle

Return:

#<unspec>

function read-line [handle]

read a string from handle up to a #\{newline} character

Param handle:

handle to read from, defaults to the current input handle

Type handle:

handle, optional

Return:

string excluding the newline

Rtype:

string

function read-lines [handle]

read from handle up to the end of file

Param handle:

handle to read from, defaults to the current input handle

Type handle:

handle, optional

Return:

string

Rtype:

string

function read-char [handle]

read a UTF-8 encoded character from handle

Param handle:

handle to read from, defaults to the current input handle

Type handle:

handle, optional

Return:

Unicode code point

Rtype:

unicode

function peek-char [handle]

return the next Unicode code point from handle

Param handle:

handle to observe, defaults to the current input handle

Type handle:

handle, optional

Return:

Unicode code point

Rtype:

unicode

function write o [handle]

write the printed representation of o to handle

Param o:

object

Param handle:

handle to write to, defaults to the current output handle

Type handle:

handle, optional

Return:

#<unspec>

function ewrite x

write x to the current error handle

Param x*:

values to print

Return:

#<unspec>

function write-char c [handle]

write a UTF-8 encoded character to handle

Param c:

code point to write

Type c:

unicode

Param handle:

handle to write to, defaults to the current output handle

Type handle:

handle, optional

Return:

#<unspec>

function puts s [handle]

Write the printed form of s to handle

Param s:

string to be printed

Type s:

string

Param handle:

handle to print to, defaults to the current output handle

Type handle:

handle, optional

Return:

the number of bytes written

Rtype:

integer

function seek-handle handle pos [whence]

seek to the given pos in handle

if one of the optional 'set, 'end or 'cur symbols is supplied for whence use the appropriate whence flag

Param handle:

handle to seek in (file or string)

Type handle:

handle

Param pos:

position to seek to

Type pos:

integer

Param whence:

whence flag, defaults to 'set

Type whence:

symbol, optional

Return:

position actually sought to

Rtype:

integer

A successful seek will clear the end-of-file status of the handle.

The handle’s concept of a line number is invalidated unless whence is 'set and position is 0 (zero)

function rewind-handle handle

Seek to position zero of handle

This will reset the handle’s position to zero and the handle’s line number to 1

Param handle:

handle to rewind

Type handle:

handle

Return:

#<unspec>

function flush-handle handle

Invoke the flush method on handle

Param handle:

handle to flush

Type handle:

handle

Return:

#<unspec>

Last built at 2024-05-17T06:10:57Z+0000 from 62cca4c (dev) for Idio 0.3.b.6