/ 
Fred-Fish-DBUG-2.04
River stage zero No dependents
/ Fred::Fish::DBUG::OFF

NAME

Fred::Fish::DBUG::OFF - Fred Fish Stub library for Perl

SYNOPSIS

 use Fred::Fish::DBUG  qw / OFF /;
   or
 require Fred::Fish::DBUG;
 Fred::Fish::DBUG->import (qw / OFF /);

Depreciated way.
  use Fred::Fish::DBUG::OFF;
    or
  require Fred::Fish::DBUG::OFF;

DESCRIPTION

Fred::Fish::DBUG::OFF is a pure Perl implementation of the C/C++ Fred Fish macro libraries when the macros are turned off! It's intended to be a pure drop and replace to the Fred::Fish::DBUG::ON module so that any module that is uploaded to CPAN doesn't have to have their module code writing to fish when used by an end user's program that also uses the Fred::Fish::DBUG module.

Using this module directly has been depreciated. You should be using Fred::Fish::DBUG instead. See that module on how to disable fish for your module.

When fish has ben disabled (turned off) most of the functions are overridden with stubs or do minimal work to avoid breaking your code that depend on side effects. But overall this module does as little work as possible.

The undocumented validation methods used by the t/*.t test cases don't work for Fred::Fish::DBUG::OFF. So those test scripts must detect that these undocumented functions are broken and handle any checks appropriately.

FUNCTIONS IN Fred::Fish::DBUG BUT NOT IN Fred::Fish::DBUG::OFF.

There are several functions listed in the POD of the 1st module that doesn't show up in the POD of the 2nd module.

This was by design. All the missing functions do is automatically call the corresponding function in Fred::Fish::DBUG::ON for you. Since this module inherits the missing functions from Fred::Fish::DBUG::ON.

The exposed constants falls into this category so your code won't break when swapping between the two modules in the same program.

So feel free to always reference the POD from Fred::Fish::DBUG and/or Fred::Fish::DBUG:::ON when using any of the DBUG modules.

SWAPPING BETWEEN FISH MODULES

There is a fairly simple way to have fish available when you run your test suite and have it always disabled when an end user runs code using your module. this is done via:

use Fred::Fish::DBUG qw / on_if_set FISH /;

This way your module will only use fish if someone sets this environment variable (Ex: FISH) before your module is sourced in. Such as in your test scripts when you are debugging your code. When anyone else uses your module it won't write to the fish logs at all, even if they are also using the DBUG module in their code base. In most cases they are not interested in seeing traces of your module.

Another reason for doing this is that this module is significantly faster when run in OFF mode than when run in the ON mode. This is true even when logging is turned off. The more your module writes to fish, the better the performance gain.

FUNCTIONS

DBUG_PUSH ( [$file [, %opts]] )

This stub does nothing since fish can't be turned on for this module.

DBUG_POP ( )

This stub does nothing since fish can't be turned on for this module.

DBUG_ENTER_FUNC ( [@arguments] )

This stub just returns the name of the calling function. It won't honor the strip option in the return value.

DBUG_ENTER_BLOCK ( $name [, @arguments] )

This stub just returns the $name passed to it. It won't honor the strip option in the return value.

DBUG_PRINT ( $tag, $fmt [, $val1 [, $val2 [, ...]]] )

This function is usually a no-op unless you are examining the return value. In that case it will return the formatted string the same as it does for Fred::Fish::DBUG::ON::DBUG_PRINT.

It also doesn't honor the delay request from DBUG_PUSH since it will never write to the fish file.

DBUG_RETURN ( ... )

Returns the parameter(s) passed as arguments back to the calling function. Since this is a function, care should be taken if called from the middle of your function's code. In that case use the syntax: "return DBUG_RETURN( value1 [, value2 [, ...]] );".

It uses Perl's wantarray feature to determine what to return the the caller. IE scalar mode (only the 1st value) or list mode (all the values in the list). Which is not quite what many perl developers might expect.

EX: return (wantarray ? (value1, value2, ...) ? value1);

DBUG_ARRAY_RETURN ( @args )

A variant of "DBUG_RETURN()" that behaves the same as perl does natively when returning a list to a scalar. IE it returns the # of elements in the @args array.

It always assumes @args is a list, even when provided a single scalar value.

DBUG_VOID_RETURN ( )

Just a void return stub. If called in the middle of your function, do as: "return DBUG_VOID_RETURN();".

DBUG_RETURN_SPECIAL ( $scalar, @array )

This DBUG_RETURN variant allows you to differentiate between what to return when your function is called in a scalar context vs an array context vs void context.

If called in an array context, the return value is equivalent to DBUG_RETURN (@array).

If called in a scalar context, the return value is equivalent to DBUG_RETURN ($scalar). With a few special case exceptions.

    Special case # 1: If $scalar is set to the predefined constant value DBUG_SPECIAL_ARRAYREF, it returns the equivalent to DBUG_RETURN (\@array). Feel free to modify the contents of the referenced array, it can't hurt anything. It's a copy.

    Special case # 2: If $scalar is set to the predefined constant value DBUG_SPECIAL_COUNT, it returns the equivalent to DBUG_RETURN (scalar (@array)), the number of elements in the array.

    Special case # 3: If $scalar is set to the predefined constant value DBUG_SPECIAL_LAST, it returns the equivalent to DBUG_RETURN ($array[-1]), the last element in the array.

    Special case # 4: If $scalar is a CODE ref, it returns the equivalent to DBUG_RETURN (scalar ($scalar->(@array))).

If called in a void context, the return value is equivalent to DBUG_VOID_RETURN ().

DBUG_LEAVE ( [$status] )

This function terminates your program with a call to exit(). It expects a numeric parameter to use as the program's $status code. If not provided, it assumes an exit status of zero!

DBUG_CATCH ( )

This stub does nothing since fish can't be turned on for this module.

DBUG_PAUSE ( )

This stub does nothing since fish can't be turned on for this module.

DBUG_MASK ( @offsets )

This stub does nothing since fish can't be turned on for this module.

DBUG_MASK_NEXT_FUNC_CALL ( @offsets )

This stub does nothing since fish can't be turned on for this module.

DBUG_FILTER ( $lvl )

This stub does nothing except return the current level and the passed $lvl. You can't change the level while using this module.

DBUG_CUSTOM_FILTER ( @levels )

This stub does nothing since fish can't be turned on for this module.

DBUG_CUSTOM_FILTER_OFF ( @levels )

This stub does nothing since fish can't be turned on for this module.

DBUG_SET_FILTER_COLOR ( $level [, $color] )

This stub always returns 0 since fish can't be turned on for this module.

DBUG_ACTIVE ( )

This stub always returns 0 since fish can't be turned on for this module.

DBUG_EXECUTE ( $tag )

This function always returns 0 since fish can't be turned on for this module.

DBUG_FILE_NAME ( )

Always returns the empty string since fish can't be turned on for this module.

DBUG_FILE_HANDLE ( )

Always returns undef since fish is never turned on with this module.

DBUG_ASSERT ( $expression [, $always_on [, $msg]] )

This function works similar to the C/C++ assert function except that it can't tell you what the boolean expression was.

This function is a no-op unless $always_on is true.

So if the $expression is false, and $always_on is true, it will write to STDERR the assert message and abort your program with an exit status code of 14. Meaning this exit can't be trapped by eval.

DBUG_MODULE_LIST ( )

This stub does nothing since fish can't be turned on for this module.

CREDITS

To Fred Fish for developing the basic algorithm and putting it into the public domain! Any bugs in its implementation are purely my fault.

SEE ALSO

Fred::Fish::DBUG - The controling module which you should be using instead of this one.

Fred::Fish::DBUG::ON - The live version of the OFF module.

Fred::Fish::DBUG::TIE - Allows you to trap and log STDOUT/STDERR to fish.

Fred::Fish::DBUG::Signal - Allows you to trap and log signals to fish.

Fred::Fish::DBUG::SignalKiller - Allows you to implement action DBUG_SIG_ACTION_LOG for die. Really dangerous to use. Will break most code bases.

Fred::Fish::DBUG::Tutorial - Sample code demonstrating using DBUG module.

COPYRIGHT

Copyright (c) 2016 - 2024 Curtis Leach. All rights reserved.

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