NAME
    TAP::Tree - TAP (Test Anything Protocol) parser which supported the
    subtest

SYNOPSIS
    Parses a TAP output.

      use v5.10.1;
      require TAP::Tree;
      my $tap = <<'END';
      1..2
          ok 1 - sub test 1
          1..1
      ok 1 - test 1
      not ok 2 - test 2
      END

      my $taptree = TAP::Tree->new( tap_ref => \$tap );
      my $tree = $taptree->parse;   # return value is hash reference simply.

      say $tree->{plan}{number};             # -> print 2
      say $tree->{testline}[0]{description}; # -> print test 1
      say $tree->{testline}[1]{description}; # -> print test 2

      say $tree->{testline}[0]{subtest}{testline}[0]{description};
      # -> print sub test 1

    Summarises the parsed TAP output

      my $summary = $taptree->summary;
      say $summary->{planned_tests}; # -> print 2
      say $summary->{ran_tests};     # -> print 2
      say $summary->{failed_tests};  # -> print 1 ... number of failed tests.
                                    # 'TODO' tests are counted as 'ok', not 'not ok'

    Iterates the parsed TAP

      my $iterator = $taptree->create_tap_tree_iterator( subtest => 1 );
  
      while ( my $result = $iterator->next ) {
          say '>' x $result->{indent} . $result->{testline}{description};
      }

      # -> print
      #   test 1
      #   >sub test 1
      #   test 2

DESCRIPTION
    TAP::Tree is a simple parser of TAP which supported the subtest.

    It parses the data of a TAP format to the data of tree structure.

    Moreover, the iterator for complicated layered tree structure is also
    prepared.

METHODS
    * new

        require TAP::Tree;
        my $taptree = TAP::Tree->new( tap_ref => $tap_ref );

      Creates the instance of "TAP::Tree".

      Specify the reference to the scalar variable which stored the outputs
      of TAP as tap_ref of an arguments.

      The arguments can be specified "tap_file" and "tap_tree" in addition
      to "tap_ref".

      "tap_file" is specified the path to file which stored the outputs of
      TAP.

        my $taptree = TAP::Tree->new( tap_file => $path );

      "tap_tree" is specified the data of the tree structure which
      "TAP::Tree" parsed.

        my $taptree = TAP::Tree->new( tap_tree => $parsed_tap );

      "utf8" is specified, when TAP is encoded by UTF-8.

        my $taptree = TAP::Tree->new( tap_ref => $tap_ref, utf8 => 1 );

    * parse

        require TAP::Tree;
        my $taptree = TAP::Tree->new( tap_ref => $tap_ref );
        my $tree    = $taptree->parse;

        say $tree->{plan}{number};
        say $tree->{testline}[0]->{description};

      Parses a output of TAP and returns the tree structure data. The return
      value is a hash reference and all of the parsed result of TAP are
      stored.

      Please dump the detailed content of inclusion :)

        {
            version   => {},  # the version number of TAP (usually 12). 
            plan      => {},  # the hash reference in which the numbers of tests.
            testline  => [],  # the array reference in which the result of each tests.
            bailout   => {},  # the hash reference in which an informational about Bailout.
        }

    * summary

      Returns the summary of the TAP output.

      The contents of a summary is below ( hash reference ).

        version          -> the version number of TAP (usually 12).
        is_skipped_all   -> the flag that shows whether all the tests were skipped.
        skip_all_msg     -> the message that shows the reason of skip tests.
        is_bailout       -> the flag that shows whether bailout the tests.
        bailout_msg      -> the message that shows the reason of bailout.
        planned_tests    -> the number of the planned tests.
        ran_tests        -> the number of the ran tests.
        failed_tests     -> the number of the failed tests.
        is_good_plan     -> the flag that shows whether the number of plan is set.
        is_ran_all_tests -> the flag that shows whether the all tests are ran.

    * create_tap_tree_iterator

      "TAP::Tree" makes becomes the complicated structure where a hierarchy
      is deep, when there is a subtest.

      Therefore, the iterator which can follow a tree strucutre data easily
      is prepared for "TAP::Tree".

        my $taptree = TAP::Tree->new( tap_ref => $tap_ref );
        $taptree->parse;
        my $iterator = $taptree->create_tap_tree_iterator( subtest => 1);

        my $test = $iterator->next;
        say $test->{testline}{description};

      Specify arguments "subtest", when following subtest.

ISSUE REPORT
    <https://github.com/magnolia-k/p5-TAP-Tree/issues>

COPYRIGHT
    copyright 2014- Magnolia "<magnolia.k@me.com>".

LICENSE
    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.