NAME

Devel::TraceSAX - Trace SAX events

SYNOPSIS

  ## From the command line:
    perl -d:TraceSAX           script.pl
    perl -d:TraceSAX=-dump_all script.pl

  ## procedural:
    use Devel::TraceSAX;

    trace_SAX $obj1;

  ## Emitting additional messages
    use Devel::TraceSAX qw( emit_trace_SAX_message );

    emit_trace_SAX_message "this is a test";

DESCRIPTION

WARNING: alpha code alert!!! This module and its API subject to change, possibly radically :).

Traces SAX events in a program. Works by applying Devel::TraceCalls to a tracer on the desired classes for all known SAX event types (according to XML::SAX::EventMethodMaker and XML::SAX::Machines).

Emitting messages if and only if Devel::TraceCalls is loaded

    use constant _tracing => defined $Devel::TraceSAX::VERSION;

    BEGIN {
        eval "use Devel::TraceCalls qw( emit_trace_SAX_message )"
            if _tracing;
    }

    emit_trace_SAX_message( "hi!" ) if _tracing;

Using the constant _tracing allows expressions like

    emit_trace_SAX_message(...) if _tracing;

to be optimized away at compile time, resulting in little or no performance penalty.

TODO

Add a lot more formatting clean-up.

LIMITATIONS

This module overloads CORE::GLOBAL::require when used from the command line via -d: or -M. For some reason this causes spurious warnings like

   Unquoted string "fields" may clash with future reserved word at /usr/local/lib/perl5/5.6.1/base.pm line 87.

That line looks like "require fields;", so it looks like the (*) prototype on our CORE::GLOBAL::require = sub (*) {...} isn't having it's desired effect. It would be nice to clean these up.

AUTHOR

    Barrie Slaymaker <barries@slaysys.com>

LICENSE

You may use this under the terms of either the Artistic License or any version of the BSD or GPL licenses :).