view release on metacpan or  search on metacpan

lib/Module/Extract/Use.pm  view on Meta::CPAN

use v5.10;
use utf8;

package Module::Extract::Use;
use strict;

use warnings;
no warnings;

our $VERSION = '1.055';

=encoding utf8

=head1 NAME

Module::Extract::Use - Discover the modules a module explicitly uses

=head1 SYNOPSIS

	use Module::Extract::Use;

	my $extor = Module::Extract::Use->new;

	my @modules = $extor->get_modules( $file );
	if( $extor->error ) { ... }

	my $details = $extor->get_modules_with_details( $file );
	foreach my $detail ( @$details ) {
		printf "%s %s imports %s\n",
			$detail->module, $detail->version,
			join ' ', @{ $detail->imports }
		}

=head1 DESCRIPTION

Extract the names of the modules used in a file using a static
analysis. Since this module does not run code, it cannot find dynamic
uses of modules, such as C<eval "require $class">. It only reports modules
that the file loads directly or are in the import lists for L<parent>
or L<base>.

The module can handle the conventional inclusion of modules with either
C<use> or C<require> as the statement:

	use Foo;
	require Foo;

	use Foo 1.23;
	use Foo qw(this that);

It now finds C<require> as an expression, which is useful to lazily
load a module once (and may be faster):

	sub do_something {
		state $rc = require Foo;
		...
		}

Additionally, it finds module names used with C<parent> and C<base>,
either of which establishes an inheritance relationship:

	use parent qw(Foo);
	use base qw(Foo);

In the case of namespaces found in C<base> or C<parent>, the value of
the C<direct> method is false. In all other cases, it is true. You
can then skip those namespaces:

	my $details = $extor->get_modules_with_details( $file );
	foreach my $detail ( @$details ) {
		next unless $detail->direct;

		...
		}

This module does not discover runtime machinations to load something,
such as string evals:

	eval "use Foo";

	my $bar = 'Bar';
	eval "use $bar";

If you want that, you might consider L<Module::ExtractUse> (a confusingly
similar name).

=cut

=over 4

=item new

Makes an object. The object doesn't do anything just yet, but you need
it to call the methods.

=cut

sub new {
	my $class = shift;

	my $self = bless {}, $class;

	$self->init;

	$self;
	}

=item init

Set up the object. You shouldn't need to call this yourself.

=cut

sub init {
	$_[0]->_clear_error;

lib/Module/Extract/Use.pm  view on Meta::CPAN

	my @modules = map { $_->module } @$details;

	@modules;
	}

=item get_modules_with_details( FILE )

Returns a list of hash references, one reference for each namespace
explicitly use-d in FILE. Each reference has keys for:

	namespace - the namespace, always defined
	version   - defined if a module version was specified
	imports   - an array reference to the import list
	pragma    - true if the module thinks this namespace is a pragma
	direct    - false if the module name came from parent or base

Each used namespace is only in the list even if it is used multiple
times in the file. The order of the list does not correspond to
anything so don't use the order to infer anything.

=cut

sub get_modules_with_details {
	my( $self, $file ) = @_;

	$self->_clear_error;

	my $modules = $self->_get_ppi_for_file( $file );
	return [] unless defined $modules;

	$modules;
	}

sub _get_ppi_for_file {
	my( $self, $file ) = @_;

	unless( -e $file ) {
		$self->_set_error( ref( $self ) . ": File [$file] does not exist!" );
		return;
		}

	require PPI;

	my $Document = eval { PPI::Document->new( $file ) };
	unless( $Document ) {
		$self->_set_error( ref( $self ) . ": Could not parse file [$file]" );
		return;
		}

	# this handles the
	#   use Foo;
	#   use Bar;
	my $regular_modules = $self->_regular_load( $Document );

	# this handles
	#   use parent qw(...)
	my $isa_modules      = $self->_isa_load( $regular_modules );

	# this handles
	#   my $rc = require Foo;
	my $expression_loads = $self->_expression_load( $Document );

	my @modules = map { @$_ }
		$regular_modules,
		$isa_modules,
		$expression_loads
		;

	return \@modules;
	}

sub _regular_load {
	my( $self, $Document ) = @_;

	my $modules = $Document->find(
		sub {
			$_[1]->isa( 'PPI::Statement::Include' )
			}
		);

	return [] unless $modules;

	my %Seen;
	my @modules =
		grep { ! $Seen{ $_->{module} }++ && $_->{module} }
		map  {
			my $hash = bless {
				direct  => 1,
				content => $_->content,
				pragma  => $_->pragma,
				module  => $_->module,
				imports => [ $self->_list_contents( $_->arguments ) ],
				version => eval{ $_->module_version->literal || ( undef ) },
				}, 'Module::Extract::Use::Item';
			} @$modules;

	\@modules;
	}

sub _isa_load {
	my( $self, $modules ) = @_;
	my @isa_modules =
		map {
			my $m = $_;
			map {
				bless {
					content => $m->content,
					pragma  => '',
					direct  => 0,
					module  => $_,
					imports => [],
					version => undef,
					}, 'Module::Extract::Use::Item';
				} @{ $m->imports };
			}
		grep { $_->module eq 'parent' or $_->module eq 'base' }
		@$modules;

	\@isa_modules;
	}