Fsdb::Filter - base class for Fsdb filters
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.
info
$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.
$filter->post_new();
Called when the subclass is done with new, giving Fsdb::Filter a chance to autorun.
$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.
$filter->set_default_tmpdir
Figure out a tmpdir, from environment variables if necessary.
$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:
Enable debugging output.
Read from InputSource, typically a file name, or - for standard input, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
-
Write to OutputDestination, typically a file name, or - for standard output, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue objects.
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.
--(no)autorun
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.)
--noclose
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.)
$OUT_REF
Show help.
Show full manual.
$self->parse_target_column(\@argv);
A helper function: allow one column to be specified as the _target_column.
_target_column
$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.
$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}.
$fsdb_io = $filter->parse_io_option($io_direction, $option_name, $target);
This helper function handles --input or --output options, without doing any setup.
--input
--output
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.
finish_io_option
$IO_DIRECTION is usually input or output, but it can also be inputs (with an "s") when multiple input sources are allowed.
$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.
$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).
$self-
_out
@_ins
$IO_DIRECTION must be "input", "inputs" or "output".
No return value.
$fh = direction_to_stdio($direction)
Private internal routing. Give a filehandle for STDIN or STDOUT based on $DIRECTION == 'input or 'output'
$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).
This function does no IO.
$filter->setup();
Do any setup that requires minimal IO (for example, reading and parsing headers).
Called exactly once.
$filter->run();
Execute the body, typically iterating over the input rows.
$log = $filter->figure_program_log();
Compute and return the log entry for a program.
$filter->finish();
Write out any trailing comments and close output.
$filter->setup_run_finish();
Shorthand for doing everything needed to run a command straightaway.
$filter->info($INFOTYPE)
Return information about what the filter does. Infotypes:
Filter has some class-specific utility routines in it. (I.e., they know about $self.)
$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}>.
Fsdb::IO::Readers
-comment_handler
$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.)
$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.
$self->{_out}
$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.
$A_FSDB
$B_FSDB
$a
$b
$A_FREF_NAME
$B_FREF_NAME
Returns undef if there are no fields in $self-{_sort_argv}>.
$out = $self->numeric_formatting($x)
Display a floating point number $x using $self->{_format}, handling possible non-numeric "-" as a special case.
$self->setup_exactly_two_inputs
Ensure that there are exactly two input streams. Common to dbmerge and dbjoin.
Filter also has some utility routines that are not part of the class structure. They are not exported.
(none currently)
To install Fsdb, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Fsdb
CPAN shell
perl -MCPAN -e shell install Fsdb
For more information on module installation, please visit the detailed CPAN module installation guide.