Fsdb::IO::Reader(3)

NAME
Fsdb::IO::Reader - handle formatting reading from a fsdb file (handle) or queue

SAMPLE CODE
Sample code reading an input stream:

    $in = new Fsdb::IO::Reader(-file => '-');
    $in->error and die "cannot open stdin as fsdb: " . $in->error . "\n";
    my @arow;
    while ($in->read_row_to_aref(\@arow) {
        # do something
    };
    $in->close;

METHODS

  new
    $fsdb = new Fsdb::IO::Reader(-file => $filename);
    $fsdb = new Fsdb::IO::Reader(-header => "#fsdb -F t foo bar", -fh => $file_handle);

Creates a new reader object from FILENAME. (FILENAME can also be a IO::Handle object, or an hdfs: file.) Always succeeds, but check the "error" method to test for failure.

Options:

other options See also the options in Fsdb::IO, including "-file", "-header".
-file FILENAME Open and read the given filename. Special filename "-" is standard input, and files with hdfs: are read from Hadoop (but not with directory aggregation).
-comment_handler $ref
    Define how comments are handled. If $REF is a Fsdb::IO::Writer object, comments are written to that stream as they are encountered. if $REF is a ref to a scalar, then we assume that scalar will be filled in with a Fsdb::IO::Writer object later and treat it the same. If it is of type code, then it is assumed to be a callback function of the form:

        sub comment_handler ($) { my $comment = @_; }

    where the one argument will be a string with the unparsed comment (with leading # and trailing newline).

    By default, or if $ref is undef, comments are consumed.

    A typical handler if you have an output Fsdb stream is:

        sub { $out->write_raw(@_); };

    (That is the code created by Fsdb::Filter::create_pass_comments_sub.)

    There are several support routines to handle comments in a pipeline; see Fsdb::Filter::create_pass_comments_sub, Fsdb::Filter::create_tolerant_pass_comments_sub, Fsdb::Filter::create_delay_comments_sub.

User-specified -header arguments override a header provided in the input source.

  config_one
documented in new

  comment_handler_to_sub;
internal use only: parses and sets up the comment handle callback. (At input, _comment_sub is as given by -comment_handler, but at exit it is always an anon function.

  _enable_compression
    $self->_enable_compression

internal use only: switch from uncompressed to compressed.

  create_io_subs
    $self->create_io_subs()

internal use only: create a thunk that returns rowobjs.

  read_headerrow
internal use only; reads the header

  read_rowobj
    $rowobj = $fsdb->read_rowobj;

Reads a line of input and returns a "row object", either a scalar string for a comment or header, or an array reference for a row, or undef on end-of-stream. This routine is the fastest way to do full-featured fsdb-formatted IO. (Although see also Fsdb::Reader::fastpath_sub.)

Unlike all the other routines (including fastpath_sub), read_rowobj does not do comment processing (calling comment_sub).

  read_row_to_aref
    $fsdb->read_row_to_aref(\@a);

Then $a[0] is the 0th column, etc. Returns undef if the read fails, typically due to EOF.

  unread_rowobj
    $fsdb->unread_rowobj($fref)

Put an fref back into the stream.

  unread_row_from_aref
    $fsdb->unread_row_from_aref(\@a);

Put array @a back into the file.

  read_row_to_href
    $fsdb->read_row_to_href(\%h);

Read the next row into hash %h. Then $h{'colname'} is the value of that column. Returns undef if the read fails, typically due to EOF.

  unread_row_from_href
    $fsdb->unread_row_from_href(\%h);

Put hash %h back into the file.

  fastpath_ok
    $fsdb->fastpath_ok();

Check if we can do fast-path IO (post-header, no pending unread rows, no errors).

  fastpath_sub
    $sub = $fsdb->fastpath_sub()
    $row_aref = &$sub();

Return an anonymous sub that does read fast-path when called. This code stub returns a new $aref corresponding with a data line, and handles comments as specified by -comment_handler