Fsdb::Filter(3)

NAME
Fsdb::Filter - base class for Fsdb filters

DESCRIPTION
Fsdb::Filter is the virtual base class for Fsdb filters.

Users will typically invoke individual programs via the command line (for example, see dbcol(1)) or string together several in a Perl program as described in dbpipeline(3).

For new Filter developers, internal processing is:

    new
        set_defaults
        parse_options
        autorun if desired
    parse_options   # optionally called additional times
    setup           # does IO on header
    run             # does IO on data
    finish          # any shutdown

In addition, the "info" method returns metadata about a given filter.

FUNCTIONS

  new
    $fsdb = new Fsdb::Filter;

Create a new filter object, calling set_defaults and parse_options. A user program will call a specific filter (say Fsdb::Filter::dbcol) to do processing. See also dbpipeline for aliases that remove the wordiness.

  post_new
    $filter->post_new();

Called when the subclass is done with new, giving Fsdb::Filter a chance to autorun.

  set_defaults
    $filter->set_defaults();

Set up object defaults. Called once during new.

Fsdb::Filter::set_defaults does some general setup, tracking module invocation and preparing for one input and output stream.

  set_default_tmpdir
    $filter->set_default_tmpdir

Figure out a tmpdir, from environment variables if necessary.

  parse_options
    $filter->parse_options(@ARGV);

Parse_options is called one or more times to parse ARGV-style options. It should not do any IO or any irreverssable actions; defer those to startup.

Fsdb::Filter::parse_options does no work; the subclass is expected to call Fsdb::Filter::get_options() for all arguments.

Most modules implement certain common fsdb options, listed below.

This module also supports the standard fsdb options:

-d  Enable debugging output.

-i or --input InputSource
    Read from InputSource, typically a file name, or "-" for standard input, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

-o or --output OutputDestination
    Write to OutputDestination, typically a file name, or "-" for standard output, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.

--autorun or --noautorun
    By default, programs process automatically, but Fsdb::Filter objects in Perl do not run until you invoke the run() method. The "--(no)autorun" option controls that behavior within Perl.

--noclose
    By default, programs close their output when done. For some cases where objects are used internally, "--noclose" may be used to leave output open for further I/O. (This option is only supported by some filters.)

--saveoutput $OUT_REF
    By default, programs close their output when done. With this option, programs in Perl can have a subprogram create an output refrence and return it to the caller in $OUT_REF. The caller can then use it for further I/O. (This option is only supported by some filters.)

--help
    Show help.

--man
    Show full manual.

  parse_target_column
    $self->parse_target_column(\@argv);

A helper function: allow one column to be specified as the "_target_column".

  get_options
    $success = $filter->get_options(\@argv, "v+" => \$verbose, ...)

get_options is just like Getopt::Long's GetOptions, but takes the argument list as the first argument. This list is modified and any non-options are returned. It also saves _orig_argv in itself.

  parse_sort_option
    $fsdb_io = $filter->parse_sort_option($option_name, $target);

This helper function handles sorting options and column names as described in dbsort(1). We normalize long sort options to unbundled short options and accumulate them in $self->{_sort_argv}.

  parse_io_option
    $fsdb_io = $filter->parse_io_option($io_direction, $option_name, $target);

This helper function handles "--input" or "--output" options, without doing any setup.

It fills in $self->{_$IO_DIRECTION} with the resulting object, which is either a file handle or Fsdb::Filter::Piepline object, and expects "finish_io_option" to convert this token into a full Fsdb::IO object.

$IO_DIRECTION is usually input or output, but it can also be inputs (with an "s") when multiple input sources are allowed.

  finish_one_io_option
    $fsdb_io = $filter->finish_io_option($io_direction, $token, @fsdb_args);

This helper function finishes setting up a Fsdb::IO object in $IO_DIRECTION, using $TOKEN as information. using @FSDB_ARGS as parameters. It creates the actual Fsdb::IO objects, opens the files (or whatever), and reads the headers. It returns the $FSDB_IO option.

$IO_DIRECTION must be "input" or "output".

Since it does IO, finish_io_option should only be called from setup, not parse_options.

Can be called once per IO stream.

  finish_io_option
    $filter->finish_io_option($io_direction, @fsdb_args);

