[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.9, Wed May 4 03:05:12 2005 UTC revision 1.10, Thu Jun 9 05:36:30 2005 UTC
# Line 2  Line 2 
2    
3          require Exporter;          require Exporter;
4          @ISA = ('Exporter');          @ISA = ('Exporter');
5          @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert);          @EXPORT = qw(Trace T TSetup QTrace Confess Cluck Min Max Assert Open);
6          @EXPORT_OK = qw(GetFile GetOptions Merge MergeOptions ParseCommand ParseRecord UnEscape Escape);          @EXPORT_OK = qw(GetFile GetOptions Merge MergeOptions ParseCommand ParseRecord UnEscape Escape);
7          use strict;          use strict;
8          use Carp qw(longmess croak);          use Carp qw(longmess croak);
# Line 20  Line 20 
20  has a list of categories and a single trace level set by the B<TSetup> method. Only messages whose trace  has a list of categories and a single trace level set by the B<TSetup> method. Only messages whose trace
21  level is less than or equal to this package's trace level and whose category is activated will  level is less than or equal to this package's trace level and whose category is activated will
22  be written. Thus, a higher trace level on a message indicates that the message  be written. Thus, a higher trace level on a message indicates that the message
23  is less likely to be seen. A higher trace level passed to B<Setup> means more trace messages will  is less likely to be seen. A higher trace level passed to B<TSetup> means more trace messages will
24  appear. To generate a trace message, use the following syntax.  appear. To generate a trace message, use the following syntax.
25    
26  C<< Trace($message) if T(errors => 4); >>  C<< Trace($message) if T(errors => 4); >>
# Line 38  Line 38 
38    
39  C<< Trace($message) if T(2); >>  C<< Trace($message) if T(2); >>
40    
41  To set up tracing, you call the C</Setup> method. The method takes as input a trace level, a list  To set up tracing, you call the L</TSetup> method. The method takes as input a trace level, a list
42  of category names, and a set of options. The trace level and list of category names are  of category names, and a set of options. The trace level and list of category names are
43  specified as a space-delimited string. Thus  specified as a space-delimited string. Thus
44    
# Line 46  Line 46 
46    
47  sets the trace level to 3, activates the C<errors>, C<Sprout>, and C<ERDB> categories, and  sets the trace level to 3, activates the C<errors>, C<Sprout>, and C<ERDB> categories, and
48  specifies that messages should be output as HTML paragraphs. The parameters are formatted  specifies that messages should be output as HTML paragraphs. The parameters are formatted
49  to make it easier to input tracing configuration on a web form.  a little clumsily, but it makes them easier to input on a web form or in a query URL.
50    
51  In addition to HTML and file output for trace messages, you can specify that the trace messages  In addition to HTML and file output for trace messages, you can specify that the trace messages
52  be queued. The messages can then be retrieved by calling the L</QTrace> method. This approach  be queued. The messages can then be retrieved by calling the L</QTrace> method. This approach
# Line 61  Line 61 
61  Thus, debugging information is available and easily retrieved even when the application is  Thus, debugging information is available and easily retrieved even when the application is
62  being used out in the field.  being used out in the field.
63    
64    There is no hard and fast rule on how to use trace levels. The following is therefore only
65    a suggestion.
66    
67    =over 4
68    
69    =item 0 Error
70    
71    Message indicates an error that may lead to incorrect results or that has stopped the
72    application entirely.
73    
74    =item 1 Warning
75    
76    Message indicates something that is unexpected but that probably did not interfere
77    with program execution.
78    
79    =item 2 Notice
80    
81    Message indicates the beginning or end of a major task.
82    
83    =item 3 Information
84    
85    Message indicates a subtask. In the FIG system, a subtask generally relates to a single
86    genome. This would be a big loop that is not expected to execute more than 500 times or so.
87    
88    =item 4 Detail
89    
90    Message indicates a low-level loop iteration.
91    
92    =back
93    
94  =cut  =cut
95    
96  # Declare the configuration variables.  # Declare the configuration variables.
97    
98  my $Destination = "NONE";       # Description of where to send the trace output.  my $Destination = "NONE";       # Description of where to send the trace output.
99    my $TeeFlag = 0;                        # TRUE if output is going to a file and to the
100                                                            # standard output
101  my %Categories = ( main => 1 );  my %Categories = ( main => 1 );
102                                                          # hash of active category names                                                          # hash of active category names
103  my $TraceLevel = 0;                     # trace level; a higher trace level produces more  my $TraceLevel = 0;                     # trace level; a higher trace level produces more
# Line 93  Line 125 
125    
126  The destination for the trace output. To send the trace output to a file, specify the file  The destination for the trace output. To send the trace output to a file, specify the file
127  name preceded by a ">" symbol. If a double symbol is used (">>"), then the data is appended  name preceded by a ">" symbol. If a double symbol is used (">>"), then the data is appended
128  to the file. Otherwise the file is cleared before tracing begins. In addition to sending  to the file. Otherwise the file is cleared before tracing begins. Precede the first ">"
129  the trace messages to a file, you can specify a special destination. C<HTML> will cause  symbol with a C<+> to echo output to a file AND to the standard output. In addition to
130  tracing to the standard output with each line formatted as an HTML paragraph. C<TEXT>  sending the trace messages to a file, you can specify a special destination. C<HTML> will
131    cause tracing to the standard output with each line formatted as an HTML paragraph. C<TEXT>
132  will cause tracing to the standard output as ordinary text. C<ERROR> will cause trace  will cause tracing to the standard output as ordinary text. C<ERROR> will cause trace
133  messages to be sent to the standard error output as ordinary text. C<QUEUE> will cause trace  messages to be sent to the standard error output as ordinary text. C<QUEUE> will cause trace
134  messages to be stored in a queue for later retrieval by the L</QTrace> method. C<WARN> will  messages to be stored in a queue for later retrieval by the L</QTrace> method. C<WARN> will
# Line 118  Line 151 
151                  $Categories{$category} = 1;                  $Categories{$category} = 1;
152          }          }
153          # Now we need to process the destination information. The most important special          # Now we need to process the destination information. The most important special
154          # case is the single ">", which requires we clear the file first. After doing          # cases are the single ">", which requires we clear the file first, and the
155          # so, we tack on another ">" sign so that future trace messages are appended.          # "+" prefix which indicates a double echo.
156            if ($target =~ m/^\+?>>?/) {
157                    if ($target =~ m/^\+/) {
158                            $TeeFlag = 1;
159                            $target = substr($target, 1);
160                    }
161          if ($target =~ m/^>[^>]/) {          if ($target =~ m/^>[^>]/) {
162                  open TRACEFILE, $target;                  open TRACEFILE, $target;
163                  print TRACEFILE Now() . " Tracing initialized.\n";                  print TRACEFILE Now() . " Tracing initialized.\n";
164                  close TRACEFILE;                  close TRACEFILE;
165                  $Destination = ">$target";                  $Destination = ">$target";
166          } else {          } else {
167                            $Destination = $target;
168                    }
169            } else {
170                  $Destination = uc($target);                  $Destination = uc($target);
171          }          }
172  }  }
173    
174    =head3 Open
175    
176    C<< my $handle = Open($fileHandle, $fileSpec, $message); >>
177    
178    Open a file and throw an exception if the open fails.
179    
180    The I<$fileSpec> is essentially the second argument of the PERL C<open>
181    function. The mode is specified using Unix-like shell information. So, for
182    example,
183    
184            Open(\*LOGFILE, '>>/usr/spool/news/twitlog', "Could not open twit log.");
185    
186    would open for output appended to the specified file, and
187    
188            Open(\*DATASTREAM, "| sort -u >$outputFile", "Could not open $outputFile.");
189    
190    would open a pipe that sorts the records written and removes duplicates. Note
191    that the file handle is specified as a string. Note the use of file handle
192    syntax in the Open call. To use anonymous file handles, code as follows.
193    
194            my $logFile = Open(undef, '>>/usr/spool/news/twitlog', "Could not open twit log.");
195    
196    The I<$message> parameter is used if the open fails to construct an error message.
197    If the parameter is omitted, a standard message is constructed using the file spec.
198    
199            Could not open "/usr/spool/news/twitlog"
200    
201    Note that the mode characters are automatically cleaned from the file name.
202    The actual error message from the file system will be captured and appended to the
203    message in any case.
204    
205            Could not open "/usr/spool/news/twitlog": file not found.
206    
207    In some versions of PERL the only error message we get is a number, which
208    corresponds to the C++ C<errno> value.
209    
210            Could not open "/usr/spool/news/twitlog": 6.
211    
212    This method has no provision for passing back error information. Its purpose is
213    to simplify the standard coding practice of opening files and killing the process
214    if the open doesn't work. If the trace level for C<Tracer> is set to level 1,
215    it will automatically show a stack trace as well.
216    
217    =over 4
218    
219    =item fileHandle
220    
221    File handle. If this parameter is C<undef>, a file handle will be generated
222    and returned as the value of this method.
223    
224    =item fileSpec
225    
226    File name and mode, as per the PERL C<open> function.
227    
228    =item message (optional)
229    
230    Error message to use if the open fails. If omitted, a standard error message
231    will be generated. In either case, the error information from the file system
232    is appended to the message.
233    
234    =item RETURN
235    
236    Returns the name of the file handle assigned to the file.
237    
238    =back
239    
240    =cut
241    
242    sub Open {
243            # Get the parameters.
244            my ($fileHandle, $fileSpec, $message) = @_;
245            # Attempt to open the file.
246            my $rv = open $fileHandle, $fileSpec;
247            # If the open failed, generate an error message.
248            if (! $rv) {
249                    # Save the system error message.
250                    my $sysMessage = $!;
251                    # Clean any obvious mode characters and leading spaces from the
252                    # filename.
253                    $fileSpec =~ s/^(<|>*)\s*//;
254                    if (!$message) {
255                            $message = "Could not open \"$fileSpec\"";
256                    }
257                    # Terminate with an error using the supplied message and the
258                    # error message from the file system.
259                    Confess("$message: $!");
260            }
261            # Return the file handle.
262            return $fileHandle;
263    }
264    
265  =head3 SetLevel  =head3 SetLevel
266    
267  C<< Tracer::SetLevel($newLevel); >>  C<< Tracer::SetLevel($newLevel); >>
# Line 397  Line 529 
529                  open TRACING, $Destination;                  open TRACING, $Destination;
530                  print TRACING "$formatted\n";                  print TRACING "$formatted\n";
531                  close TRACING;                  close TRACING;
532                    # If the Tee flag is on, echo it to the standard output.
533                    if ($TeeFlag) {
534                            print "$formatted\n";
535                    }
536          }          }
537  }  }
538    
# Line 774  Line 910 
910                  # Close it.                  # Close it.
911                  close INPUTFILE;                  close INPUTFILE;
912          my $actualLines = @retVal;          my $actualLines = @retVal;
         Trace("$lineCount lines read from $fileName. $actualLines processed.") if T(3);  
913          }          }
914          # Return the file's contents in the desired format.          # Return the file's contents in the desired format.
915      if (wantarray) {      if (wantarray) {

Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3