NAME

    Devel::Trace::Subs - Generate, track, store and print code flow and
    stack traces.

SYNOPSIS

        use Devel::Trace::Subs qw(trace trace_dump);
    
        # add a trace() call to the top of all your subs
    
        trace(); # or even better: $trace() if $ENV{DTS_ENABLE};
    
        # enable the module anywhere in the stack (preferably the calling script)
    
        $ENV{DTS_ENABLE} = 1;
    
        # then from anywhere (typically near the end of the calling script) dump the output
    
        trace_dump();
    
        # automate the installation into a file (or all files in a directory)
    
        inject_trace(file => 'filename'); # or directory, or 'Module::Name'
    
        # remove the effects of inject_trace()
    
        remove_trace(file => 'filename')

DESCRIPTION

    This module facilitates keeping track of a project's code flow and
    stack trace information in calls between subroutines.

    Optionally, you can use this module to automatically inject the
    appropriate trace() calls into some or all subs in individual files,
    all Perl files within a directory structure, or even in production
    files by specifying its Module::Name.

    It also has the facility to undo what was done by the automatic
    installation mentioned above.

EXPORT

    None by default. See EXPORT_OK

EXPORT_OK

    trace, trace_dump, inject_trace

FUNCTIONS

 trace

    Parameters: None

    In order to enable tracing, you must set $ENV{DTS_ENABLE} to a true
    value somewhere in the call stack (preferably in the calling script).
    Simply set to a false value (or remove it) to disable this module.

    Puts the call onto the stack trace. Call it in scalar context to
    retrieve the data structure as it currently sits.

 trace_dump

    Dumps the output of the collected data.

    All of the following parameters are optional.

    want => 'string', type => 'html', file => 'file.ext'

    want: Takes either 'flow' or 'stack', and will output the respective
    data collection. If this parameter is omitted, both code flow and stack
    trace information is dumped.

    type: Has only a single value, 'html. This will dump the output in HTML
    format.

    file: Takes the name of a file as a parameter. The dump will write
    output to the file specified. The program will die if the file can not
    be opened for writing.

 install_trace

    Automatically injects the necessary code into Perl files to facilitate
    stack tracing.

    Parameters:

    file => 'filename' - Mandatory: 'filename' can be the name of a single
    file, a directory, or even a 'Module::Name'. If the filename is a
    directory, we'll iterate recursively through the directory, and make
    the changes to all .pl and .pm files underneath of it. If filename is a
    'Module::Name', we'll load the file for that module dynamically, and
    modify it. CAUTION: this will edit live production files.

    copy => 'filename' - Optional: The name of a backup file. We'll copy
    the file in file parameter and copy it to the file name specified, and
    only work on the copied version, leaving the original file alone.

    include => [qw(sub1 sub2)] - Optional: An array reference with the
    names of subroutines you want to include. If include is sent in, only
    these subs will be modified, ie. all others will be excluded by
    default.

    exclude => [qw(sub1 sub2)]> - Optional: This has the exact opposite
    effect as include. Note that if exclude is sent in, include is rendered
    useless.

 remove_trace

    Automatically remove all remnants of this module from a file or files,
    that were added by this module's install_trace() method.

    Parameters: file => 'filename'

    Where 'filename' can be the name of a file, a directory or a
    'Module::Name'.

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

BUGS

    Please report any bugs or feature requests to bug-devel-trace-flow at
    rt.cpan.org, or through the web interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel-Trace-Subs. I will
    be notified, and then you'll automatically be notified of progress on
    your bug as I make changes.

SUPPORT

    You can find documentation for this module with the perldoc command.

        perldoc Devel::Trace::Subs

    You can also look for information at:

      * RT: CPAN's request tracker (report bugs here)

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=Devel-Trace-Subs

      * AnnoCPAN: Annotated CPAN documentation

      http://annocpan.org/dist/Devel-Trace-Subs

      * CPAN Ratings

      http://cpanratings.perl.org/d/Devel-Trace-Subs

      * Search CPAN

      http://search.cpan.org/dist/Devel-Trace-Subs/

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

    Copyright 2015 Steve Bertrand.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.