ServerJS/API/io/ProposalK

This module and the file module in this proposal are a hybrid of mostly the Ruby API melded with Pythonic/Rhinocerous iteration, and liberated of the notion that certain things should be static methods as opposed to simply hosted by the module.

/**
*/

/*** Io
    - :is:`iter#Iterable`
*/

/**** input
    - accepts an optional `String` line terminator
    - accepts an optional `String` encoding module identifier
    - returns a `String` decoded from reading
*/

/**** print
    - accepts a `String` to encode and write
    - accepts an optional `String` line terminator
    - accepts an optional `String` encoding module identifier
*/

/**** read
    - accepts a maximum `Number` of bytes to read.
    - returns a `Binary` of however many bytes were actually read.
*/

/**** write
    - returns a `Number` of however many bytes were actually
      written.
*/

/**** readNonblock
    - accepts a maximum `Number` of bytes to read.
    - returns a `Binary` of however many bytes were read without
      blocking.
*/

/**** writeNonblock
    - accepts a `Binary` of bytes to write.
    - returns a `Number` of however many bytes were actually
      written without blocking.
*/

/**** isEof
    returns whether the read/write head is at or beyond the
    end of the stream.
*/

/**** iter
    an alias for `linesIter`
*/

/**** linesIter
    - accepts an optional `String` line terminator
    - accepts an optional `String` encoding module identifier
    returns an iteration on lines (`String`) of the stream.
*/

/**** charsIter
    - accepts an optional `String` encoding module identifier
    returns an iteration of characters (`String`) of the stream.
*/

/**** bytesIter
    returns an iteration on bytes (`Binary`) of the stream.
*/

/**** fcntl
*/

/**** getFileNo
    returns an integer `Number` for the process stream number
    that the IO object is attached to.
*/

/**** toNumber
    an alias for `getFileNo`
*/

/**** getLineNo
    returns the current "line" number from the file.
    updated on read.
*/

/**** isTty
    returns whether the stream is attached to a
    terminal device, a teletype, ``tty``.
*/

/**** getPos
    get the current byte offset of the
    read/write head in the stream.
*/

/**** setPos
    set the current byte offset of the
    read/write head in the stream.
*/

/**** rewind
    Equivalent to ``setPos(0)``
*/

/**** seek
    Seeks to a given integer `Number` offset in the
    stream relative to a given position:

    Accepts:

    - ``offset``, an integer `Number`
    - ``whence``, an enumerated integer `Number` supplied
      by one of the following constants.
    
    Whence:

      ========  ==================================
      SEEK_CUR  Seeks to current position
                plus ``offset``

      SEEK_END  Seeks to the end of the stream
                plus ``offset``, usually negative.

      SEEK_SET  Seeks to the beginning of the
                stream plus ``offset``
      ========  ==================================


    Example::

        var file = require('file');
        var io = require('io');
        var f = file.File("testfile", "utf-8");
        f.seek(-13, io.SEEK_END);
        var line = f.input()
        
*/

/**** stat
*/

/**** select
*/

/**** fsync
*/

/**** ioctl
*/