MMAgic::Trace - Perl filter used to (de)activate trace statements. More...

Public Member Functions
	import (@@tags)
	Activate and configure trace filter.
	filter ()
	Filter source to activate trace statements.

Detailed Description

MMAgic::Trace - Perl filter used to (de)activate trace statements.

SYNOPSIS

  use MMAgic::Trace;
  
  # ...or...
  
  use MMAgic::Trace qw(XXX); # set XXX tag
  
  #!#     this line is a trace statement
  #*#     include this trace statement (easy one-line include)
  #$#     include trace statements to end of subroutine
  #!#     include this if use Trace qw(XXX);  #[XXX]
  #!#     include this if one of tags set     #[XXX YYY]

DESCRIPTION

The MMAgic::Trace source filter works by changing the source code early in the compilation process. Certain special comment sequences are used to indicate lines of code that contain trace statements.

Unlike many trace mechanisms, the trace statements that are not activated are never executing at run-time. There is a minor compile-time penalty for using the source filter but once the program is running the un-activated statements are just comments and take up no CPU cycles whatsoever.

It is possible to use this filter for anything, not (just) trace statements. For other uses it may be necessary to write a more specific filter.

Special Comments

Special comment sequences are used to mark lines that will potentially be activated by the filter. The first three characters of the line are #?# where the center character (between the two octothorpes) determines the behavior of the line. The basic sequence is #!# which indicates an unactivated line.

Statements can be activated by changing them slightly, replacing #!# with #*# or #$# to activate one or more lines. #*# just activates that line, whereas #$# activates that line and any other #!# lines until the end of the current subroutine.

There is no way to activate lines at this level of granularity without editing the source file to change the comment sequences. It is possible, of course, to activate lines that have additional control behavior that will be executed at run-time, gaining the best of both worlds.

Tag Groups

It is also possible to mark one or more lines with tags, grouping lines together so that they can be (de)activated at one time. These tags only apply to lines that begin with a comment sequence such as #!#. The tags are added to the end of such lines using a sequence #[TAG] where TAG is whatever tag is desired. Any number of lines can be marked with the same tag. Multiple tags can be added to a line within the square brackets separated by spaces.

There are two means of activating lines by tag. The first is to add the desired tags onto the use statement in a list which will be processed by the MMAgic::Trace::import() function. This requires editing of the source file.

The second method is to use one or more command-line parameters of the form --trace=TAG, allowing them to be activated at run-time. These are parsed during the MMAgic::Trace::import() function and activate the specified tag(s) for all files that use those tags. This allows the tagged lines to be activated at run-time. This parsing occurs prior to changes made by Getopt::Long.

COPYRIGHT AND LICENSE

Author:: Marc M. Adkins, mailto:Perl@Doorways.org

Definition at line 95 of file Trace.pm.

Member Function Documentation

MMAgic::Trace::filter ( )

Filter source to activate trace statements.

This is the basic mechanism used by Filter::Util::Call. Should be called once for each line of code.

Some might prefer Filter::Simple, but this works fine for now. It is not all the complicated.

MMAgic::Trace::import ( @@ tags )

Activate and configure trace filter.

Using the package activates the source filter. Special comment sequences are recognized and converted to normal code lines based on the comment sequence and/or tags specified therein.

The use statement allows optional specification of tags to activate. When tags are activated the appropriately tagged comments are converted to code throughout, so that categories of trace statements can be activated all at once.

Parameters:

@tags

tags to be activated

The documentation for this class was generated from the following file:

MMAgic/Trace.pm

MMAgic Demo: MMAgic::Trace Class Reference

MMAgic::Trace Class Reference