NAME

Fred::Fish::DBUG::TIE - Fred Fish library extension to trap STDERR & STDOUT.

SYNOPSIS

use Fred::Fish::DBUG::TIE;
  or
require Fred::Fish::DBUG::TIE;

DESCRIPTION

Fred::Fish::DBUG::TIE is an extension to the Fred Fish DBUG module that allows your program to trap all output written to STDOUT & STDERR to also be merged into your fish logs.

It's very usefull when a module that doesn't use Fish writes it's logging information to your screen and you want to put this output into context with your program's fish logs.

This is implemented via Perl's tie feature. Please remember that perl only allows one tie per filehandle. But if multiple ties are required, this module provides a way to chain them together.

FUNCTIONS

DBUG_TIE_STDERR ( [$callback_func [, $ignore_chaining [, $caller ]]] )

This method ties what's written to STDERR to also appear in the fish logs with the tag of "STDERR". This tie will happen even if the fish logging is currently turned off.

If the tie is already owned by this module then future calls just steals the old tie's chain if not told to ignore it.

It returns 1 on a successful setup, and 0 or undef on failure.

If $callback_func is provided, each time you call a print command against STDERR, it will call this function for you after it first writes the message to fish and then chains to the previous tie or prints to STDERR. If either step encounters any errors, the callback will not be made.

The number of arguments the callback function expects is based on the context of the print request. "print @list" passes the callback @list. But "printf $fmt, @values" passes you the single pre-formatted print message.

Your callback should return 1 on success or 0/undef on failure. Any failure is reported as the return value of the original print command. If fish has been redirected to your screen, fish will be disabled during the callback.

If $ignore_chaining is true, it will ignore any existing tie against this file handle. The default is to chain to it if a tie exists. Assuming that if you already have an established tie that it must be important. So it won't toss it in favor of this logging unless you explicitly tell it to do so!

If $caller is true, it will identify where in the code the trapped print request can be found. If 0 it will surpress caller info. If undef it will use the current who_called setting from DBUG_PUSH to make this decision.

DBUG_TIE_STDOUT ( [$callback_func [, $ignore_chaining [, $caller ]]] )

This method ties what's written to STDOUT to also appear in the fish logs with the tag of "STDOUT". This tie will happen even if the fish logging is currently turned off.

If the tie is already owned by this module then future calls just steals the old tie's chain if not told to ignore it.

It returns 1 on a successful setup, and 0 or undef on failure.

See DBUG_TIE_STDERR for more info on the parameters.

DBUG_UNTIE_STDERR ( )

This method breaks the tie between STDERR and the fish logs. Any writes to STDERR after this call will no longer be written to fish. It will not call untie if someone else owns the STDERR tie.

It returns 1 on success, and 0 on failure.

Currently if it's chaining STDERR to a previous tie it can't preserve that inforation.

DBUG_UNTIE_STDOUT ( )

This method breaks the tie between STDOUT and the fish logs. Any writes to STDOUT after this call will no longer be written to fish. It will not call untie if someone else owns the STDOUT tie.

It returns 1 on success, and 0 on failure.

Currently if it's chaining STDOUT to a previous tie it can't preserve that inforation.

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 to enable this module.

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

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

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) 2019 - 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.