Fred-Fish-DBUG
view release on metacpan or search on metacpan
In that case it's still fairly simple and still requires code in your BEGIN
block. The requirement is that you must defer loading your module until after
the %ENV value has been set! In that case you have three options.
Option 1:
BEGIN
{
$ENV{some_special_variable} = 1;
eval "use your_module_that_uses_fish";
if ( $@ ) {
die ("Can't load module: your_module_that_uses_fish\n");
}
}
Option 2: - Using require/import to do it.
BEGIN
{
$ENV{some_special_variable} = 1;
eval {
require your_module_that_uses_fish;
your_module_that_uses_fish::import ();
};
if ( $@ ) {
die ("Can't load module: your_module_that_uses_fish\n");
}
}
Option 3: - Adding a minimum version check.
BEGIN
{
$ENV{some_special_variable} = 1;
eval {
require your_module_that_uses_fish;
your_module_that_uses_fish->import ();
your_module_that_uses_fish->VERSION ( 2.03 );
};
if ( $@ ) {
die ("Can't load module: your_module_that_uses_fish\n");
}
}
# -----------------------------------------------------------------------------
It's that simple! You can now dynamically control using Fish differently
between different modules in your code base. Mix and match what's written to
fish to your heart's content!
# =============================================================================
# DEVELOPER NOTE: (So I don't forget this again)
# =============================================================================
While I attempted to write good test cases, they can all pass and still
result in the module having issues. Since what is important is what is actually
written to the log file! So it's important for the developer (me) to remember
to actually look at the fish logs generated sometimes.
End users of this module (you) do not have to do this. You can assume if all
the test cases pass it's good to use and install!
# =============================================================================
# C/C++ Macros vs Perl Functions
# -----------------------------------------------------------------------------
# C/C++ Macro Name | Perl Function Name | Comments
# -----------------+----------------------+------------------------------------
DBUG_PUSH | DBUG_PUSH | Used to turn Fish on.
DBUG_ENTER | DBUG_ENTER_FUNC | Tracks entering a function.
--- | DBUG_EBTER_BLOCK | Tracks entering a sub-block of code.
DBUG_PRINT | DBUG_PRINT | Writes message to fish logs.
DBUG_RETURN | DBUG_RETURN | Tracks one or more return values.
--- | DBUG_ARRAY_RETURN | Handles returns of lists to scalars.
--- | DBUG_RETURN_SPECIAL | Special case of DBUG_RETURN.
DBUU_VOID_RETURN | DBUG_VOID_RETURN | Tracks func return with no value.
DBUG_LEAVE | DBUG_LEAVE | Terminates your program.
DBUG_EXECUTE | DBUG_EXECUTE | Returns TRUE if writing to fish.
DBUG_FILE | DBUG_FILE_HANDLE | Return's the File Handle of fish.
DBUG_IN_USE | DBUG_ACTIVE | Returns TRUE if writing to fish.
DBUG_ASSERT | DBUG_ASSERT | If true & fish on, abort program.
# -----------------------------------------------------------------------------
# Not one of the C/C++ Macros, but added to support Perl functionality.
# -----------------------+-----------------------------------------------------
DBUG_CATCH | Logs trapped exception.
DBUG_PAUSE | Temporarily turns off fish logs.
DBUG_MASK | Masks func return values written to fish.
DBUG_MASK_NEXT_FUNC_CALL | Masks func argument written to fish.
DBUG_FILTER | Filter what's written to fish.
DBUG_CUSTOM_FILTER | Filter what's written to fish.
DBUG_CUSTOM_FILTER_OFF | Filter what's written to fish.
DBUG_SET_FILTER_COLOR | Use color it the fish logs.
DBUG_FILE_NAME | Returns the file name of the fish log.
DBUG_MODULE_LIST | Writes to fish all perl modules used by your prog.
DBUG_TIE_STDERR | Traps STDERR & writes it to fish.
DBUG_TIE_STDOUT | Traps STDOUT & writes it to fish.
DBUG_UNTIE_STDERR | Breaks the STDERR trap.
DBUG_UNTIE_STDOUT | Breaks the STDOUT trap.
# -----------------------------------------------------------------------------
# NOTE: Trap signals with care. On some OS, such as Windows, trapping
# signals can be flakey! But it's extremely useful on Unix.
# ----------------------------------------------------------------------------
DBUG_TRAP_SIGNAL | Writes the tapped signal to fish.
DBUG_FIND_CURRENT_TRAPS | Tells if a signal is currently trappable.
DBUG_DIE_CONTEXT | Gives the context of the trapped signal.
# -----------------------------------------------------------------------------
# C/C++ Macro Name, but not relevant in Perl
# -----------------------------------------------------------------------------
DBUG_POP
DBUG_PROCESS
DBUG_SETJMP
DBUG_LONGJMP
DBUG_DUMP
DEBUGGER_OFF
DEBUGGER_ON
DBUG_LOCK_FILE
DBUG_UNLOCK_FILE
DBUG_my_pthread_mutex_lock_FILE
DBUG_my_pthread_mutex_unlock_FILE
# ----------------------------------------------------------------------------
# NOTE: The C/C++ macros implemented it's options via ugly flags in DBUG_PUSH.
# So for Perl I used more user friendly hash tags instead. The list of
# options are Perl specific.
# ----------------------------------------------------------------------------
# Unless otherwise specified, the default is off! (0)
# The DBUG_PUSH() options are:
# 1) append - 1/0 Open fish log in append mode.
# 2) autoflush - 1/0 (defaults to 1 if not present)
# 3) autoopen - 1/0 Keeps opening & closing the fish file between
# DBUG writes to fish. Very, very, very slow!
# 4) off - 1/0 Treat call to DBUG_PUSH() as a no-op, leaving
# fish turned off. Overrides all other options!
# I usually set this flag's value via a command line
# option to turn fish on and off, rather than making
# the call do DBUG_PUSH() itself conditional. But
# both ways work.
# 5) filter - Alternate way to implement DBUG_FILTER().
# 6) kill_end_trace - 1/0 Disable writing to fish for END blocks after a
# call to DBUG_LEAVE or die or exit!
# 7) who_called - 1/0 Prints out the caller info for each call to
# DBUG_ENTER_FUNC() & DBUG_ENTER_BLOCK().
# Does same for DBUG_PRINT().
# 8) multi - 1/0 Use for all multi-threaded Perl programs and/or
# forked processes. For threads it will prefix
# each line with $$-tid() to tell which line
# goes with which thread. But if the PID changes
# it will do this by appending '/xx' where xx is
# usually the last 2 digits of the PID.
# 9) limit - 1/0/-1 Limit to child/parent thread. (parent/all/child)
# 10) chmod - (default 0644) File permissions to use on the fish file.
# Overrides any UMASK settings.
# 11) before - 1/0 Set to true if you put your DBUT_ENTER_FUNC call
# before your call to DBUG_PUSH & you still want
# your func printed in fish afterwards.
# 12) strip - 1/0 Strip out the module name of functions written to
# fish.
# 13) delay - xx (Default 0) Implements a delay after each call
# to DBUG_PRINT() that writes to the fish file.
# Recommend having Time::HiRes installed to use.
# This allows using fractions of a second.
# 14) elapsed - 1/0 Gives the amount of time spent inside a function
# on return. Installing Time::HiRes allows tracking
# to fractions of a second.
# 15) keep - 1/0/code_ref Only keep the fish logs when your program
# terminates under certain conditions. (1) if you
( run in 0.646 second using v1.01-cache-2.11-cpan-75ffa21a3d4 )