view release on metacpan or  search on metacpan

lib/Fred/Fish/DBUG/Tutorial.pm  view on Meta::CPAN

    <main-prog
    exit (0)

    >main::END
    <main::END

    >Fred::Fish::DBUG::END
    | Fred::Fish::DBUG: So Long, and Thanks for All the Fish!
    <Fred::Fish::DBUG::END ()

What happened to the tracing of the BEGIN block of code?

BEGIN was called before you called DBUG_PUSH(), so it wasn't tracked in the
B<fish> log.  You'd need to call DBUG_PUSH() in the BEGIN block itself if you'd
like B<fish> to trace your BEGIN logic.

And speaking of BEGIN, never, ever call DBUG_TRAP_SIGNAL in a BEGIN block.  You
can get really strange behavior if you have syntax errors in your code and these
error messages and warnings get trapped by L<Fred::Fish::DBUG>.  The only reason
to call it in a BEGIN block is to stress test L<Fred::Fish::DBUG> itself.

As a final note, except for AUTOLOAD, these and the other special Perl functions
have no caller, arguments or return values.  They are called by Perl itself and
not by your code.  Like BEGIN at compile time and END when Perl is shutting down
your code.

 ===============================================================

=head1 EXAMPLE # 12 - Some not so obvious surprises ...

Or maybe not if you've been paying close attention.

For all examples below assume:

    sub some_function {
       DBUG_ENTER_FUNC (@_);
       DBUG_RETURN (@_);
    }

 ********************

    if ( some_function ( qw /1 0 -1/ ) ) { ... }
    if ( some_function ( qw /1 0 -1/ ) == 0 ) { ... }

The interesting part, both calls log the same return value to B<fish>.

   | <main::some_function - return ([1])

It was smart enough to tell it to return just the first value instead of a list
of values.

 ********************

   foreach ( some_function ( qw /1 0 -1/ ) ) { ... }

The interesting part of the B<fish> log:

   | <main::some_function - return ([1], [0], [-1])

Notice it was smart enough to return a list of values.  And the loop had three
iterations.

 ********************

   while ( some_function ( qw /1 0 -1/ ) ) { ... }

The interesting part of the B<fish> log:

   | <main::some_function - return ([1])

It was smart enough to tell it to return just the first value instead of a list
of values.  But you ended up in an infinite loop!

 ********************

    $val = ( some_function ( qw / a b c / ) )[1];

The interesting part of the B<fish> log:

   | <main::some_function - return ([a], [b], [c])

And B<$val> gets set to "b"!

 ********************

    my $x = call_me ( some_function ( qw /a b c/ ) );

The interesting part of the B<fish> log:

   | <main::some_function - return ([a], [b], [c])
   | >main::call_me
   | | args: [a], [b], [c]
   | <main::call_me - return ([a])

Notice that B<some_function> returned all it's return values as arguments to
B<call_me>!

 ********************

Which leads us to this final surprising result.  Which should be obvious, but
usually isn't at first glance.

   call_me (qw /a b c/);
   $x = call_me (qw /a b c/);
   @l = call_me (qw /a b c/);

   sub call_me {
      DBUG_ENTER_FUNC (@_);
      DBUG_RETURN ( some_function (@_) );
   }

The call to B<some_function> will always return in list mode!  No matter what it
finally decides to return for B<call_me>!  It doesn't inherit the I<wantarray>
status!

   | | <main::some_function - return ([a], [b], [c])

It treats DBUG_RETURN() as just another function call!  Which can be a bit
counterintuitive at times!  So if you wanted B<some_function> to inherit the
I<wantarray> status of B<call_me>, you'd have to do something like this.