1Fsdb::Filter(3)       User Contributed Perl Documentation      Fsdb::Filter(3)
2
3
4

NAME

6       Fsdb::Filter - base class for Fsdb filters
7

DESCRIPTION

9       Fsdb::Filter is the virtual base class for Fsdb filters.
10
11       Users will typically invoke individual programs via the command line
12       (for example, see dbcol(1)) or string together several in a Perl
13       program as described in dbpipeline(3).
14
15       For new Filter developers, internal processing is:
16
17           new
18               set_defaults
19               parse_options
20               autorun if desired
21           parse_options   # optionally called additional times
22           setup           # does IO on header
23           run             # does IO on data
24           finish          # any shutdown
25
26       In addition, the "info" method returns metadata about a given filter.
27

FUNCTIONS

29   new
30           $fsdb = new Fsdb::Filter;
31
32       Create a new filter object, calling set_defaults and parse_options.  A
33       user program will call a specific filter (say Fsdb::Filter::dbcol) to
34       do processing.  See also dbpipeline for aliases that remove the
35       wordiness.
36
37   post_new
38           $filter->post_new();
39
40       Called when the subclass is done with new, giving Fsdb::Filter a chance
41       to autorun.
42
43   set_defaults
44           $filter->set_defaults();
45
46       Set up object defaults.  Called once during new.
47
48       Fsdb::Filter::set_defaults does some general setup, tracking module
49       invocation and preparing for one input and output stream.
50
51   set_default_tmpdir
52           $filter->set_default_tmpdir
53
54       Figure out a tmpdir, from environment variables if necessary.
55
56   parse_options
57           $filter->parse_options(@ARGV);
58
59       Parse_options is called one or more times to parse ARGV-style options.
60       It should not do any IO or any irreverssable actions; defer those to
61       startup.
62
63       Fsdb::Filter::parse_options does no work; the subclass is expected to
64       call Fsdb::Filter::get_options() for all arguments.
65
66       Most modules implement certain common fsdb options, listed below.
67
68       This module also supports the standard fsdb options:
69
70       -d  Enable debugging output.
71
72       -i or --input InputSource
73           Read from InputSource, typically a file name, or "-" for standard
74           input, or (if in Perl) a IO::Handle, Fsdb::IO or Fsdb::BoundedQueue
75           objects.
76
77       -o or --output OutputDestination
78           Write to OutputDestination, typically a file name, or "-" for
79           standard output, or (if in Perl) a IO::Handle, Fsdb::IO or
80           Fsdb::BoundedQueue objects.
81
82       --autorun or --noautorun
83           By default, programs process automatically, but Fsdb::Filter
84           objects in Perl do not run until you invoke the run() method.  The
85           "--(no)autorun" option controls that behavior within Perl.
86
87       --noclose
88           By default, programs close their output when done.  For some cases
89           where objects are used internally, "--noclose" may be used to leave
90           output open for further I/O.  (This option is only supported by
91           some filters.)
92
93       --saveoutput $OUT_REF
94           By default, programs close their output when done.  With this
95           option, programs in Perl can have a subprogram create an output
96           refrence and return it to the caller in $OUT_REF.  The caller can
97           then use it for further I/O.  (This option is only supported by
98           some filters.)
99
100       --help
101           Show help.
102
103       --man
104           Show full manual.
105
106   parse_target_column
107           $self->parse_target_column(\@argv);
108
109       A helper function: allow one column to be specified as the
110       "_target_column".
111
112   get_options
113           $success = $filter->get_options(\@argv, "v+" => \$verbose, ...)
114
115       get_options is just like Getopt::Long's GetOptions, but takes the
116       argument list as the first argument.  This list is modified and any
117       non-options are returned.  It also saves _orig_argv in itself.
118
119   parse_sort_option
120           $fsdb_io = $filter->parse_sort_option($option_name, $target);
121
122       This helper function handles sorting options and column names as
123       described in dbsort(1).  We normalize long sort options to unbundled
124       short options and accumulate them in $self->{_sort_argv}.
125
126   parse_io_option
127           $fsdb_io = $filter->parse_io_option($io_direction, $option_name, $target);
128
129       This helper function handles "--input" or "--output" options, without
130       doing any setup.
131
132       It fills in $self->{_$IO_DIRECTION} with the resulting object, which is
133       either a file handle or Fsdb::Filter::Piepline object, and expects
134       "finish_io_option" to convert this token into a full Fsdb::IO object.
135
136       $IO_DIRECTION is usually input or output, but it can also be inputs
137       (with an "s") when multiple input sources are allowed.
138
139   finish_one_io_option
140           $fsdb_io = $filter->finish_io_option($io_direction, $token, @fsdb_args);
141
142       This helper function finishes setting up a Fsdb::IO object in
143       $IO_DIRECTION, using $TOKEN as information.  using @FSDB_ARGS as
144       parameters.  It creates the actual Fsdb::IO objects, opens the files
145       (or whatever), and reads the headers.  It returns the $FSDB_IO option.
146
147       $IO_DIRECTION must be "input" or "output".
148
149       Since it does IO, finish_io_option should only be called from setup,
150       not parse_options.
151
152       Can be called once per IO stream.
153
154   finish_io_option
155           $filter->finish_io_option($io_direction, @fsdb_args);
156
157       This helper function finishes setting up a Fsdb::IO object in
158       $IO_DIRECTION, using @FSDB_ARGS as parameters.  It creates the actual
159       Fsdb::IO objects, opens the files (or whatever), and reads the headers.
160       the resulting Fsdb::IO objects are built from "$self-"{_$IO_DIRECTION}>
161       and are left in "$self-"{_in}> or ("_out" or @_ins).
162
163       $IO_DIRECTION must be "input", "inputs" or "output".
164
165       Since it does IO, finish_io_option should only be called from setup,
166       not parse_options.
167
168       Can be called once per IO stream.
169
170       No return value.
171
172   direction_to_stdio
173           $fh = direction_to_stdio($direction)
174
175       Private internal routing.  Give a filehandle for STDIN or STDOUT based
176       on $DIRECTION == 'input or 'output'
177
178   finish_fh_io_option
179           $filter->finish_fh_io_option($io_direction);
180
181       This helper function creates a filehandle in $IO_DIRECTION.  Compare to
182       finish_io_option which creates a Fsdb::IO object.  It creates the
183       actual IO::File objects, opens the files (or whatever).  The filehandle
184       is built from "$self-"{_$IO_DIRECTION}> and are left in "$self-"{_in}>
185       or ("_out").
186
187       $IO_DIRECTION must be "input" or "output".
188
189       This function does no IO.
190
191       No return value.
192
193   setup
194           $filter->setup();
195
196       Do any setup that requires minimal IO (for example, reading and parsing
197       headers).
198
199       Called exactly once.
200
201   run
202           $filter->run();
203
204       Execute the body, typically iterating over the input rows.
205
206       Called exactly once.
207
208   compute_program_log
209           $log = $filter->figure_program_log();
210
211       Compute and return the log entry for a program.
212
213   finish
214           $filter->finish();
215
216       Write out any trailing comments and close output.
217
218   setup_run_finish
219           $filter->setup_run_finish();
220
221       Shorthand for doing everything needed to run a command straightaway.
222
223   info
224           $filter->info($INFOTYPE)
225
226       Return information about what the filter does.  Infotypes:
227
228       input_type Types of input accepted. Raw types are: "fsdbtext",
229       "fsdbobj", "fsdb*", "text", or "none".
230       output_type Type of output produced. Same format as input_type.
231       input_count Number of input streams (usually 1).
232       output_count Number of input streams (usually 1).
233

CLASS-SPECIFIC UTILITY ROUTINES

235       Filter has some class-specific utility routines in it.  (I.e., they
236       know about $self.)
237
238   create_pass_comments_sub
239           $filter->create_pass_comments_sub
240       or
241           $filter->create_pass_comments_sub('_VALUE');
242
243       Creates a code block suitable for passing to "Fsdb::IO::Readers"
244       "-comment_handler" that passes comments through to "$self-"{_out}>.  Or
245       with the optional argument, through "$self-"{_VALUE}>.
246
247   create_tolerant_pass_comments_sub
248           $filter->create_tolerant_pass_comments_sub
249       or
250           $filter->create_tolerant_pass_comments_sub('_VALUE');
251
252       Like "$self-"create_pass_comments_sub>, but this version tolerates the
253       output not being opened.  In those cases, comments are discarded.
254       Warning: use carefully to guarantee consistent results.
255
256       A symptom requiring tolerance is to get an error like "Can't call
257       method "write_raw" on an undefined value at
258       /usr/lib/perl5/vendor_perl/5.10.0/Fsdb/Filter.pm line 678."  (which
259       will be the sub create_pass_comments_sub ($;$) line in
260       create_pass_comments.)
261
262   create_delay_comments_sub
263           $filter->create_delay_comments_sub($optional_value);
264
265       Creates a code block suitable for passing to Fsdb::IO::Readers
266       -comment_handler that will buffer comments for automatic (from
267       $self->final) after all other IO.  No output occurs until finish() is
268       called, at which time "$self->{_out}" must be a live Fsdb object.
269
270   create_compare_code
271           $filter->create_compare_code($a_fsdb, $b_fsdb, $a_fref_name, $b_fref_name).
272
273       Write compare code based on sort-style options stored in
274       "$self-"{_sort_argv}>.  $A_FSDB and $B_FSDB are the Fsdb::IO object
275       that defines the schemas for the two objects.  We assume the variables
276       $a and $b point to arefs; these names can be overridden by specifying
277       $A_FREF_NAME and $B_FREF_NAME.
278
279       Returns undef if there are no fields in "$self-"{_sort_argv}>.
280
281   numeric_formatting
282           $out = $self->numeric_formatting($x)
283
284       Display a floating point number $x using $self->{_format}, handling
285       possible non-numeric "-" as a special case.
286
287   setup_exactly_two_inputs
288           $self->setup_exactly_two_inputs
289
290       Ensure that there are exactly two input streams.  Common to dbmerge and
291       dbjoin.
292

NON-CLASS UTILITY ROUTINES

294       Filter also has some utility routines that are not part of the class
295       structure.  They are not exported.
296
297       (none currently)
298
299
300
301perl v5.34.0                      2021-07-22                   Fsdb::Filter(3)