NAME

       Devel::NYTProf::Data - Devel::NYTProf data loading and manipulation

SYNOPSIS

         use Devel::NYTProf::Data;

         $profile = Devel::NYTProf::Data->new( { filename => 'nytprof.out' } );

         $profile->dump_profile_data();

DESCRIPTION

       Reads a profile data file written by Devel::NYTProf, aggregates the contents, and returns
       the results as a blessed data structure.

       Access to the data should be via methods in this class to avoid breaking encapsulation
       (and thus breaking your code when the data structures change in future versions).

       NOTE the documentation is out of date and may not be updated soon.  It's also likely that
       the API will change drastically in future.  It's possible, for example, that the data
       model will switch to use SQLite and the http://metacpan.org/pod/ORLite ORM.

       Let me know if you come to depend on a particular API and I'll try to preserve it if
       practical.

METHODS

   new
         $profile = Devel::NYTProf::Data->new( );

         $profile = Devel::NYTProf::Data->new( {
           filename => 'nytprof.out', # default
           quiet    => 0,             # default, 1 to silence message
         } );

       Reads the specified file containing profile data written by Devel::NYTProf, aggregates the
       contents, and returns the results as a blessed data structure.

   dump_profile_data
         $profile->dump_profile_data;
         $profile->dump_profile_data( {
             filehandle => \*STDOUT,
             separator  => "",
         } );

       Writes the profile data in a reasonably human friendly format to the specified
       "filehandle" (default STDOUT).

       For non-trivial profiles the output can be very large. As a guide, there'll be at least
       one line of output for each line of code executed, plus one for each place a subroutine
       was called from, plus one per subroutine.

       The default format is a Data::Dumper style whitespace-indented tree.  The types of data
       present can depend on the options used when profiling.

       If "separator" is true then instead of whitespace, each item of data is indented with the
       path through the structure with "separator" used to separate the elements of the path.
       This format is especially useful for grep'ing and diff'ing.

   normalize_variables
         $profile->normalize_variables;

       Traverses the profile data structure and normalizes highly variable data, such as the
       time, in order that the data can more easily be compared. This is mainly of use to the
       test suite.

       The data normalized is:

       •   profile timing data: set to 0

       •   subroutines: timings are set to 0

       •   attributes, like basetime, xs_version, etc., are set to 0

       •   filenames: path prefixes matching absolute paths in @INC are changed to "/.../"

       •   filenames: eval sequence numbers, like "(re_eval 2)" are changed to 0

   subs_defined_in_file
         $subs_defined_hash = $profile->subs_defined_in_file( $file, $include_lines );

       Returns a reference to a hash containing information about subroutines defined in a source
       file.  The $file argument can be an integer file id (fid) or a file path.

       Returns undef if the profile contains no "sub_subinfo" data for the $file.

       The keys of the returned hash are fully qualified subroutine names and the corresponding
       value is a hash reference containing Devel::NYTProf::SubInfo objects.

       If $include_lines is true then the hash also contains integer keys corresponding to the
       first line of the subroutine. The corresponding value is a reference to an array. The
       array contains a hash ref for each of the subroutines defined on that line, typically just
       one.

   file_line_range_of_sub
         ($file, $fid, $first, $last, $fi) = $profile->file_line_range_of_sub("main::foo");

       Returns the filename, fid, and first and last line numbers, and fileinfo object for the
       specified subroutine (which must be fully qualified with a package name).

       Returns an empty list if the subroutine name is not in the profile data.

       The $fid return is the 'original' fid associated with the file the subroutine was created
       in.

       The $file returned is the source file that defined the subroutine.

       Subroutines that are implemented in XS have a line range of 0,0 and a possibly unknown
       file (if NYTProf couldn't find a good match based on the package name).

       Subroutines that were called but only returned via an exception may have a line range of
       undef,undef if they're xsubs or were defined before NYTProf was enabled.

   resolve_fid
         $fid = $profile->resolve_fid( $file );

       Returns the integer file id that corresponds to $file.

       If $file can't be found and $file looks like a positive integer then it's presumed to
       already be a fid and is returned. This is used to enable other methods to work with fid or
       file arguments.

       If $file can't be found but it uniquely matches the suffix of one of the files then that
       corresponding fid is returned.

PROFILE DATA STRUTURE

       XXX

LIMITATION

       There's currently no way to merge profile data from multiple files.

SEE ALSO

       Devel::NYTProf

AUTHOR

       Adam Kaplan, "<akaplan at nytimes.com>" Tim Bunce, <http://blog.timbunce.org> Steve
       Peters, "<steve at fisharerojo.org>"

COPYRIGHT AND LICENSE

        Copyright (C) 2008 by Adam Kaplan and The New York Times Company.
        Copyright (C) 2008,2009 by Tim Bunce, Ireland.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of
       Perl 5 you may have available.