[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.35, Wed Jan 11 19:26:45 2006 UTC revision 1.39, Fri Feb 24 19:45:29 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 StandardSetup ScriptSetup ScriptFinish);      @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open OpenDir TICK StandardSetup ScriptSetup ScriptFinish Insure);
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 27  Line 27 
27      use FIG_Config;      use FIG_Config;
28      use PageBuilder;      use PageBuilder;
29      use Digest::MD5;      use Digest::MD5;
30        use File::Basename;
31        use File::Path;
32    
33  =head1 Tracing and Debugging Helpers  =head1 Tracing and Debugging Helpers
34    
# Line 208  Line 210 
210    
211  =head3 StandardSetup  =head3 StandardSetup
212    
213  C<< my ($options, @parameters) = StandardSetup(\@categories, \%options, @ARGV); >>  C<< my ($options, @parameters) = StandardSetup(\@categories, \%options, $parmHelp, @ARGV); >>
214    
215  This method performs standard command-line parsing and tracing setup. The return  This method performs standard command-line parsing and tracing setup. The return
216  values are a hash of the command-line options and a list of the positional  values are a hash of the command-line options and a list of the positional
# Line 255  Line 257 
257      TransactFeatures -trace=3 -sql register ../xacts IDs.tbl      TransactFeatures -trace=3 -sql register ../xacts IDs.tbl
258    
259  Standard tracing is output to the standard output and echoed to the file  Standard tracing is output to the standard output and echoed to the file
260  C<trace.log> in the FIG temporary directory.  C<trace>I<$$>C<.log> in the FIG temporary directory, where I<$$> is the
261    process ID. You can also specify the C<user> parameter to put a user ID
262    instead of a process ID in the trace file name. So, for example
263    
264  The default trace level is 2. To get all messages, specify a trace level of 4.  The default trace level is 2. To get all messages, specify a trace level of 4.
265  For a genome-by-genome update, use 3.  For a genome-by-genome update, use 3.
266    
267        TransactFeatures -trace=3 -sql -user=Bruce register ../xacts IDs.tbl
268    
269    would send the trace output to C<traceBruce.log> in the temporary directory.
270    
271  The I<options> parameter is a reference to a hash containing the command-line  The I<options> parameter is a reference to a hash containing the command-line
272  options and their default values. Command-line options may be in the form of switches  options, their default values, and an explanation of what they mean. Command-line
273  or keywords. In the case of a switch, the option value is 1 if it is specified and  options may be in the form of switches or keywords. In the case of a switch, the
274  0 if it is not specified. In the case of a keyword, the value is separated from the  option value is 1 if it is specified and 0 if it is not specified. In the case
275  option name by an equal sign. You can see this last in the command-line example above.  of a keyword, the value is separated from the option name by an equal sign. You
276    can see this last in the command-line example above.
277    
278  An example at this point would help. Consider, for example, the command-line utility  An example at this point would help. Consider, for example, the command-line utility
279  C<TransactFeatures>. It accepts a list of positional parameters plus the options  C<TransactFeatures>. It accepts a list of positional parameters plus the options
# Line 272  Line 281 
281  the following code.  the following code.
282    
283      my ($options, @parameters) = Tracer::StandardSetup(["DocUtils"],      my ($options, @parameters) = Tracer::StandardSetup(["DocUtils"],
284                                                        { safe => 0, noAlias => 0,                          { safe => [0, "use database transactions"],
285                                                          start => ' ', tblFiles => 0},                            noAlias => [0, "do not expect aliases in CHANGE transactions"],
286                              start => [' ', "start with this genome"],
287                              tblFiles => [0, "output TBL files containing the corrected IDs"] },
288                            "command transactionDirectory IDfile",
289                                                      @ARGV);                                                      @ARGV);
290    
291    
# Line 302  Line 314 
314  need to be added in the future, they can be processed by this method without  need to be added in the future, they can be processed by this method without
315  upsetting the command-line utilities.  upsetting the command-line utilities.
316    
317    Finally, if the special option C<-h> is specified, the option names will
318    be traced at level 0 and the program will exit without processing.
319    This provides a limited help capability. For example, if the user enters
320    
321        TransactFeatures -h
322    
323    he would see the following output.
324    
325        TransactFeatures [options] command transactionDirectory IDfile
326            -trace    tracing level (default 2)
327            -sql      trace SQL commands
328            -safe     use database transactions
329            -noAlias  do not expect aliases in CHANGE transactions
330            -start    start with this genome
331            -tblFiles output TBL files containing the corrected IDs
332    
333  The parameters to this method are as follows.  The parameters to this method are as follows.
334    
335  =over 4  =over 4
# Line 315  Line 343 
343  =item options  =item options
344    
345  Reference to a hash containing the legal options for the current command mapped  Reference to a hash containing the legal options for the current command mapped
346  to their default values. The use can override the defaults by specifying the  to their default values and descriptions. The user can override the defaults
347  options as command-line switches prefixed by a hyphen. Tracing-related options  by specifying the options as command-line switches prefixed by a hyphen.
348  may be added to this hash.  Tracing-related options may be added to this hash. If the C<-h> option is
349    specified on the command line, the option descriptions will be used to
350    explain the options.
351    
352    =item parmHelp
353    
354    A string that vaguely describes the positional parameters. This is used
355    if the user specifies the C<-h> option.
356    
357  =item ARGV  =item ARGV
358    
# Line 337  Line 372 
372    
373  sub StandardSetup {  sub StandardSetup {
374      # Get the parameters.      # Get the parameters.
375      my ($categories, $options, @argv) = @_;      my ($categories, $options, $parmHelp, @argv) = @_;
376      # Add the tracing options.      # Add the tracing options.
377      $options->{trace} = 2;      $options->{trace} = [2, "tracing level"];
378      $options->{sql} = 0;      $options->{sql} = [0, "turn on SQL tracing"];
379        $options->{h} = [0, "display command-line options"];
380        $options->{user} = [$$, "trace log file name suffix"];
381        # Create a parsing hash from the options hash. The parsing hash
382        # contains the default values rather than the default value
383        # and the description. While we're at it, we'll memorize the
384        # length of the longest option name.
385        my $longestName = 0;
386        my %parseOptions = ();
387        for my $key (keys %{$options}) {
388            if (length $key > $longestName) {
389                $longestName = length $key;
390            }
391            $parseOptions{$key} = $options->{$key}->[0];
392        }
393      # Parse the command line.      # Parse the command line.
394      my ($retOptions, @retParameters) = ParseCommand($options, @argv);      my ($retOptions, @retParameters) = ParseCommand(\%parseOptions, @argv);
395      # Now we want to set up tracing. First, we need to know if SQL is to      # Now we want to set up tracing. First, we need to know if SQL is to
396      # be traced.      # be traced.
397      my @cats = @{$categories};      my @cats = @{$categories};
# Line 353  Line 402 
402      push @cats, "Tracer", "FIG";      push @cats, "Tracer", "FIG";
403      # Next, we create the category string by prefixing the trace level      # Next, we create the category string by prefixing the trace level
404      # and joining the categories.      # and joining the categories.
405      my $cats = join(" ", $options->{trace}, @cats);      my $cats = join(" ", $parseOptions{trace}, @cats);
406      # Now set up the tracing.      # Now set up the tracing.
407      TSetup($cats, "+>$FIG_Config::temp/trace.log");      my $suffix = $retOptions->{user};
408        TSetup($cats, "+>$FIG_Config::temp/trace$suffix.log");
409        # Check for the "h" option. If it is specified, dump the command-line
410        # options and exit the program.
411        if ($retOptions->{h}) {
412            $0 =~ m#[/\\](\w+)(\.pl)?$#i;
413            Trace("$1 [options] $parmHelp") if T(0);
414            for my $key (sort keys %{$options}) {
415                my $name = Pad($key, $longestName, 0, ' ');
416                my $desc = $options->{$key}->[1];
417                if ($options->{$key}->[0]) {
418                    $desc .= " (default " . $options->{$key}->[0] . ")";
419                }
420                Trace("  $name $desc") if T(0);
421            }
422            exit(0);
423        }
424      # Return the parsed parameters.      # Return the parsed parameters.
425      return ($retOptions, @retParameters);      return ($retOptions, @retParameters);
426  }  }
# Line 915  Line 980 
980          # Convert it to lower case before we hash it.          # Convert it to lower case before we hash it.
981          $category = lc $category;          $category = lc $category;
982          # Use the category and tracelevel to compute the result.          # Use the category and tracelevel to compute the result.
983            if (ref $traceLevel) {
984                Confess("Bad trace level.");
985            } elsif (ref $TraceLevel) {
986                Confess("Bad trace config.");
987            }
988          $retVal = ($traceLevel <= $TraceLevel && ($AllTrace || exists $Categories{$category}));          $retVal = ($traceLevel <= $TraceLevel && ($AllTrace || exists $Categories{$category}));
989      }      }
990      # Return the computed result.      # Return the computed result.
# Line 1225  Line 1295 
1295  =item RETURN  =item RETURN
1296    
1297  In a list context, returns the entire file as a list with the line terminators removed.  In a list context, returns the entire file as a list with the line terminators removed.
1298  In a scalar context, returns the entire file as a string.  In a scalar context, returns the entire file as a string. If an error occurs opening
1299    the file, an empty list will be returned.
1300    
1301  =back  =back
1302    
# Line 1779  Line 1850 
1850  to their values. The template file will be read into memory, and variable markers  to their values. The template file will be read into memory, and variable markers
1851  will be replaced by data in this hash reference.  will be replaced by data in this hash reference.
1852    
1853    =back
1854    
1855  =cut  =cut
1856    
1857  sub ScriptFinish {  sub ScriptFinish {
# Line 1808  Line 1881 
1881      print $outputString;      print $outputString;
1882  }  }
1883    
1884    =head3 Insure
1885    
1886    C<< Insure($dirName); >>
1887    
1888    Insure a directory is present.
1889    
1890    =over 4
1891    
1892    =item dirName
1893    
1894    Name of the directory to check. If it does not exist, it will be created.
1895    
1896    =back
1897    
1898    =cut
1899    
1900    sub Insure {
1901        my ($dirName) = @_;
1902        if (! -d $dirName) {
1903            Trace("Creating $dirName directory.") if T(2);
1904            mkpath $dirName;
1905        }
1906    }
1907    
1908  1;  1;

Legend:
Removed from v.1.35  
changed lines
  Added in v.1.39

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3