# The Change Log for Fred::Fish::DBUG
# and Fred::Fish::DBUG::ON
# and Fred::Fish::DBUG::OFF
# The basic algorithm is in the public domain and this implementation has been
# customized to support Perl features while remaining faithful to the original
# intent.
# ------------------------------------------------------------------------
# Developer's Note:
# Remember to run "full_developer_test.pl" for the deepest possible
# testing of this module. Everyone else only needs to do "make test".
# ------------------------------------------------------------------------
# TODO:
# 1) Need test case of forked processes using threads. Skip test
# if threads/forks are not supported!
# 2) Need test case of threads forking processes! (reverse of
# previous test!)
# 3) Need test case with multiple packages in one file which use different
# on/off settings.
Version - YYYY/MM/DD
---------------------
2.09 2024-12-06 08:30:00
- Success! It now passes all CPAN Testers tests for all versions of perl.
- Fixed some POD typos.
- Added Fred::Fish::DBUG::Test to handle common Test::More functions so that
info is written to fish as well.
- t/15-basic-test-and-helper.t replaced t/15-basic-helper.t
- t/*.t - Modified to use Fred::Fish::DBUG::Test. Simplified a lot of code.
- helper1234.pm - removed a lot of unneeded code due to the above changes.
- t/57-delay-elapsed-slow-if-fish-on.t - Decreased the delay for each fish
write from 2.5 sec to 1.5 sec (the minimum for the test to work). Done
since a CPAN Tester forced a timeout on this slow running test. If it
sill fails it won't be fixed, since it isn't really a fatal error. Just
anoying.
2.08 2024-10-09 08:30:00
- Finally found the bug! The debugging helper methods in DBUG.pm was giving
credit to the wrong file for who was sourcing in the module. So when asked
it couldn't find a match. Function _find_key() was corrected.
- Fixed all the test cases after t/15 to do "use helper1234" rather than
use_ok since "make test" aborts at t/15 if there are issues, so we don't
need to repeat this test over & over again.
- Backed out the above fix for the 3 multi-thread tests.
2.07 2024-10-08 08:30:00
- Added more tests to t/15-basic-help.t to help narrow down the issue.
If it doesn't help I'll make v5.14.0 the min version of perl.
- Stubbed out min version of perl test. Using 5.8.8 for now, easy to upgrade
to 5.14.0 later.
2.06 2024-10-04 08:30:00
- Rats, it didn't fix things, pre-version 5.14.0 still broken.
helper1234 now loaded directly via use in t/15-basic-help.t
If this fix works, I'll fix all the other t/*.t progs in the next release.
2.05 2024-10-01 08:30:00
- In researching why certain CPAN Testers fail, it looks like use_ok() inside
of a BEGIN block has issues with BEGIN/import() executing in different order
for different versions of perl. I can't test directly, but my fix is to
put the use_ok('helper1234) in one BEGIN block & call any helper1234 funcs
in a separate BEGIN block. Using t/15-basic-help.t as a test case.
If this fix works, I'll fix all the other t/*.t progs in the next release.
2.04 2024-09-27 08:30:00
- Added a delay log file whenever the delay option was used in a test case.
- Modified full_developer_test.pl.src to take delays into account.
- Fixed bug in Tutorial.pm Example # 6. Also moved required to end of file.
Fixed typo in package name that broke the links.
- Fixed the POD NAME section in all *.pm files to follow the correct naming
standards.
- Fixed t/21-return_simple.t to also test that wantarray keyword works as
expected. Since so much logic depends on it.
- CPAN Tester hack, didn't like me calling dbug_level() from BEGIN ?
So added test in DBUG.pm to verify since I can't reproduce it (-100).
(used to verify CPAN Tester issue described more fully in v2.05)
- Updated the POD NAME for all *.pm files to be fully qualified.
- Depreciate DEBUG.pm & Log.pm, now just POD stubs.
- Fixed unexpected warning error encountered by a CPAN tester on test case
t/70_multi_thread-test.t
2.03 2024-08-05 08:30:00
- Split Signal logging from ON.pm to Signal.pm, required an update to most
test scripts as well.
- Split TIE logging from ON.pm to TIE.pm, required an update to
t/62-tie_test.t as well.
- Updated copyright in all *.pm files to 2024.
- Added DBUG_SPECIAL_LAST option to DBUG_RETURN_SPECIAL().
- Added new test case t/25-return_special_last.t
- Added DBUG_ARRAY_RETURN ().
- Added new test case t/26-return_array.t
- Cleaned up some POD text.
2.02 2021-04-16 08:30:00
- Updated the copyright to 2021 in all files.
- Major updates to the POD in all *.pm files dealing with changes made
in the previous release.
- Promoted a lot of ok() calls to is() calls in the t/*.t programs.
- Added is2() to helper1234.pm, which writes output of is() to fish.
2.01 2020-09-23 08:30:00
- Major refactoring to make swapping between ON/OFF modules more intuitive
without requiring the end user to use non-standard loading of this module.
It now uses "use Fred::Fish::DBUG qw / mode /;" instead of using special
logic in your program's BEGIN block. But the old 1.xx style still works,
it now just looks very strange & creepy.
- Redid all the t/*.t test programs to take advantage of the new logic.
- Added a few new t/*.t test programs to deal with dual inheritance issues
to verify having ON in one file is compatible with having OFF in another.
1.10 2020-03-03 08:30:00
- More minor speed enhancements.
- Fixed DBUG_PUSH() typo for chmod option detection.
- Now if fish is turned off for a masked arg/return value it will set
the masking count to -1 instead of 0. Making the validation done by
t/off/helper1234.pm more accurate. (-1 means unknown count.)
- Fixed DBUG_RETURN() filtering issue. Where DBUG_FILTER_LEVEL_FUNC
is off & DBUG_FILTER_LEVEL_ARGS is on with arguments to print.
- Fixed bug in test funcs using undefined hints.
Never Released this version.
1.09 2020-02-20 08:30:00
- Updated the copyright to 2020 on all files.
- Fixed keep/kill_end_trace combination where the keep flag wasn't being
honored at all.
- Fixed issue with "kill_end_trace" wasn't being honored if exit() instead of
DBUG_LEAVE() was called. (or even if neither was called) In this case at
least some END blocks will still write to fish since we were never given a
chance to prevent it. But now the DBUG END block won't print out anything.
- Changed DBUG_LEAVE() in OFF.pm from a stub to have it call
_dbug_leave_cleanup() so that other modules using DBUG will terminate
cleanly afterwards so we won't hit one of the above bugs.
- Fixed some POD text in DBUG.pm
- Fixed some POD text in Tutorial.pm
- Fixed issue with PAUSE on & didn't call DBUG_LEAVE.
- Fixing so many END issues I broke down and had END call DBUG_LEAVE if it
hadn't already been called. Had to tweak DBUG_LEAVE to allow this. But
at least it centralized a lot of code.
- Fixed so sub-package Fred::Fish::DBUG::TIE is hidden from PAUSE per same
fix in Try::Tiny.
- Modified _indent_multi() to 1st check if option multi was used instead of
just falling through.
- t/25-eval_auto_balance.t - Added test cases demonstrating when DBUG_CATCH
must be used to avoid looking like your code is recursive when it isn't.
- Added option allow_utf8 to allow writing utf8/wide chars to a fish file.
Added test case t/80-foreign_language.t to test out, using Date::Language
for a source of foreign language text that uses UTF8.
- Speed enhancements, speeded up by changing most calls to _filter_on() to
calls to DBUG_EXECUTE() & other optimizations for when fish is turned off.
Never Released this version.
1.08 2019-10-31 08:30:00
- Reordered the order the private methods appeared in DBUG, no logic changes,
so that all the Signal related methods were together at the end of the
module.
- Removed the unused _diff_ test function. No longer needed.
- Removed a depreciated Signal related BEGIN block as no longer needed since
it prevented the code reordering.
- Fixed bugs in _dbug_called_by() as new test cases came up. Now will never
return a Fred::Fish::DBUG location. It's one of the reasons why internal
calls to print from this module never honor the option who_called.
- Reorganized the parameters to DBUG_TIE_... functions.
- Fixed t/52-tie_test.t to use the new order.
- Module DBUG::TIE now uses _dbug_hack to control the fish printing.
- Replaced DBUG_REGISTER() with DBUG_MODULE_LIST().
- Merged Fred::Fish::DBUG::TIE back into the main module now that its working.
No real reason for keeping it separated any more. Especially when the
previous release was never made public. Also did quite a number of bug
fixes. Mostly to break infinite recursion situations.
- Changed when the callback is called against a tied file handle. It's now:
1) Write to fish.
2) "Chain the tie" or "write to STDOUT/STDERR" if no tie. It assumes the
chained tie will handle the write to STDOUT/STDERR.
3) Call the callback function.
- Made the same changes to t/52-tie_test.t's tie test.
- Fixed full_developer_test.pl.src to allow it to run individual test progs
in the "t" sub-directory. "prove" always reports failure if the prog is
located someplace else. So in those cases it uses "perl" instead.
- full_developer_test.pl.src now makes sure the make variant selected actually
works before returning it. (dmake vs gmake issue in Strawberry Perl)
Makes it easier to add new make variants in the future.
- No longer allows you to make the TIE chain to itself.
- More fixes to Tutorial.pm to clarify some of the examples.
- Fixed so option "kill_end_trace" works for all signals when die itself
wasn't being trapped. Still a hole if trapped by eval and die is rethrown.
Or if trap die via module & later manually reset it.
- Fixed duplicate Ha Ha messages when trapping DIE & just trying to log it.
- Added simulate_windows_signal() to helper1234.pm to better simulate
generating signals on non-unix platforms. Then updated the t/*.t programs
to use it.
- Added Fred::Fish::DBUG:SignalKiller as a helper module. Not recommended
for general use. Just written to prove why you don't want to do this.
- Added new test case t/27-SignalKiller.t
- Added new option "no_addresses" for DBUG_PUSH(). Allows for easier
comparison of fish logs using utilities like Unix's diff command.
Never Released this version.
1.07 2019-06-26 08:30:00
- Added Fred::Fish::DBUG::TIE to the package. So we can now trap messages
written to STDERR and STDOUT and log them to fish as well.
- Added test cases t/05-basic-tie.t and t/52-tie_test.t
- If the exit status didn't get printed in DBUG_LEAVE, it now gets printed
in the END block using a different filter level.
- Added DBUG_FILTER_LEVEL_STD as a new filter level to allow filtering
these trapped messages from STDOUT & STDERR.
- Added DBUG_CUSTOM_FILTER & it's inverse DBUG_CUSTOM_FILTER_OFF to allow
users to define their own customized filtering.
- Fixed _filter_lvl() to fully allow the DBUG_FILTER_LEVEL_... constants
when setting the filter level in all cases.
- Now calls _filter_on() all over the place internally instead of using
equivalent tests. Required so custom filtering would work.
- Added Fred::Fish::DBUG::Tutorial to the package. Gives a lot of
examples to make learning to use this module easier.
- Added t/06-basic-tutorial.t to verify no syntax issues.
- Fixed DBUG_EXECUTE to return -1 if writing to the screen like DBUG_ACTIVE
does.
- Added helper function _dbug_print_pkg_tag() for internal prints and then
modified the code to use it.
- Added _dbug_hack() so my test cases and helper modules can reset internal
configuration data before running commands depending on dynamic config
changes. Also rewrote _dbug_forward_trapped_signal() to use it to make
it more reliable.
- Fixed so signals at least print out something even when pause was turned on.
But filtering can still suppress messages. Mostly a consistency fix. Before
some signals did and others didn't.
Never Released this version.
1.06 2019-06-03 08:30:00
- More POD changes & typo fixes in DBUG.pm & OFF.pm.
- Fixes to examples in README.
- Fixes to trap signal logic.
- Added 5th flag to DBUG_DIE_CONTEXT.
- Retired DBUG_EVAL in favor of DBUG_CATCH.
*** Makes module Incompatible with the previous releases! ***
- Fixed to auto-balance the function/return values after an eval/try event
was trapped without the need to call DBUG_CATCH() yourself. Making this
call optional.
- Added t/25-eval_auto_balance.t to test this logic out!
- Fixed bug in DBUG_PUSH() handling the "keep" option.
Never Released this version.
1.05 2019-04-12 08:30:00
- Added POD to DBUG.pm describing issues with using goto.
- Clarified some masking POD text.
- Fixed _dbug_log_signal() to prevent circular DBUG signal handlers.
- DBUG_ENTER_BLOCK() now supports arguments the same way DBUG_ENTER_FUNC()
does.
- Updated all t/*.t programs to add the arguments to DBUG_ENTER_BLOCK if
appropriate. (Used to simulate it in the tests if needed.)
- Renamed test t/47-*.t since it's so slow when fish is turned on.
- Added t/29-AUTOLOAD-test.t to help demonstrate fish logging issues
caused by the use of goto's. And using AUTOLOAD was the easiest way
to demonstrate the problems and solutions.
- Added test module t/off/helper1234.pm to centralize common tasks and make
it easier to make significant changes to the module. Also centralized
the hooks into the module for gathering validation results.
- Updated all test progs to use t/off/helper1234.pm to standardize any
initialization and reporting on results.
- Modified DBUG.pm to no longer trap DIE & WARN by default and updated
the pod to say so. Also no longer allows undef for selecting default
actions. There are no longer any valid defaults, just recommendations.
- Now allows DIE & WARN to perform all the same actions as the other
signals. Required a significant rewrite of the signal handling funcs.
- Changed how DBUG_DIE_CONTEXT worked. Also removed all it's old
constants since no longer used.
- Added new test case using Tiny::Try to verify it works same as eval
as far as the fish logs are concerned! Required a hack in DBUG to
report the who_called info with DBUG_ENTER_FUNC() to report entry
was in the try/catch/finally blocks instead of Tiny/Try.pm. It may
not work this way with all the other Try modules.
- Implemented option "keep".
- Added test_object.pm to allow testing of special object functions
with who_called turned on for t/30-func_who_called_trace.t.
1.04 2019-03-05 08:30:00
- Fixed which_make() windows bug in "full_developer_test.pl.src".
Then modified it to tell which 'make' variant was selected.
Next made it more modular and easier to support.
- Added color support to DBUG.pm via DBUG_SET_FILTER_COLOR().
Accepts both the color names in strings & the color macros.
- Added color testing to t/40-filter-tests.t
- Also created t/45-filter-macro-tests.t so could test using the color macros.
- Did away with DBUG_BEGIN() & replaced with DBUG_RETURN_SPECIAL() once
it became obvious that not all methods in a module would want to always
use the same mapping logic. Greatly simplified DBUG_RETURN().
- Modified the test cases to follow this new logic with DBUG_RETURN_SPECIAL().
- Merged DBUG_MASK_HASH() into DBUG_MASK() and then removed DBUG_MASK_HASH().
- Modified the test cases to follow the new logic for DBUG_MASK().
- Allowed DBUG_FILTER_LEVEL_... constants to be used as tags in DBUG_PRINT().
Requested but not really recommended. Using text tags makes it a more
readable fish log file.
- Fixed bug in _dbug_called_by() in DBUG.pm & put into OFF.pm as well
so can be used by test programs. Also changed what arguments to expect.
- Added direct test for _dbug_called_by() to t/30-func_who_called_trace.t
to help with debugging the "who_called" option.
- Fixed all test cases to correctly reference non-exposed functions using
"can". Since the module name is a variable.
- Added "limit" option to DBUG_PUSH() method in DBUG.pm.
- Added "strip" option to DBUG_PUSH() method in DBUG.pm.
- Added "delay" option to DBUG_PUSH() method in DBUG.pm.
- Added "elapsed" option to DBUG_PUSH() method in DBUG.pm.
- Fixed "detach" threads issue in the test scripts. They now wait until all
threads complete so don't leave behind scratch files owned by threads killed
when the main thread terminates. Forked process don't have this problem.
- Now uses DBUG_ACTIVE() & DBUG_EXECUTE() internally instead of hard coding
the equivalent tests all over the place.
- DBUG_ENTER_FUNC() & DBUG_RETURN() now convert any CODE references into
their function names before printing out the argument/return list. Or
\&__ANON__ for anonymous functions.
- DBUG_PRINT() now does this CODE reference conversion as well for individual
arguments. But not if buried inside a string.
- DBUG_ENTER_BLOCK() now uses ">>${name}" instead of ">${name}" to distinguish
it from DBUG_ENTER_FUNC(). And the return now uses "<<${name}".
- Fixed bug in DBUG_FIND_CURRENT_TRAPS() where it returned unusable info for
anonymous functions. Now always returns CODE references instead of strings
containing the name of the function(s) called.
- Fixed t/20-signal_traps.t to test new results from DBUG_FIND_CURRENT_TRAPS()
correctly.
- Fixed bugs in README variable load examples.
1.03 2019-01-10 08:30:00
- More POD clean up.
- Updated copyright to say 2019.
- Improved detection if program is run via "make test" in BEGIN.
- Made DBUG_FIND_CURRENT_TRAPS() plural to avoid confusion.
*** Makes it Incompatible with previous releases! ***
- Fixed _dbug_log_signal to convert CODE references back into their function
names for use by DBUG_FIND_CURENT_TRAPS().
- When trapping warnings, always makes sure the file/line is written to fish
even when the caller specifically suppressed it.
- Added new function DBUG_MASK_NEXT_FUNC_CALL() & modified
DBUG_ENTER_FUNC() to use the results. Also put in OFF.pm
- To help with auto testing of module, also wrote test helper method
dbug_mask_argument_counts() in both *.pm files.
- Changed DBUG_PUSH() option from "pid" to "multi" to make it more obvious
what it's for. (Multi-Thread and/or Multi-Process tracing.)
- Fixed DBUG_PUSH() initialization to allow for it to be called outside of
the "main" function of your program!
- Fixed DBUG_PRINT() to prepend the thread info on all lines when "multi"
option is in use. Otherwise leaves blank as before. Allows us to break
up a fish file trace by thread when multiple threads write to it.
- Fixed bug in DBUG_TRAP_SIGNAL() handling option DBUG_SIG_ACTION_REMOVE.
- Stopped polluting Perl's namespace by no longer exporting the test functions
used by the t/*.t programs. Then fixed all the t/*.t programs to explicitly
reference them as non-exposed functions.
- Added test case dependencies to Makefile.PL & added PL_FILES option.
- Wrote full_developer_test.pl.src to help with running the test cases in
all three modes. Running 'make' creates the full_developer_test.pl prog
itself. Had to do indirectly so that 'make install' wouldn't try to
install it under the perl bin tree.
- Fixed all 4 basic scripts to use BAIL_OUT() if module fails to load.
Catches compile issues early & aborts "make test"!
- Fixed all t/*.t test programs to put their fish files in t/fish/*.fish.txt
- Added new test t/35-func_masking.t
- Added t/60-multi_thread_test.t for thread testing with a common shared
fish log. Must use a 'grep' like tool to make this fish log readable!
Ex: grep ^[0-9]*-10: t/fish/60-multi_thread_test.fish.txt
Strips out the trace of thread 10.
Ex: grep ^[0-9]*-0: t/fish/60-multi_thread_test.fish.txt
Shows just the trace of the main thread!
- Added t/65-multi_thread_sep_logs_test.t to test out threads having their
own log files.
- Added t/67-multi_thread_buggy_usage.t to show incorrect usage of threads.
- Fixed all t/*.t test progs to treat any unexpected warnings as a failed test
case or a reason to call BAIL_OUT() in the 4 basic tests! There were still
many cases where a warning was expected!
- Added t/70-fork_test.t as a new test case.
- Fixed issues with the test cases run while using Fred::Fish::DBUG::OFF.
- Fixed some README typos/changes.
- Added the new test progs to the MANIFEST.
1.02 2018-08-06 08:30:00
- Some code clean up
- Some POD clean up
- Some polishing of the t/*.t test progs!
- Converted Fred::Fish::DBUG::OFF to inherit from Fred::Fish::DBUG to avoid
compatibility issues in the future. Most of the functions are still
overridden as stubs though.
Never Released this version.
1.01 2017-08-31 08:30:00
- Started logging my changes in a change file as I started packaging it
with the eventual goal of uploading it to CPAN.
- Started keeping track of the VERSION.
Never Released this version.