The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PPI-Xref-0.010
River stage zero No dependents
/ ppixref

NAME

ppixref - frontend for PPI::Xref for indexing and querying Perl code

Usage

$ME [--files|--subs|--packages|--modules|--missing_modules|--parse_errors] ...

$ME [--subs_files|--packages_files] ...

$ME [--files_lines|--total_lines] ...

$ME [--incs_files|--incs_chains|--incs_chains_reverse|--incs_deps] ...

$ME [--files_founts|--modules_counts] ...

$ME [--code=... [--auto_semicolon|--noauto_semicolon]]

$ME --parse

$ME --report_all

$ME --report_title --noreport_title

$ME --report_prefix=prefix

$ME --INC=dir,dir,dir

$ME --cache_directory=dir

$ME [--process_verbose|--recurse_verbose|--cache_verbose|--summary]

$ME [--separator=s|--column|--finish]

$ME --recurse|--norecurse

$ME [--help|--short_help|--long_help]

Description

The ... in the usage message is either a list of files, or --code='...', or --files_from_file=file, or --files_from_cache, or --files_from_system (the @INC).

If --code is used, the filename is faked to be '-' in the reports. The --files_from_file=file specifies a file to read the filenames from, filename per line. If the filename is '-', STDIN is used.

Note that the --code argument must be complete, e.g. 'use utf8;' must have the semicolon. For convenience, a semicolon is automatically added unless there already is one, or the code argument ends in an end brace. This can be disabled with --noauto_semicolon.

The --parse can be used to just parse the inputs (and possibly cache the results, if --cache_directory is specified) but not to output anything (except the --*verbose or --summary output). One or more of --parse or one of the report options (--packages et cetera, read on) must be specified.

An "inc" is a "file inclusion", any of the use/no/require/do.

  • --packages shows seen package statements, while the --modules shows module names included via use/no/require.

  • --missing_modules (default: on) shows the missing modules (in addition to warning about them during scan). Use --nomissing_modules to suppress.

  • --parse_errors (default: on) shows the parse errors modules (in addition to warning about them during scan). Use --noparse_errors to suppress.

  • --subs_files, --packages_files, and --incs_files by default show only the start line, with --finish they show also the finish, and with --column also the column(s). The --incs_chains only shows the start lines.

  • --incs_files shows only the first level, the --incs_chains shows the full inclusion chains. Warning: the number of inclusion chains can be even for the simplest codes. Enjoy responsibly.

  • --incs_chains_reverse instead of --incs_chains generates reversed inclusion chains, for inspecting reverse dependencies.

  • --total_lines tells the total number of lines seen, while the --files_lines tells the lines per file.

  • --files_counts and --modules_counts show how many times each file or module is referred to (first-level).

  • --incs_deps shows what kind of tree node (root, branch, leaf, singleton) each file is in the total dependency tree. It does not attempt to draw the actual tree graph.

  • --report_all turns on all the reports. By default these reports go to STDOUT, with --report_prefix you can direct them to files starting with the specified prefix. The report titles ("===...===") can be turned off with --noreport_title.

  • --cache_directory=dir can be used to cache the PPI processing results under a directory. This is usually much faster than processing the files from scratch with PPI. For paranoia, the directory must exist.

  • --cache_read_only means that the cache files are read as-is, but no cache writes happen. (As optimization, neither will any (re)processing of files happen, because where would we put the results.) This option is useful if you just want to query the currently computed (and hopefully cached) results.

  • --INC=dir,dir,dir can be used to specify an \@INC different from the standard one. Note the comma-separation.

  • --separator default is the tabulator.

  • The default is to recurse through use/no/require/do statements, use --norecurse to not to.

  • The --summary (default: on) turns on summary report at the end.

  • The --processverbose turns on display on processing progress.

  • The --cacheverbose turns on verbose cache access.

Common warnings

Certain warnings happen reasonably often, but the reasonable default action is just to live with them. In certain cases one could report the issue as a PPI issue.

  • PPI::Xref::__process_id: warning: Failed to find file ... in ...

    If the file not found is something that depends on runtime values (e.g. some variable), PPI::Xref is not going to find it.

  • PPI::Xref::__process_id: warning: Failed to find module '...' in ...

    If the module is somehow optional, for example dependent on the operating system or not a core module, it may not be found on every installation.

  • PPI::Xref::__parse_error: PPI::Document incomplete in ...

    PPI::Xref checks whether a file was parsed as 'complete', meaning that all braces and parentheses and similar were balanced. If there was a parsing error in the file, completeness will not happen. This one you might want to report as a bug in PPI itself since PPI should be able to parse any valid Perl code. Please distill the failure to the smallest possible snippet before reporting it.

  • PPI::Xref::__parse_error: PPI::Document creation failed in ...

    The said file could not be parsed at all by PPI. Are you certain it contains valid Perl code?