This helper function finishes setting up a Fsdb::IO object in $IO_DIRECTION, using @FSDB_ARGS as parameters. It creates the actual Fsdb::IO objects, opens the files (or whatever), and reads the headers. the resulting Fsdb::IO objects are built from "$self-"{_$IO_DIRECTION}> and are left in "$self-"{_in}> or ("_out" or @_ins).

$IO_DIRECTION must be "input", "inputs" or "output".

Since it does IO, finish_io_option should only be called from setup, not parse_options.

Can be called once per IO stream.

No return value.

  direction_to_stdio
    $fh = direction_to_stdio($direction)

Private internal routing. Give a filehandle for STDIN or STDOUT based on $DIRECTION == 'input or 'output'

  finish_fh_io_option
    $filter->finish_fh_io_option($io_direction);

This helper function creates a filehandle in $IO_DIRECTION. Compare to finish_io_option which creates a Fsdb::IO object. It creates the actual IO::File objects, opens the files (or whatever). The filehandle is built from "$self-"{_$IO_DIRECTION}> and are left in "$self-"{_in}> or ("_out").

$IO_DIRECTION must be "input" or "output".

This function does no IO.

No return value.

  setup
    $filter->setup();

Do any setup that requires minimal IO (for example, reading and parsing headers).

Called exactly once.

  run
    $filter->run();

Execute the body, typically iterating over the input rows.

Called exactly once.

  compute_program_log
    $log = $filter->figure_program_log();

Compute and return the log entry for a program.

  finish
    $filter->finish();

Write out any trailing comments and close output.

  setup_run_finish
    $filter->setup_run_finish();

Shorthand for doing everything needed to run a command straightaway.

  info
    $filter->info($INFOTYPE)

Return information about what the filter does. Infotypes:

input_type Types of input accepted. Raw types are: "fsdbtext", "fsdbobj", "fsdb*", "text", or "none".
output_type Type of output produced. Same format as input_type.
input_count Number of input streams (usually 1).
output_count Number of input streams (usually 1).

CLASS-SPECIFIC UTILITY ROUTINES
Filter has some class-specific utility routines in it. (I.e., they know about $self.)

  create_pass_comments_sub
    $filter->create_pass_comments_sub
or
    $filter->create_pass_comments_sub('_VALUE');

Creates a code block suitable for passing to "Fsdb::IO::Readers" "-comment_handler" that passes comments through to "$self-"{_out}>. Or with the optional argument, through "$self-"{_VALUE}>.

  create_tolerant_pass_comments_sub
    $filter->create_tolerant_pass_comments_sub
or
    $filter->create_tolerant_pass_comments_sub('_VALUE');

Like "$self-"create_pass_comments_sub>, but this version tolerates the output not being opened. In those cases, comments are discarded. Warning: use carefully to guarantee consistent results.

A symptom requiring tolerance is to get an error like "Can't call method "write_raw" on an undefined value at /usr/lib/perl5/vendor_perl/5.10.0/Fsdb/Filter.pm line 678." (which will be the sub create_pass_comments_sub ($;$) line in create_pass_comments.)

  create_delay_comments_sub
    $filter->create_delay_comments_sub($optional_value);

Creates a code block suitable for passing to Fsdb::IO::Readers -comment_handler that will buffer comments for automatic (from $self->final) after all other IO. No output occurs until finish() is called, at which time "$self->{_out}" must be a live Fsdb object.

  create_compare_code
    $filter->create_compare_code($a_fsdb, $b_fsdb, $a_fref_name, $b_fref_name).

Write compare code based on sort-style options stored in "$self-"{_sort_argv}>. $A_FSDB and $B_FSDB are the Fsdb::IO object that defines the schemas for the two objects. We assume the variables $a and $b point to arefs; these names can be overridden by specifying $A_FREF_NAME and $B_FREF_NAME.

Returns undef if there are no fields in "$self-"{_sort_argv}>.

  numeric_formatting
    $out = $self->numeric_formatting($x)

Display a floating point number $x using $self->{_format}, handling possible non-numeric "-" as a special case.

  setup_exactly_two_inputs
    $self->setup_exactly_two_inputs

Ensure that there are exactly two input streams. Common to dbmerge and dbjoin.

NON-CLASS UTILITY ROUTINES
Filter also has some utility routines that are not part of the class structure. They are not exported.

(none currently)