Daniel Muey > Perl-ImportReport-0.1 > Perl::ImportReport

Download:
Perl-ImportReport-0.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.1   Source  

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.

syntax highlighting: