[Bio] / FigKernelPackages / Tracer.pm Repository:
ViewVC logotype

Diff of /FigKernelPackages/Tracer.pm

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.30, Mon Dec 5 19:06:30 2005 UTC revision 1.31, Thu Jan 5 21:41:14 2006 UTC
# Line 19  Line 19 
19    
20      require Exporter;      require Exporter;
21      @ISA = ('Exporter');      @ISA = ('Exporter');
22      @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open OpenDir TICK);      @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open OpenDir TICK StandardSetup);
23      @EXPORT_OK = qw(GetFile GetOptions Merge MergeOptions ParseCommand ParseRecord UnEscape Escape);      @EXPORT_OK = qw(GetFile GetOptions Merge MergeOptions ParseCommand ParseRecord UnEscape Escape);
24      use strict;      use strict;
25      use Carp qw(longmess croak);      use Carp qw(longmess croak);
# Line 205  Line 205 
205      $SetupCount++;      $SetupCount++;
206  }  }
207    
208    =head3 StandardSetup
209    
210    C<< my ($options, @parameters) = StandardSetup(\@categories, \%options, @ARGV); >>
211    
212    This method performs standard command-line parsing and tracing setup. The return
213    values are a hash of the command-line options and a list of the positional
214    parameters. Tracing is automatically set up and the command-line options are
215    validated.
216    
217    This is a complex method that does a lot of grunt work. The parameters can
218    be more easily understood, however, once they are examined individually.
219    
220    The I<categories> parameter is the most obtuse. It is a reference to a list of
221    special-purpose tracing categories. Most tracing categories are PERL package
222    names. So, for example, if you wanted to turn on tracing inside the B<Sprout>,
223    B<ERDB>, and B<SproutLoad> packages, you would specify the categories
224    
225        ["Sprout", "SproutLoad", "ERDB"]
226    
227    This would cause trace messages in the specified three packages to appear in
228    the output. There are threer special tracing categories that are automatically
229    handled by this method. In other words, if you used L</TSetup> you would need
230    to include these categories manually, but if you use this method they are turned
231    on automatically.
232    
233    =over 4
234    
235    =item FIG
236    
237    Turns on trace messages inside the B<FIG> package.
238    
239    =item SQL
240    
241    Traces SQL commands and activity.
242    
243    =item Tracer
244    
245    Traces error messages and call stacks.
246    
247    =back
248    
249    C<SQL> is only turned on if the C<-sql> option is specified in the command line.
250    The trace level is specified using the C<-trace> command-line option. For example,
251    the following command line for C<TransactFeatures> turns on SQL tracing and runs
252    all tracing at level 3.
253    
254        TransactFeatures -trace=3 -sql register ../xacts IDs.tbl
255    
256    Standard tracing is output to the standard output and echoed to the file
257    C<trace.log> in the FIG temporary directory.
258    
259    The default trace level is 3. This dumps out all SQL commands if SQL tracing
260    is turned on and tends to produce one flurry of messages per genome. To get all
261    messages, specify a trace level of 4. For generally quiet output, use 2.
262    
263    The I<options> parameter is a reference to a hash containing the command-line
264    options and their default values. Command-line options may be in the form of switches
265    or keywords. In the case of a switch, the option value is 1 if it is specified and
266    0 if it is not specified. In the case of a keyword, the value is separated from the
267    option name by an equal sign. You can see this last in the command-line example above.
268    
269    An example at this point would help. Consider, for example, the command-line utility
270    C<TransactFeatures>. It accepts a list of positional parameters plus the options
271    C<safe>, C<noAlias>, C<start>, and C<tblFiles>. To start up this command, we execute
272    the following code.
273    
274        my ($options, @parameters) = Tracer::StandardSetup(["DocUtils"],
275                                                          { trace => 3, sql => 0,
276                                                            safe => 0, noAlias => 0,
277                                                            start => ' ', tblFiles => 0},
278                                                        @ARGV);
279    
280    
281    The call to C<ParseCommand> specifies the default values for the options and
282    stores the actual options in a hash that is returned as C<$options>. The
283    positional parameters are returned in C<@parameters>.
284    
285    The following is a sample command line for C<TransactFeatures>.
286    
287        TransactFeatures -trace=2 -noAlias register ../xacts IDs.tbl
288    
289    In this case, C<register>, C<../xacts>, and C<IDs.tbl> are the positional
290    parameters, and would find themselves in I<@parameters> after executing the
291    above code fragment. The tracing would be set to level 2, and the categories
292    would be C<FIG>, C<Tracer>, and <DocUtils>. C<FIG> and C<Tracer> are standard,
293    and C<DocUtils> was included because it came in within the first parameter
294    to this method. The I<$options> hash would be
295    
296        { trace => 2, sql => 0, safe => 0,
297          noAlias => 1, start => ' ', tblFiles => 0 }
298    
299    Use of C<StandardSetup> in this way provides a simple way of performing
300    standard tracing setup and command-line parsing. Note that the caller is
301    not even aware of the command-line switches C<-trace> and C<-sql>, which
302    are used by this method to control the tracing. If additional tracing features
303    need to be added in the future, they can be processed by this method without
304    upsetting the command-line utilities.
305    
306    The parameters to this method are as follows.
307    
308    =over 4
309    
310    =item categories
311    
312    Reference to a list of tracing category names. These should be names of
313    packages whose internal workings will need to be debugged to get the
314    command working.
315    
316    =item options
317    
318    Reference to a hash containing the legal options for the current command mapped
319    to their default values. The use can override the defaults by specifying the
320    options as command-line switches prefixed by a hyphen. Tracing-related options
321    may be added to this hash.
322    
323    =item ARGV
324    
325    List of command line parameters, including the option switches, which must
326    precede the positional parameters and be prefixed by a hyphen.
327    
328    =item RETURN
329    
330    Returns a list. The first element of the list is the reference to a hash that
331    maps the command-line option switches to their values. These will either be the
332    default values or overrides specified on the command line. The remaining
333    elements of the list are the position parameters, in order.
334    
335    =back
336    
337    =cut
338    
339    sub StandardSetup {
340        # Get the parameters.
341        my ($categories, $options, @argv) = @_;
342        # Add the tracing options.
343        $options->{trace} = 3;
344        $options->{sql} = 0;
345        # Parse the command line.
346        my ($retOptions, @retParameters) = ParseCommand($options, @argv);
347        # Now we want to set up tracing. First, we need to know if SQL is to
348        # be traced.
349        my @cats = @{$categories};
350        if ($retOptions->{sql}) {
351            push @cats, "SQL";
352        }
353        # Add the default categories.
354        push @cats, "Tracer", "FIG";
355        # Next, we create the category string by prefixing the trace level
356        # and joining the categories.
357        my $cats = join(" ", $options->{trace}, @cats);
358        # Now set up the tracing.
359        TSetup($cats, "+>$FIG_Config::temp/trace.log");
360        # Return the parsed parameters.
361        return ($retOptions, @retParameters);
362    }
363    
364  =head3 Setups  =head3 Setups
365    
366  C<< my $count = Tracer::Setups(); >>  C<< my $count = Tracer::Setups(); >>
# Line 365  Line 521 
521    
522  =head3 OpenDir  =head3 OpenDir
523    
524  C<< my @files = OpenDir($dirName, $filtered); >>  C<< my @files = OpenDir($dirName, $filtered, $flag); >>
525    
526  Open a directory and return all the file names. This function essentially performs  Open a directory and return all the file names. This function essentially performs
527  the functions of an C<opendir> and C<readdir>. If the I<$filtered> parameter is  the functions of an C<opendir> and C<readdir>. If the I<$filtered> parameter is
528  set to TRUE, all filenames beginning with a period (C<.>) will be filtered out of  set to TRUE, all filenames beginning with a period (C<.>), dollar sign (C<$>),
529  the return list. If the directory does not open, an exception is thrown. So,  or pound sign (C<#>) will be filtered out of the return list. If the directory
530    does not open and I<$flag> is not set, an exception is thrown. So,
531  for example,  for example,
532    
533      my @files = OpenDir("/Volumes/fig/contigs", 1);      my @files = OpenDir("/Volumes/fig/contigs", 1);
# Line 378  Line 535 
535  is effectively the same as  is effectively the same as
536    
537      opendir(TMP, "/Volumes/fig/contigs") || Confess("Could not open /Volumes/fig/contigs.");      opendir(TMP, "/Volumes/fig/contigs") || Confess("Could not open /Volumes/fig/contigs.");
538      my @files = grep { $_ !~ /^\./ } readdir(TMP);      my @files = grep { $_ !~ /^[\.\$\#]/ } readdir(TMP);
539    
540  Similarly, the following code  Similarly, the following code
541    
542      my @files = grep { $_ =~ /^\d/ } OpenDir("/Volumes/fig/orgs");      my @files = grep { $_ =~ /^\d/ } OpenDir("/Volumes/fig/orgs", 0, 1);
543    
544  Returns the names of all files in C</Volumes/fig/orgs> that begin with digits and  Returns the names of all files in C</Volumes/fig/orgs> that begin with digits and
545  automatically throws an error if the directory fails to open.  automatically returns an empty list if the directory fails to open.
546    
547  =over 4  =over 4
548    
# Line 398  Line 555 
555  TRUE if files whose names begin with a period (C<.>) should be automatically removed  TRUE if files whose names begin with a period (C<.>) should be automatically removed
556  from the list, else FALSE.  from the list, else FALSE.
557    
558    =item flag
559    
560    TRUE if a failure to open is okay, else FALSE
561    
562  =back  =back
563    
564  =cut  =cut
565  #: Return Type @;  #: Return Type @;
566  sub OpenDir {  sub OpenDir {
567      # Get the parameters.      # Get the parameters.
568      my ($dirName, $filtered) = @_;      my ($dirName, $filtered, $flag) = @_;
569      # Declare the return variable.      # Declare the return variable.
570      my @retVal;      my @retVal = ();
571      # Open the directory.      # Open the directory.
572      if (opendir(my $dirHandle, $dirName)) {      if (opendir(my $dirHandle, $dirName)) {
573          # The directory opened successfully. Get the appropriate list according to the          # The directory opened successfully. Get the appropriate list according to the
574          # strictures of the filter parameter.          # strictures of the filter parameter.
575          if ($filtered) {          if ($filtered) {
576              @retVal = grep { $_ !~ /^\./ } readdir $dirHandle;              @retVal = grep { $_ !~ /^[\.\$\#]/ } readdir $dirHandle;
577          } else {          } else {
578              @retVal = readdir $dirHandle;              @retVal = readdir $dirHandle;
579          }          }
580      } else {      } elsif (! $flag) {
581          # Here the directory would not open.          # Here the directory would not open and it's considered an error.
582          Confess("Could not open directory $dirName.");          Confess("Could not open directory $dirName.");
583      }      }
584      # Return the result.      # Return the result.

Legend:
Removed from v.1.30  
changed lines
  Added in v.1.31

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3