The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Debug-Mixin-0.4.4
River stage zero No dependents
++
/ Debug::Mixin

NAME

 Debug::Mixin - Make your applications and modules easier to debug

SYNOPSIS

package my_module ;

        # load Debug::Mixin
        use Debug::Mixin
                {
                BANNER     => "my banner",
                
                # available at any point in the debugger
                DEBUGGER_SUBS => 
                        [
                        
                                {
                                NAME        => CheckDependencyMatrix
                                ALIASES     => [qw(dm_cdm cdm)],
                                DESCRIPTION => "a short description of what this sub is for",
                                HELP        => "a long, possibly multi line description displayed"
                                                . "when the user needs it",
                                SUB         => sub{},
                                }
                        ],
                } ;
                
        # add breakpoints
        AddBreakpoint
                (
                NAME    =>   'hi'
                
                FILTERS =>
                        [
                        sub 
                                {
                                my (%filter) = @_ ;
                                $filter{ARGS}{TYPE} eq 'DEPEND' ; # true will enable the actions
                                }
                        ]
                        
                ACTIONS =>
                        [
                        sub 
                                {
                                my (%filter) = @_ ;
                                
                                print DumpTree $filter{ARGS}{COMPLEX_ELEMENT} ;
                                
                                return JUMP_TO_DEBUGGER # want to jump into debugger
                                }
                        ]
                        
                DEBUGGER_SUBS=>
                        [
                                {
                                NAME        => 'BreakpointDebuggerSub',
                                DESCRIPTION => "a short description of what this sub is for",
                                HELP        => "a long, possibly multi line description displayed"
                                                . "when the user needs it",
                                SUB         => sub{},
                                }
                        ]
                        
                LOCAL_STORAGE => {}
                
                ALWAYS_USE_DEBUGGER => 0 # let subs decide if we jump in the debugger
                ACTIVE => 1
                )
                
        # use the breakpoints
        sub DoSomething
        {
        #DEBUG  
        my %debug_data = 
                (
                  TYPE           => 'VARIABLE'
                , VARIABLE_NAME  => $key
                , VARIABLE_VALUE => $value
                , ...
                ) ;
        
        #DEBUG  
        $DB::single = 1 if(Debug::Mixin::IsDebuggerEnabled() && Debug::Mixin::CheckBreakpoint(%debug_data)) ;
        
        # or
        
        if(Debug::Mixin::IsDebuggerEnabled())
                {
                %debug_data = 
                        (
                          TYPE           => 'VARIABLE'
                        , ...
                        ) ;
                        
                $DB::single = 1 if(Debug::Mixin::CheckBreakpoint(%debug_data, MORE_DATA => 1)) ;
                }

DESCRIPTION

This module help you define breakpoints for your own module or applications making them easier to debug.

DOCUMENTATION

Lately,I've been speculating about architectures that would allow us to debug them more easily. Logging, aspect oriented, web interface to internals are some examples of techniques already in use.

The perl debugger already allows us to do a lot of tricky testing before displaying a prompt or stopping only when certain conditions are met. I believe in making debugging even more practical and intelligent.

My theory is simple, actively present data, from your code, and check if a breakpoint matches. This is, in theory, not very different from smart breakpoints in the debugger except the breakpoints are defined in files outside the debugger and are part of the module distribution. The place where this breakpoints triggers are not defined by the breakpoints but by the code being debugged.

Finding where the breakpoints should be checked is best determined while writing the code though they can be added later making your module more . This, of course, doesn't stop you from using the debugger in a normal fashion, with or without the help of these "code called" breakpoints

In your module

        use Debug::Mixin ;
        ...
        $DB::single = 1 if(Debug::Mixin::IsDebuggerEnabled() && Debug::Mixin::CheckBreakpoint(%debug_data)) ;

At the cost of a subroutine call, you get checking of breakpoints at a position you deem strategic and the possibility to stop in the debugger if any of the breakpoints actions flag to stop.

I'd check if the cost has a real impact before trying to reduce it. you could write:

        use Filter::Uncomment GROUPS => [ debug_mixin => ['DM'] ] ;
        use Debug::Mixin ;
        ...
        ##DM $DB::single = 1 if(Debug::Mixin::IsDebuggerEnabled() && Debug::Mixin::CheckBreakpoint(%debug_data)) ;

You'll now pay only if you are actively using Debug::Mixin to debug your application/modules. The only cost being the filtration of the code if, and only if, you decide to uncomment. if you don't, the cost is practically zero.

Have I used this in any real project, PBS on CPAN, and it did really help a lot with very complex problems. Mainly because it let me run debugging very fast but also because the check point were put in the code before I had any problems saving me time to find out where I should place them.

DEBUG SESSION

script Debug::Mixin aware

        perl -d script.pl --argument_loading_plenty_breakpoints

script doesn't have to be aware of modules debugging facilities, only modules using Debug::Mixin have to

        perl -d -MDebug::Mixin='LoadBreakpointsFiles=file' script.pl

        > Using Debug::Mixin banner, use 'dm_help' for Debug::Mixin help.
        
        > dm_help
          dm_subs()                     list and run debugging subs
          dm_load(@files)               load breakpoints files
          
          # all breakpoints functions take a regex
          dm_bp(qr//)                   list breakpoints
          dm_activate(qr//)             activate breakpoints
          dm_deactivate(qr//)           deactivate breakpoints
          dm_use_debugger(qr//)         jump in debugger
          dm_dont_use_debugger(qr//)    jump in debugger only if a breakpoint action says to
        
        > run part of the program ...
        
        > Breakpoints display information (eventually interacting with the user)
        
        > stop at a breakpoint, if local commands are available interact with the user, display their documentation

SUBROUTINES/METHODS

import

Called for you by Perl

SetupElement

Private function

EnableDebugger

Globally Enables or disables this module.

        Debug::Mixin::EnableDebugger(0) ;
        Debug::Mixin::EnableDebugger(1) ;

IsDebuggerEnabled

Returns the state of this module.

        my $status = Debug::Mixin::IsDebuggerEnabled() ;

AddBreakpoint

        use Debug::Mixin ;
        
        AddBreakpoint
                (
                NAME    =>   'add dependencies'
                
                FILTERS =>
                        [
                        sub 
                                {
                                my (%filter) = @_ ;
                                $filter{ARGS}{TYPE} eq 'DEPEND' ; # true will enable the actions
                                }
                        ]
                        
                ACTIONS =>
                        [
                        sub 
                                {
                                my (%filter) = @_ ;
                                
                                print DumpTree $filter{ARGS}{COMPLEX_ELEMENT} ;
                                
                                return JUMP_TO_DEBUGGER # want to jump into debugger
                                }
                        ]
                        
                DEBUGGER_SUBS =>
                        [
                                {
                                NAME        => 'CheckDependencyMatrix',
                                ALIASES     => [qw(dm_cdm cdm)],
                                DESCRIPTION => "a short description of what this sub is for",
                                HELP        => "a long, possibly multi line description displayed"
                                                . "when the user needs it",
                                SUB         => sub{},
                                }
                        ]
                        
                LOCAL_STORAGE => {}
                
                ALWAYS_USE_DEBUGGER => 0 # let subs decide if we jump in the debugger
                ACTIVE => 1
                )

Breakpoint elements

  • NAME

    The name of the breakpoint, you can remove and otherwise manipulate breakpoints by name.

  • FILTERS

    Used to enable or disable all the actions with a single check. FILTERS is a list of sub references. The references are passed the argument you pass to CheckBreakpoints and :

    • DEBUG_MIXIN_BREAKPOINT

      A reference to the breakpoint.

    • DEBUG_MIXIN_CALLED_AT

      a hash containing the file and line where CheckBreakpoints was called.

  • ACTIONS

    ACTIONS is a list of sub references. All the subs are run. All debugging functionality (ex: activating or adding breakpoints) are available within the subs.

  • DEBUGGER_SUBS

    List of functions available, at the time the breakpoint matches, when running under the debugger. Debug::Mixin will present you with the list of local functions and allow you to run any of the functions.

    each entry must have follow the following format

            {
        NAME        => 'CheckDependencyMatrix',
        ALIASES     => [qw(dm_cdm cdm)],
        DESCRIPTION => "a short description of what this sub is for",
        HELP        => "a long, possibly multi line description displayed"
                        . "when the user needs it",
        SUB         => sub{},
        }

  • ALWAYS_USE_DEBUGGER

    If the breakpoint is active, CheckBreakpoints will always return true.

  • ACTIVE

    The breakpoint actions will only be called if ACTIVE is set.

  • LOCAL_STORAGE

    A user storage area within the breakpoint. You can store and manipulate it as you wish. You must use this area as Debug::Mixin only allows certain fields in a breakpoint.

    This item can be manipulated through the breakpoint reference passed to filters and actions.

A warning is displayed if you override an existing breakpoint. A breakpoint creation history is kept.

CheckBreakPointDefinitions

Checks the validity of the user supplied breakpoint definitions. Croaks on error.

LoadBreakpointsFiles

Evaluates a perl script. The main purpose of the script is to define breakpoints but the script can also query Debug::Mixin and change existing breakpoints or run any perl code deemed fit.

Croaks on error, return(1) on success.

RemoveBreakpoints

Removes one or more breakpoint matching the name regex passed as argument. A warning is displayed for each removed breakpoint.

        Debug::Mixin::RemoveBreakpoints(qr/dependencies/) ;

Returns the number of removed breakpoints.

RemoveAllBreakpoints

Removes all breakpoints. No message is displayed.

        Debug::Mixin::RemoveAllBreakpoints();

ListDebuggerSubs

List all the debugger subs registered by modules loading Debug::Mixin on STDOUT.

ListBreakpoints

List, on STDOUT, all the breakpoints matching the name regex passed as argument.

GetBreakpoints

Returns a reference to all the breakpoints. Elements are returned in the insertion order.

Use this only if you know what you are doing.

ActivateBreakpoints

Activate all the breakpoints matching the name regex passed as argument.

Only active breakpoints are checked by Debug::Mixin.

DeactivateBreakpoints

Deactivate all the breakpoints matching the name regex passed as argument.

Only active breakpoints are checked by when you call CheckBreakpoints.

ActivateAlwaysUseDebugger

Sets all breakpoints matching the name regex passed as argument to always jumps to the perl debugger.

DeactivateAlwaysUseDebugger

Sets all breakpoints matching the name regex passed as argument, to never jumps to the perl debugger.

CheckBreakpoints

Check a user state against all registered breakpoints. Returned value tells caller if it should jump into the debugger.

        if(Debug::Mixin::IsDebuggerEnabled())
                {#bp local subs


                %debug_data = 
                        (
                          # user data passed to the breakpoint actions
                          TYPE           => '...'
                        , COMMENT        => '...'
                        , ...
                        ) ;
                        
                $DB::single = 1 if(Debug::Mixin::CheckBreakpoint(%debug_data)) ;
                }

HandleBreakpointSubInteraction

Private subroutine handling user interaction in a debugger session.

dm_help

Displays the commands made available by Debug::Mixin in the debugger.

dm_subs

List all the available debugging subs and interacts with the user to run them.

Output

Prints the passed arguments

TO DO

More test, testing the module through the perl debugger's automation.

BUGS AND LIMITATIONS

None so far.

AUTHOR

        Khemir Nadim ibn Hamouda
        CPAN ID: NKH
        mailto:nadim@khemir.net

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SUPPORT

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

    perldoc Debug::Mixin

You can also look for information at:

SEE ALSO

Filter::Uncomment