=pod

=for comment
This file located in the distribution. But it is also found in a Github wiki:
https://github.com/rocky/p5-B-DeparseTree/wiki/DeparseTree.pod
where we can immediately see the results and others can contribute.

=begin html

<a href="https://travis-ci.org/rocky/p5-B-DeparseTree"><img src="https://travis-ci.org/rocky/p5-B-DeparseTree.png"></a>

=end html

=head1 Name

B::DeparseTree

=head2 Synopsis

   use B::DeparseTree;
   my $deparse = B::DeparseTree->new();

   # create a subroutine to deparse...
   sub my_abs($) {
       return -$a < 0 ? -$a : $a;
   };

   my $deparse_tree = B::DeparseTree->new();
   my $tree_node = $deparse_tree->coderef2info(\&my_abs);
   print $tree_node->{text};

The above produces:

    ($)
    {
        return -$a < 0 ? -$a : $a
    }

but the result are reconstructed purely from the OPnode tree. To show
parent-child information in the tree:

   use B::DeparseTree;
   B::DeparseTree::Fragment::dump_relations($deparse_tree);

which produces in abbreviated form...

   ...
   3--------------------------------------------------
   Child info:
   	addr: 0x263b710, parent: 0x263b748
   	op: pushmark
   	text: return -$a < 0 ? -$a : $a

   return -$a < 0 ? -$a : $a
   ||||||
   3--------------------------------------------------
   4--------------------------------------------------
   Child info:
   	addr: 0x263b748, parent: 0x263b628
   	op: return
   	text: return -$a < 0 ? -$a : $a

   return -$a < 0 ? -$a : $a
   -------------------------
   4--------------------------------------------------
   5--------------------------------------------------
   Child info:
   	addr: 0x263b790, parent: 0x263b748
   	op: cond_expr
   	text: -$a < 0 ? -$a : $a

   return -$a < 0 ? -$a : $a
          ------------------
   5--------------------------------------------------
   ...
   9--------------------------------------------------
   Child info:
   	addr: 0x263b898, parent: 0x263b7d0
   	op: negate
   	text: -$a

   return -$a < 0 ? -$a : $a
                    ---
   9--------------------------------------------------

The subroutine C<extract_node_info> is what produces the text with its underline.

=head2 Description

Perl's L<B::Deparse> but we save abstract tree information and associate
that with Perl text fragments.  These are fragments accessible by OP
address. With this, in Perl you can determine more precisely where you in
a program with granularity finer that at a line number boundary.

Uses for this could be in stack trace routines like L<Carp>. It is used
in the L<deparse |https://metacpan.org/pod/Devel::Trepan::Deparse>
command extension to L<Devel::Trepan>.

=head2 See also:

=over  4

=item *

L<B::Devel::Trepan::Deparse> for a L<Devel::Trepan> plugin that uses this

=item *

L<B::Deparse> for deparsing without keeping tree information around

=item *

L<B::Callsite> for one way to get opcode locations on the call stack

=item *

L<Exact Perl location with B::Deparse (and Devel::Callsite) |http://blogs.perl.org/users/rockyb/2015/11/exact-perl-location-with-bdeparse-and-develcallsite.html> for
more information.

=back
