Diff of /FigKernelPackages/Tracer.pm

-revision 1.34, Fri Jan  6 05:34:21 2006 UTC
+revision 1.35, Wed Jan 11 19:26:45 2006 UTC
 Line 19
      require Exporter;
      @ISA = ('Exporter');
-     @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open OpenDir TICK StandardSetup);
+     @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open OpenDir TICK StandardSetup ScriptSetup ScriptFinish);
      @EXPORT_OK = qw(GetFile GetOptions Merge MergeOptions ParseCommand ParseRecord UnEscape Escape);
      use strict;
      use Carp qw(longmess croak);
 Line 257
  Standard tracing is output to the standard output and echoed to the file
  C<trace.log> in the FIG temporary directory.
- The default trace level is 3. This dumps out all SQL commands if SQL tracing
+ The default trace level is 2. To get all messages, specify a trace level of 4.
- is turned on and tends to produce one flurry of messages per genome. To get all
+ For a genome-by-genome update, use 3.
- messages, specify a trace level of 4. For generally quiet output, use 2.
  The I<options> parameter is a reference to a hash containing the command-line
  options and their default values. Command-line options may be in the form of switches
-Line 273
+Line 272
  the following code.
      my ($options, @parameters) = Tracer::StandardSetup(["DocUtils"],
-                                                       { trace => 3, sql => 0,
+                                                       { safe => 0, noAlias => 0,
-                                                         safe => 0, noAlias => 0,
                                                          start => ' ', tblFiles => 0},
                                                      @ARGV);
-Line 341
+Line 339
      # Get the parameters.
      my ($categories, $options, @argv) = @_;
      # Add the tracing options.
-     $options->{trace} = 3;
+     $options->{trace} = 2;
      $options->{sql} = 0;
      # Parse the command line.
      my ($retOptions, @retParameters) = ParseCommand($options, @argv);
-Line 1211
+Line 1209
  C<< my @fileContents = Tracer::GetFile($fileName); >>
- Return the entire contents of a file.
+     or
+ C<< my $fileContents = Tracer::GetFile($fileName); >>
+ Return the entire contents of a file. In list context, line-ends are removed and
+ each line is a list element. In scalar context, line-ends are replaced by C<\n>.
  =over 4
-Line 1670
+Line 1673
      return `$commandString`;
  }
+ =head3 ScriptSetup
+ C<< my ($query, $varHash) = ScriptSetup(); >>
+ Perform standard tracing and debugging setup for scripts. The value returned is
+ the CGI object followed by a pre-built variable hash.
+ The C<Trace> query parameter is used to determine whether or not tracing is active and
+ which trace modules (other than C<Tracer> and C<FIG>) should be turned on. Specifying
+ the C<CGI> trace module will trace parameter and environment information. Parameters are
+ traced at level 3 and environment variables at level 4. At the end of the script, the
+ client should call L</ScriptFinish> to output the web page.
+ =cut
+ sub ScriptSetup {
+     # Get the CGI query object.
+     my $query = CGI->new();
+     # Check for tracing. Set it up if the user asked for it.
+     if ($query->param('Trace')) {
+         # Set up tracing to be queued for display at the bottom of the web page.
+         TSetup($query->param('Trace') . " FIG Tracer", "QUEUE");
+         # Trace the parameter and environment data.
+         if (T(CGI => 3)) {
+             # Here we want to trace the parameter data.
+             my @names = $query->param;
+             for my $parmName (sort @names) {
+                 # Note we skip "Trace", which is for our use only.
+                 if ($parmName ne 'Trace') {
+                     my @values = $query->param($parmName);
+                     Trace("CGI: $parmName = " . join(", ", @values));
+                 }
+             }
+         }
+         if (T(CGI => 4)) {
+             # Here we want the environment data too.
+             for my $envName (sort keys %ENV) {
+                 Trace("ENV: $envName = $ENV{$envName}");
+             }
+         }
+     } else {
+         # Here tracing is to be turned off. All we allow is errors traced into the
+         # error log.
+         TSetup("0", "WARN");
+     }
+     # Create the variable hash.
+     my $varHash = { DebugData => '' };
+     # If we're in DEBUG mode, set up the debug mode data for forms.
+     if (Tracer::DebugMode) {
+         $varHash->{DebugData} = GetFile("Html/DebugFragment.html");
+     }
+     # Return the query object and variable hash.
+     return ($query, $varHash);
+ }
+ =head3 ScriptFinish
+ C<< ScriptFinish($webData, $varHash); >>
+ Output a web page at the end of a script. Either the string to be output or the
+ name of a template file can be specified. If the second parameter is omitted,
+ it is assumed we have a string to be output; otherwise, it is assumed we have the
+ name of a template file. The template should have the variable C<DebugData>
+ specified in any form that invokes a standard script. If debugging mode is turned
+ on, a form field will be put in that allows the user to enter tracing data.
+ Trace messages will be placed immediately before the terminal C<BODY> tag in
+ the output, formatted as a list.
+ A typical standard script would loook like the following.
+     BEGIN {
+         # Print the HTML header.
+         print "CONTENT-TYPE: text/html\n\n";
+     }
+     use Tracer;
+     use CGI;
+     use FIG;
+     # ... more uses ...
+     my ($query, $varHash) = ScriptSetup();
+     eval {
+         # ... get data from $query, put it in $varHash ...
+     };
+     if ($@) {
+         Trace("Script Error: $@") if T(0);
+     }
+     ScriptFinish("Html/MyTemplate.html", $varHash);
+ The idea here is that even if the script fails, you'll see trace messages and
+ useful output.
+ =over 4
+ =item webData
+ A string containing either the full web page to be written to the output or the
+ name of a template file from which the page is to be constructed. If the name
+ of a template file is specified, then the second parameter must be present;
+ otherwise, it must be absent.
+ =item varHash (optional)
+ If specified, then a reference to a hash mapping variable names for a template
+ to their values. The template file will be read into memory, and variable markers
+ will be replaced by data in this hash reference.
+ =cut
+ sub ScriptFinish {
+     # Get the parameters.
+     my ($webData, $varHash) = @_;
+     # Check for a template file situation.
+     my $outputString;
+     if (defined $varHash) {
+         # Here we have a template file. We need to apply the variables to the template.
+         $outputString = PageBuilder::Build("<$webData", $varHash, "Html");
+     } else {
+         # Here the user gave us a raw string.
+         $outputString = $webData;
+     }
+     # Check for trace messages.
+     if ($Destination eq "QUEUE") {
+         # We have trace messages, so we want to put them at the end of the body. This
+         # is either at the end of the whole string or at the beginning of the BODY
+         # end-tag.
+         my $pos = length $outputString;
+         if ($outputString =~ m#</body>#gi) {
+             $pos = (pos $outputString) - 7;
+         }
+         substr $outputString, $pos, 0, QTrace('Html');
+     }
+     # Write the output string.
+     print $outputString;
+ }
 ;

 Legend:



Removed from v.1.34
 


changed lines


 
Added in v.1.35
 Legend:



Removed from v.1.34
 


changed lines


 
Added in v.1.35
-Removed from v.1.34
+Added in v.1.35

MCS Webmaster	ViewVC Help
Powered by ViewVC 1.0.3