NAME

Perl::ImportReport - Find data on symbols being imported by Perl code

VERSION

This document describes Perl::ImportReport version 0.1

SYNOPSIS

    use Perl::ImportReport;
    
    # Create the import checking object
    my $object = Perl::ImportReport->new( $filename ) || die "Invalid value for PPI document source";
    my $object = Perl::ImportReport->new( \$source  ) || die "Invalid value for PPI document source";
    my $object = Perl::ImportReport->new( $ppi_document ) || die "Invalid value for PPI document source";

    # Find the import data information
    my $import_data = $object->get_import_report();  

DESCRIPTION

Sometimes you want to trim out needless importing from your code. This object calculates and reports what packages are importing what symbols into what packages in the code.

INTERFACE

new

  # Create the version checking object
  my $object = Perl::ImportReport->new( $filename ) || die "Invalid value for PPI document source";
  my $object = Perl::ImportReport->new( \$source  ) || die "Invalid value for PPI document source";
  my $object = Perl::ImportReport->new( $ppi_document ) || die "Invalid value for PPI document source";

The new constructor creates a new import reporting object for a PPI::Document. You can also provide the document to be read as a file name, or as a SCALAR reference containing the code.

Returns a new Perl::ImportReport object, or undef on error.

get_ppi_document

The get_ppi_document accessor can be used to get the PPI::Document object back out of the import reporting.

Document

Alias for get_ppi_document for all you Perl::MinimumVersion fans.

get_import_report

Dive the PPI PDOM and build a report of the symbols being imported in the code.

Returns a data structure with the following keys:

'number_of_includes'

In the context of this module an "include" is a use() statement that is not a pragma and not a non-import use().

'imports'

This is an array of hashes. Each hash describes an "include" instance.

The keys in this hash are:

'symbol_list'

Expanded export list. Tags, negations, and regexes are worked out into the final list of what would actually be exported.

'raw_perl'

The actual use() statement in question.

'module'

The namespace of the module.

'module_version'

The version being required (if any)

'arguments'

The array ref containing arguments()

'line_number'

The line number of the use statement.

'in_package'

The package it is in (and thus where the symbols will be imported into).

'exporter'

A hashref with the keys EXPORT, EXPORT_OK, EXPORT_TAG.

Each one of those is a hash that has the key 'error' which holds the error (if any() trying to require the module), 'data' that hold the modules's corresponding symbol. (e.g. {EXPORT}{data}) is the module's @EXPORT)

EXPORT also has 'count' which is the count of items in @EXPORT.

DIAGNOSTICS

Throws no warnings or errors of it's own.

CONFIGURATION AND ENVIRONMENT

Perl::ImportReport requires no configuration files or environment variables.

DEPENDENCIES

PPI, PPI::Util

SEE ALSO

Perl::MinimumVersion

TODO

There a couple of possible todo's commented in the source, patches welcome!

Have the results data structure as an object (or objects) that have their own inspection methods and/or add inspection methods.

For now you can find a simple reporting script that uses the data structure directly at "/drmuey.com/?do=page&id=102"" in "http:.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-perl-importreport@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Daniel Muey <http://drmuey.com/cpan_contact.pl>

LICENCE AND COPYRIGHT

Copyright (c) 2010, Daniel Muey <http://drmuey.com/cpan_contact.pl>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Perl::ImportReport

perl -MCPAN -e shell
install Perl::ImportReport