.. include:: ../../global.rst .. _`handle type`: 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 :ref:`file handles` and a similar form, :ref:`pipe handles`. File and pipe handles can be abstracted to :ref:`fd handles` (file descriptor handles). There are also :ref:`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. :lname:`Idio` has no defence against you using up limited resources unwisely. Handle Predicates ----------------- .. _`handle?`: .. idio: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 .. _`input-handle?`: .. idio: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 .. _`output-handle?`: .. idio: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 .. _`closed-handle?`: .. idio: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 .. _`ready-handle?`: .. idio: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 .. _`eof-handle?`: .. idio: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 ----------------- .. _`handle-line`: .. idio: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 :ref:`seek-handle `. .. _`handle-pos`: .. idio:function:: handle-pos handle Return the current position of handle `handle` :param handle: handle to report on :type handle: handle :return: position :rtype: integer .. _`handle-name`: .. idio:function:: handle-name handle return the name associated with handle `handle` :param handle: handle to query :type handle: handle :return: name :rtype: string .. _`handle-location`: .. idio:function:: handle-location handle Return a string representation of the current location in handle `handle` :samp:`{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 :ref:`seek-handle `. Handle Functions ---------------- .. _`close-handle`: .. idio:function:: close-handle handle Close the handle `handle` :param handle: handle to close :type handle: handle :return: ``#`` .. _`close-input-handle`: .. idio:function:: close-input-handle handle Close the input handle `handle` :param handle: handle to close :type handle: input handle :return: ``#`` .. _`close-output-handle`: .. idio:function:: close-output-handle handle Close the output handle `handle` :param handle: handle to close :type handle: output handle :return: ``#`` .. _`read-line`: .. idio: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 .. _`read-lines`: .. idio: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 .. _`read-char`: .. idio: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 .. _`peek-char`: .. idio: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 .. _`write`: .. idio: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: ``#`` .. _`ewrite`: .. idio:function:: ewrite x :ref:`write ` `x` to the current error handle :param x*: values to print :return: ``#`` .. _`write-char`: .. idio: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: ``#`` .. _`puts`: .. idio: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 .. _`seek-handle`: .. idio: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) .. _`rewind-handle`: .. idio: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: ``#`` .. _`flush-handle`: .. idio:function:: flush-handle handle Invoke the flush method on `handle` :param handle: handle to flush :type handle: handle :return: ``#`` .. include:: ../../commit.rst