PPI::Xref - generate cross-references for Perl code
use PPI::Xref; my $xref = PPI::Xref->new(); # Constructor.
PPI::Xref can be used to process files of Perl code or Perl code as a string, and then generate cross-references of its contents. The code is never executed, only parsed as a document tree.
NOTE: the cross-reference is not a call graph. Instead, it is a statically generated graph of file inclusions and named sub definitions.
NOTE: all the use/no/require/do are followed, which means that for example optional or platform specific modules will fail to be found. This is expected and fine.
my $xref = PPI::Xref->new($opt);
The $opt is a href of options. Possible options:
Boolean, whether to recurse or not, default yes.
NOTE: even with false recurse the files referred to at the first level (for example, X.pm for use X) will be looked up. But no further descending into those files will happen, so subs from those files will not be found.
recurse
X.pm
use X
Boolean, if true, progress messages are shown during the processing.
An aref of directories, default [ @INC ]. You can retrieve the aref (with non-accessible non-directories removed) as $xref->INC.
String, a directory name. For paranoia, the directory must exist. If defined, use for the PPI processing results of source files, including the (SHA-1) hash checksum of the file, and the results derived from PPI parsing.
Process one or more files. They are looked for in the @INC, or in the INC specified via the constructor.
$xref->process($filename, ...);
Process string of Perl code, pass it in as scalar ref. This will show up as filename '-'.
$xref->process(\$string);
Once you have processed all the inputs you can query the object for various results. More complex results need to queried using iterators.
Fully resolved filenames.
$xref->files
Fully qualified subroutine names.
$xref->subs
Package names in package statements.
$xref->packages
Module names in use/no/require.
$xref->modules
The total number of times the file is referred to by file inclusion.
$xref->file_count($file)
The total number of times the module is referred to by use/no/require.
$xref->module_count($module)
The number of lines in the file.
$xref->file_lines($file)
The total number of lines in all the seen files.
$xref->total_lines()
my $sfi = $xref->subs_files_iter; while (my $sf = $sfi->next) { my ($subname, $filename, $linenumber) = $sf->array; my $sfs = $sf->string; # Single string concatenating the columns. }
NOTE: the subnames are not necessarily unique, for multiple reasons:
The iter constructor can also take an options href:
String for joining, for the string() method.
Boolean, whether the also column numbers should be returned.
Boolean, should also the end line/column of the sub be returned.
Like subs_files_iter, but for packages.
my $pfi = $xref->packages_files_iter;
Options as with "subs_files_iter".
NOTE 1: since packages are lexically scoped, and since a single file can declare multiple packages, and since any file may declare any package, the same package name may be listed multiple times.
NOTE 2: the results of the finish option, and specially if combined with the column option, are sometimes slightly debatable: in which package do the whitespace tokens belong, for example?
finish
column
File inclusion: any of use / no / require / do (file).
use
no
require
do
my $ifi = $xref->incs_files_iter; while (my $if = $ifi->next) { # The $first_file line $linenumber includes the $second_file. my ( $first_file, $linenumber, $second_file, # full path filename $stmt_content, # string: use/no/require/do $include_string, # module name (use/no/require) or filename (require/do) ... ) = $if->array; my $ifs = $if->string; # Single string concatenating the columns. }
Options as with "subs_files_iter". Depending on the column and finish options, the ... can have none to three elements (default none).
Inclusion chains: starting from all the root files, singleton files (if any, see "incs_deps"), and then files given to process(), return the full inclusion chains of files. What this basically means is dependencies.
NOTE 1: this does not return all the possible paths, since that would be ill-defined for inclusion loops, and diamond patterns. What this returns is (starting from the roots and singletons), all the possible paths that do not cause loops, or in general visiting already seen files (counting from the current root). Another way of looking at the returned results is that if they would be overlaid, they would form a DAG (directed acyclic graph).
NOTE 2: all the possible paths does include multiple inclusions. This means that if both the lines A.pm:X and A.pm:Y include B.pm, both paths (the path through X, and the path through Y) are returned.
NOTE 3: there are MANY paths even for the simplest code.
my $ici = $xref->incs_chains_iter; while (my $ic = $ici->next) { # The @ic is either of one element (a file that includes nothing) # or 3, 5, 7, ... elements (you can think of this as 2k + 1 where # k = 0, 1, 2...) # @ic[0, 2, 4, ...] are filenames. # @ic[1, 3, 5, ...] are linenumbers. my @ic = $ic->array; my $ics = $ic->string; # Single string concatenating the columns. }
You can specify separator in the options for the iterator constructor. (No column or finish options available, for simplicity.) You can also specify a boolean reverse_chains option to generate reverse dependencies.
separator
reverse_chains
Computes the depth-one dependency tree of all the seen files.
my $id = $xref->incs_deps; $id->files() # All the files. $id->successors($file) # The files included. $id->predecessors($file) # The files including. $id->roots() # File nobody is including. $id->leaves() # Files everybody is just including. $id->branches() # Both included and including. $id->singletons() # Neither included nor including. $id->file_kind($file) # 'root', 'leaf', 'branch', 'singleton', or C<undef>.
Note that the 'root', 'leaf', and 'branch' are relative terms: it all depends on which node you start from.
How many PPI documents have been created. If cached results are being used, less documents need be created.
How many PPI processing results have been read from the cache results.
How many PPI processing results have been written to the cache results.
For cache maintenance you may want to delete cache files of removed source files. Detection of removed source files is outside the scope of PPI::Xref (either or both of version control system querying and file system traversal are likely), but if you know the files, you can use
$xref->cache_delete($file, ...)
The specified files have to be either original fully resolved filenames, (not the INC-relative ones), or the fully resolved cache filenames.
Deletions happen quietly: a missing cache file causes no warning.
Returns the number of successful deletions.
@modules = $xref->missing_modules()
Modules that were called for via use/no/require/do but which could not be found in %INC.
%INC
Common reasons include:
Modules that are conditionally invoked, for example based on the operating system, or configuration options.
Modules that are invoked based on a runtime value. PPI does not do runtime.
$count = $xref->missing_module_count($modulename)
Given a name of a missing module, how many times it was referred.
@files = $xref->missing_module_files($modulename)
Given a name of a missing module, returns the files that referred it.
@lines = $xref->missing_module_lines($modulename)
Given a name of a missing module, returns the lines that referred it.
@files = $xref->parse_errors_files()
Files that had parsing errors, which PPI could not handle.
Document incomplete is the most common parsing error. That means that after parsing the file, PPI was left with unbalanced state, like for example opened but not closed brace. This may have been caused by some earlier parsing issue.
$xref->file_parse_errors($filename)
Given a filename, return a hash of its parse errors. The keys are the error locations (which can be the whole file), the values are the error details (which can be just "Document incomplete" in the case of the whole file).
perl 5.14, https://search.cpan.org/perldoc?PPI, https://search.cpan.org/perldoc?Sereal
To install PPI::Xref, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PPI::Xref
CPAN shell
perl -MCPAN -e shell install PPI::Xref
For more information on module installation, please visit the detailed CPAN module installation guide.