[p5sagit/p5-mst-13.2.git] / lib / Module / Build / ModuleInfo.pm

package Module::Build::ModuleInfo;

# This module provides routines to gather information about
# perl modules (assuming this may be expanded in the distant
# parrot future to look at other types of modules).

use strict;

use File::Spec;
use IO::File;
use Module::Build::Version;


my $PKG_REGEXP  = qr/   # match a package declaration
  ^[\s\{;]*             # intro chars on a line
  package               # the word 'package'
  \s+                   # whitespace
  ([\w:]+)              # a package name
  \s*                   # optional whitespace
  ;                     # semicolon line terminator
/x;

my $VARNAME_REGEXP = qr/ # match fully-qualified VERSION name
  ([\$*])         # sigil - $ or *
  (
    (             # optional leading package name
      (?:::|\')?  # possibly starting like just :: (ala $::VERSION)
      (?:\w+(?:::|\'))*  # Foo::Bar:: ...
    )?
    VERSION
  )\b
/x;

my $VERS_REGEXP = qr/ # match a VERSION definition
  (?:
    \(\s*$VARNAME_REGEXP\s*\) # with parens
  |
    $VARNAME_REGEXP           # without parens
  )
  \s*
  =[^=~]  # = but not ==, nor =~
/x;


sub new_from_file {
  my $package  = shift;
  my $filename = File::Spec->rel2abs( shift );
  return undef unless defined( $filename ) && -f $filename;
  return $package->_init( undef, $filename, @_ );
}

sub new_from_module {
  my $package = shift;
  my $module  = shift;
  my %props   = @_;
  $props{inc} ||= \@INC;
  my $filename = $package->find_module_by_name( $module, $props{inc} );
  return undef unless defined( $filename ) && -f $filename;
  return $package->_init( $module, $filename, %props );
}

sub _init {
  my $package  = shift;
  my $module   = shift;
  my $filename = shift;

  my %props = @_;
  my( %valid_props, @valid_props );
  @valid_props = qw( collect_pod inc );
  @valid_props{@valid_props} = delete( @props{@valid_props} );
  warn "Unknown properties: @{[keys %props]}\n" if scalar( %props );

  my %data = (
    module   => $module,
    filename => $filename,
    version  => undef,
    packages => [],
    versions => {},
    pod          => {},
    pod_headings => [],
    collect_pod  => 0,

    %valid_props,
  );

  my $self = bless( \%data, $package );

  $self->_parse_file();

  unless ( $self->{module} && length( $self->{module} ) ) {
    my( $v, $d, $f ) = File::Spec->splitpath( $self->{filename} );
    if ( $f =~ /\.pm$/ ) {
      $f =~ s/\..+$//;
      my @candidates = grep /$f$/, @{$self->{packages}};
      $self->{module} = shift( @candidates ); # punt
    } else {
      if ( grep /main/, @{$self->{packages}} ) {
	$self->{module} = 'main';
      } else {
        $self->{module} = $self->{packages}[0] || '';
      }
    }
  }

  $self->{version} = $self->{versions}{$self->{module}}
      if defined( $self->{module} );

  return $self;
}

# class method
sub _do_find_module {
  my $package = shift;
  my $module  = shift || die 'find_module_by_name() requires a package name';
  my $dirs    = shift || \@INC;

  my $file = File::Spec->catfile(split( /::/, $module));
  foreach my $dir ( @$dirs ) {
    my $testfile = File::Spec->catfile($dir, $file);
    return [ File::Spec->rel2abs( $testfile ), $dir ]
	if -e $testfile and !-d _;  # For stuff like ExtUtils::xsubpp
    return [ File::Spec->rel2abs( "$testfile.pm" ), $dir ]
	if -e "$testfile.pm";
  }
  return;
}

# class method
sub find_module_by_name {
  my $found = shift()->_do_find_module(@_) or return;
  return $found->[0];
}

# class method
sub find_module_dir_by_name {
  my $found = shift()->_do_find_module(@_) or return;
  return $found->[1];
}


# given a line of perl code, attempt to parse it if it looks like a
# $VERSION assignment, returning sigil, full name, & package name
sub _parse_version_expression {
  my $self = shift;
  my $line = shift;

  my( $sig, $var, $pkg );
  if ( $line =~ $VERS_REGEXP ) {
    ( $sig, $var, $pkg ) = $2 ? ( $1, $2, $3 ) : ( $4, $5, $6 );
    if ( $pkg ) {
      $pkg = ($pkg eq '::') ? 'main' : $pkg;
      $pkg =~ s/::$//;
    }
  }

  return ( $sig, $var, $pkg );
}

sub _parse_file {
  my $self = shift;

  my $filename = $self->{filename};
  my $fh = IO::File->new( $filename )
    or die( "Can't open '$filename': $!" );

  my( $in_pod, $seen_end, $need_vers ) = ( 0, 0, 0 );
  my( @pkgs, %vers, %pod, @pod );
  my $pkg = 'main';
  my $pod_sect = '';
  my $pod_data = '';

  while (defined( my $line = <$fh> )) {

    chomp( $line );
    next if $line =~ /^\s*#/;

    $in_pod = ($line =~ /^=(?!cut)/) ? 1 : ($line =~ /^=cut/) ? 0 : $in_pod;

    # Would be nice if we could also check $in_string or something too
    last if !$in_pod && $line =~ /^__(?:DATA|END)__$/;

    if ( $in_pod || $line =~ /^=cut/ ) {

      if ( $line =~ /^=head\d\s+(.+)\s*$/ ) {
	push( @pod, $1 );
	if ( $self->{collect_pod} && length( $pod_data ) ) {
          $pod{$pod_sect} = $pod_data;
          $pod_data = '';
        }
	$pod_sect = $1;


      } elsif ( $self->{collect_pod} ) {
	$pod_data .= "$line\n";

      }

    } else {

      $pod_sect = '';
      $pod_data = '';

      # parse $line to see if it's a $VERSION declaration
      my( $vers_sig, $vers_fullname, $vers_pkg ) =
	  $self->_parse_version_expression( $line );

      if ( $line =~ $PKG_REGEXP ) {
	$pkg = $1;
	push( @pkgs, $pkg ) unless grep( $pkg eq $_, @pkgs );
	$vers{$pkg} = undef unless exists( $vers{$pkg} );
	$need_vers = 1;

      # VERSION defined with full package spec, i.e. $Module::VERSION
      } elsif ( $vers_fullname && $vers_pkg ) {
	push( @pkgs, $vers_pkg ) unless grep( $vers_pkg eq $_, @pkgs );
	$need_vers = 0 if $vers_pkg eq $pkg;

	my $v =
	  $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
	unless ( defined $vers{$vers_pkg} && length $vers{$vers_pkg} ) {
	  $vers{$vers_pkg} = $v;
	} else {
	  warn <<"EOM";
Package '$vers_pkg' already declared with version '$vers{$vers_pkg}'
ignoring new version '$v'.
EOM
	}

      # first non-comment line in undeclared package main is VERSION
      } elsif ( !exists($vers{main}) && $pkg eq 'main' && $vers_fullname ) {
	$need_vers = 0;
	my $v =
	  $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
	$vers{$pkg} = $v;
	push( @pkgs, 'main' );

      # first non-comement line in undeclared packge defines package main
      } elsif ( !exists($vers{main}) && $pkg eq 'main' && $line =~ /\w+/ ) {
	$need_vers = 1;
	$vers{main} = '';
	push( @pkgs, 'main' );

      # only keep if this is the first $VERSION seen
      } elsif ( $vers_fullname && $need_vers ) {
	$need_vers = 0;
	my $v =
	  $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );


	unless ( defined $vers{$pkg} && length $vers{$pkg} ) {
	  $vers{$pkg} = $v;
	} else {
	  warn <<"EOM";
Package '$pkg' already declared with version '$vers{$pkg}'
ignoring new version '$v'.
EOM
	}

      }

    }

  }

  if ( $self->{collect_pod} && length($pod_data) ) {
    $pod{$pod_sect} = $pod_data;
  }

  $self->{versions} = \%vers;
  $self->{packages} = \@pkgs;
  $self->{pod} = \%pod;
  $self->{pod_headings} = \@pod;
}

sub _evaluate_version_line {
  my $self = shift;
  my( $sigil, $var, $line ) = @_;

  # Some of this code came from the ExtUtils:: hierarchy.

  my $eval = qq{q#  Hide from _packages_inside()
		 #; package Module::Build::ModuleInfo::_version;
		 no strict;

		 local $sigil$var;
		 \$$var=undef; do {
		   $line
		 }; \$$var
		};

  local $^W;
  # Try and get the $VERSION
  my $result = eval $eval;
  warn "Error evaling version line '$eval' in $self->{filename}: $@\n" if $@;

  # Bless it into our own version class
  $result = Module::Build::Version->new($result);

  return $result;
}


############################################################

# accessors
sub name            { $_[0]->{module}           }

sub filename        { $_[0]->{filename}         }
sub packages_inside { @{$_[0]->{packages}}      }
sub pod_inside      { @{$_[0]->{pod_headings}}  }
sub contains_pod    { $#{$_[0]->{pod_headings}} }

sub version {
    my $self = shift;
    my $mod  = shift || $self->{module};
    my $vers;
    if ( defined( $mod ) && length( $mod ) &&
	 exists( $self->{versions}{$mod} ) ) {
	return $self->{versions}{$mod};
    } else {
	return undef;
    }
}

sub pod {
    my $self = shift;
    my $sect = shift;
    if ( defined( $sect ) && length( $sect ) &&
	 exists( $self->{pod}{$sect} ) ) {
	return $self->{pod}{$sect};
    } else {
	return undef;
    }
}

1;

__END__

=head1 NAME

ModuleInfo - Gather package and POD information from a perl module files


=head1 DESCRIPTION

=over 4

=item new_from_file($filename, collect_pod => 1)

Construct a ModuleInfo object given the path to a file. Takes an optional
arguement C<collect_pod> which is a boolean that determines whether
POD data is collected and stored for reference. POD data is not
collected by default. POD headings are always collected.

=item new_from_module($module, collect_pod => 1, inc => \@dirs)

Construct a ModuleInfo object given a module or package name. In addition
to accepting the C<collect_pod> argument as described above, this
method accepts a C<inc> arguemnt which is a reference to an array of
of directories to search for the module. If none are given, the
default is @INC.

=item name()

Returns the name of the package represented by this module. If there
are more than one packages, it makes a best guess based on the
filename. If it's a script (i.e. not a *.pm) the package name is
'main'.

=item version($package)

Returns the version as defined by the $VERSION variable for the
package as returned by the C<name> method if no arguments are
given. If given the name of a package it will attempt to return the
version of that package if it is specified in the file.

=item filename()

Returns the absolute path to the file.

=item packages_inside()

Returns a list of packages.

=item pod_inside()

Returns a list of POD sections.

=item contains_pod()

Returns true if there is any POD in the file.

=item pod($section)

Returns the POD data in the given section.

=item find_module_by_name($module, \@dirs)

Returns the path to a module given the module or package name. A list
of directories can be passed in as an optional paramater, otherwise
@INC is searched.

Can be called as either an object or a class method.

=item find_module_dir_by_name($module, \@dirs)

Returns the entry in C<@dirs> (or C<@INC> by default) that contains
the module C<$module>. A list of directories can be passed in as an
optional paramater, otherwise @INC is searched.

Can be called as either an object or a class method.

=back


=head1 AUTHOR

Ken Williams <ken@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>


=head1 COPYRIGHT

Copyright (c) 2001-2005 Ken Williams.  All rights reserved.

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


=head1 SEE ALSO

perl(1), L<Module::Build>(3)

=cut
Commit	Line	Data
bb4e9162	1	package Module::Build::ModuleInfo;
	2
	3	# This module provides routines to gather information about
	4	# perl modules (assuming this may be expanded in the distant
	5	# parrot future to look at other types of modules).
	6
	7	use strict;
	8
	9	use File::Spec;
	10	use IO::File;
b3dfda33	11	use Module::Build::Version;
bb4e9162	12
	13
	14	my $PKG_REGEXP = qr/ # match a package declaration
	15	^[\s\{;]* # intro chars on a line
	16	package # the word 'package'
	17	\s+ # whitespace
	18	([\w:]+) # a package name
	19	\s* # optional whitespace
	20	; # semicolon line terminator
	21	/x;
	22
	23	my $VARNAME_REGEXP = qr/ # match fully-qualified VERSION name
	24	([\$]) # sigil - $ or
	25	(
	26	( # optional leading package name
	27	(?:::\|\')? # possibly starting like just :: (ala $::VERSION)
	28	(?:\w+(?:::\|\'))* # Foo::Bar:: ...
	29	)?
	30	VERSION
	31	)\b
	32	/x;
	33
	34	my $VERS_REGEXP = qr/ # match a VERSION definition
	35	(?:
	36	\(\s$VARNAME_REGEXP\s\) # with parens
	37	\|
	38	$VARNAME_REGEXP # without parens
	39	)
	40	\s*
	41	=[^=~] # = but not ==, nor =~
	42	/x;
	43
	44
	45	sub new_from_file {
	46	my $package = shift;
	47	my $filename = File::Spec->rel2abs( shift );
	48	return undef unless defined( $filename ) && -f $filename;
	49	return $package->_init( undef, $filename, @_ );
	50	}
	51
	52	sub new_from_module {
	53	my $package = shift;
	54	my $module = shift;
	55	my %props = @_;
	56	$props{inc} \|\|= \@INC;
	57	my $filename = $package->find_module_by_name( $module, $props{inc} );
	58	return undef unless defined( $filename ) && -f $filename;
	59	return $package->_init( $module, $filename, %props );
	60	}
	61
	62	sub _init {
	63	my $package = shift;
	64	my $module = shift;
	65	my $filename = shift;
	66
	67	my %props = @_;
	68	my( %valid_props, @valid_props );
	69	@valid_props = qw( collect_pod inc );
	70	@valid_props{@valid_props} = delete( @props{@valid_props} );
	71	warn "Unknown properties: @{[keys %props]}\n" if scalar( %props );
	72
	73	my %data = (
	74	module => $module,
	75	filename => $filename,
76	version => undef,
77	packages => [],
78	versions => {},
79	pod => {},
80	pod_headings => [],
81	collect_pod => 0,
82
83	%valid_props,
84	);
85
86	my $self = bless( \%data, $package );
87
88	$self->_parse_file();
89
90	unless ( $self->{module} && length( $self->{module} ) ) {
91	my( $v, $d, $f ) = File::Spec->splitpath( $self->{filename} );
92	if ( $f =~ /\.pm$/ ) {
93	$f =~ s/\..+$//;
94	my @candidates = grep /$f$/, @{$self->{packages}};
95	$self->{module} = shift( @candidates ); # punt
96	} else {
97	if ( grep /main/, @{$self->{packages}} ) {
98	$self->{module} = 'main';
99	} else {
100	$self->{module} = $self->{packages}[0] \|\| '';
101	}
102	}
103	}
104
105	$self->{version} = $self->{versions}{$self->{module}}
106	if defined( $self->{module} );
107
108	return $self;
109	}
110
111	# class method
112	sub _do_find_module {
113	my $package = shift;
114	my $module = shift \|\| die 'find_module_by_name() requires a package name';
115	my $dirs = shift \|\| \@INC;
116
117	my $file = File::Spec->catfile(split( /::/, $module));
118	foreach my $dir ( @$dirs ) {
119	my $testfile = File::Spec->catfile($dir, $file);
120	return [ File::Spec->rel2abs( $testfile ), $dir ]
121	if -e $testfile and !-d _; # For stuff like ExtUtils::xsubpp
122	return [ File::Spec->rel2abs( "$testfile.pm" ), $dir ]
123	if -e "$testfile.pm";
124	}
125	return;
126	}
127
128	# class method
129	sub find_module_by_name {
130	my $found = shift()->_do_find_module(@_) or return;
131	return $found->[0];
132	}
133
134	# class method
135	sub find_module_dir_by_name {
136	my $found = shift()->_do_find_module(@_) or return;
137	return $found->[1];
138	}
139
140
141	# given a line of perl code, attempt to parse it if it looks like a
142	# $VERSION assignment, returning sigil, full name, & package name
143	sub _parse_version_expression {
144	my $self = shift;
145	my $line = shift;
146
147	my( $sig, $var, $pkg );
148	if ( $line =~ $VERS_REGEXP ) {
149	( $sig, $var, $pkg ) = $2 ? ( $1, $2, $3 ) : ( $4, $5, $6 );
150	if ( $pkg ) {
151	$pkg = ($pkg eq '::') ? 'main' : $pkg;
152	$pkg =~ s/::$//;
153	}
154	}
155
156	return ( $sig, $var, $pkg );
157	}
158
159	sub _parse_file {
160	my $self = shift;
161
162	my $filename = $self->{filename};
163	my $fh = IO::File->new( $filename )
164	or die( "Can't open '$filename': $!" );
165
166	my( $in_pod, $seen_end, $need_vers ) = ( 0, 0, 0 );
167	my( @pkgs, %vers, %pod, @pod );
168	my $pkg = 'main';
169	my $pod_sect = '';
170	my $pod_data = '';
171
172	while (defined( my $line = <$fh> )) {
173
174	chomp( $line );
175	next if $line =~ /^\s*#/;
176
177	$in_pod = ($line =~ /^=(?!cut)/) ? 1 : ($line =~ /^=cut/) ? 0 : $in_pod;
178
0ec9ad96	179	# Would be nice if we could also check $in_string or something too
	180	last if !$in_pod && $line =~ /^__(?:DATA\|END)__$/;
	181
bb4e9162	182	if ( $in_pod \|\| $line =~ /^=cut/ ) {
	183
	184	if ( $line =~ /^=head\d\s+(.+)\s*$/ ) {
	185	push( @pod, $1 );
	186	if ( $self->{collect_pod} && length( $pod_data ) ) {
	187	$pod{$pod_sect} = $pod_data;
	188	$pod_data = '';
	189	}
	190	$pod_sect = $1;
	191
	192
	193	} elsif ( $self->{collect_pod} ) {
	194	$pod_data .= "$line\n";
	195
	196	}
	197
	198	} else {
	199
	200	$pod_sect = '';
	201	$pod_data = '';
	202
	203	# parse $line to see if it's a $VERSION declaration
	204	my( $vers_sig, $vers_fullname, $vers_pkg ) =
	205	$self->_parse_version_expression( $line );
	206
	207	if ( $line =~ $PKG_REGEXP ) {
	208	$pkg = $1;
	209	push( @pkgs, $pkg ) unless grep( $pkg eq $_, @pkgs );
	210	$vers{$pkg} = undef unless exists( $vers{$pkg} );
	211	$need_vers = 1;
	212
	213	# VERSION defined with full package spec, i.e. $Module::VERSION
	214	} elsif ( $vers_fullname && $vers_pkg ) {
	215	push( @pkgs, $vers_pkg ) unless grep( $vers_pkg eq $_, @pkgs );
	216	$need_vers = 0 if $vers_pkg eq $pkg;
	217
	218	my $v =
	219	$self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
	220	unless ( defined $vers{$vers_pkg} && length $vers{$vers_pkg} ) {
	221	$vers{$vers_pkg} = $v;
	222	} else {
	223	warn <<"EOM";
	224	Package '$vers_pkg' already declared with version '$vers{$vers_pkg}'
	225	ignoring new version '$v'.
	226	EOM
	227	}
	228
	229	# first non-comment line in undeclared package main is VERSION
	230	} elsif ( !exists($vers{main}) && $pkg eq 'main' && $vers_fullname ) {
	231	$need_vers = 0;
	232	my $v =
	233	$self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
	234	$vers{$pkg} = $v;
	235	push( @pkgs, 'main' );
	236
	237	# first non-comement line in undeclared packge defines package main
	238	} elsif ( !exists($vers{main}) && $pkg eq 'main' && $line =~ /\w+/ ) {
	239	$need_vers = 1;
	240	$vers{main} = '';
	241	push( @pkgs, 'main' );
	242
	243	# only keep if this is the first $VERSION seen
	244	} elsif ( $vers_fullname && $need_vers ) {
	245	$need_vers = 0;
246	my $v =
247	$self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
248
249
250	unless ( defined $vers{$pkg} && length $vers{$pkg} ) {
251	$vers{$pkg} = $v;
252	} else {
253	warn <<"EOM";
254	Package '$pkg' already declared with version '$vers{$pkg}'
255	ignoring new version '$v'.
256	EOM
257	}
258
259	}
260
261	}
262
263	}
264
265	if ( $self->{collect_pod} && length($pod_data) ) {
266	$pod{$pod_sect} = $pod_data;
267	}
268
269	$self->{versions} = \%vers;
270	$self->{packages} = \@pkgs;
271	$self->{pod} = \%pod;
272	$self->{pod_headings} = \@pod;
273	}
274
275	sub _evaluate_version_line {
276	my $self = shift;
277	my( $sigil, $var, $line ) = @_;
278
279	# Some of this code came from the ExtUtils:: hierarchy.
280
281	my $eval = qq{q# Hide from _packages_inside()
282	#; package Module::Build::ModuleInfo::_version;
283	no strict;
284
285	local $sigil$var;
286	\$$var=undef; do {
287	$line
288	}; \$$var
289	};
bb4e9162	290
b3dfda33	291	local $^W;
b3dfda33	292	# Try and get the $VERSION
bb4e9162	293	my $result = eval $eval;
bb4e9162	294	warn "Error evaling version line '$eval' in $self->{filename}: $@\n" if $@;
bb4e9162	295
b3dfda33	296	# Bless it into our own version class
b3dfda33	297	$result = Module::Build::Version->new($result);
bb4e9162	298
	299	return $result;
	300	}
	301
	302
	303	############################################################
	304
	305	# accessors
	306	sub name { $_[0]->{module} }
	307
	308	sub filename { $_[0]->{filename} }
	309	sub packages_inside { @{$_[0]->{packages}} }
	310	sub pod_inside { @{$_[0]->{pod_headings}} }
	311	sub contains_pod { $#{$_[0]->{pod_headings}} }
	312
	313	sub version {
	314	my $self = shift;
	315	my $mod = shift \|\| $self->{module};
	316	my $vers;
	317	if ( defined( $mod ) && length( $mod ) &&
	318	exists( $self->{versions}{$mod} ) ) {
	319	return $self->{versions}{$mod};
	320	} else {
	321	return undef;
	322	}
	323	}
	324
	325	sub pod {
	326	my $self = shift;
	327	my $sect = shift;
	328	if ( defined( $sect ) && length( $sect ) &&
	329	exists( $self->{pod}{$sect} ) ) {
	330	return $self->{pod}{$sect};
	331	} else {
	332	return undef;
	333	}
	334	}
	335
	336	1;
	337
	338	__END__
	339
	340	=head1 NAME
	341
	342	ModuleInfo - Gather package and POD information from a perl module files
	343
	344
	345	=head1 DESCRIPTION
	346
	347	=over 4
	348
	349	=item new_from_file($filename, collect_pod => 1)
	350
	351	Construct a ModuleInfo object given the path to a file. Takes an optional
	352	arguement C<collect_pod> which is a boolean that determines whether
	353	POD data is collected and stored for reference. POD data is not
	354	collected by default. POD headings are always collected.
	355
	356	=item new_from_module($module, collect_pod => 1, inc => \@dirs)
	357
	358	Construct a ModuleInfo object given a module or package name. In addition
	359	to accepting the C<collect_pod> argument as described above, this
	360	method accepts a C<inc> arguemnt which is a reference to an array of
	361	of directories to search for the module. If none are given, the
362	default is @INC.
363
364	=item name()
365
366	Returns the name of the package represented by this module. If there
367	are more than one packages, it makes a best guess based on the
368	filename. If it's a script (i.e. not a *.pm) the package name is
369	'main'.
370
371	=item version($package)
372
373	Returns the version as defined by the $VERSION variable for the
374	package as returned by the C<name> method if no arguments are
375	given. If given the name of a package it will attempt to return the
376	version of that package if it is specified in the file.
377
378	=item filename()
379
380	Returns the absolute path to the file.
381
382	=item packages_inside()
383
384	Returns a list of packages.
385
386	=item pod_inside()
387
388	Returns a list of POD sections.
389
390	=item contains_pod()
391
392	Returns true if there is any POD in the file.
393
394	=item pod($section)
395
396	Returns the POD data in the given section.
397
398	=item find_module_by_name($module, \@dirs)
399
400	Returns the path to a module given the module or package name. A list
401	of directories can be passed in as an optional paramater, otherwise
402	@INC is searched.
403
404	Can be called as either an object or a class method.
405
406	=item find_module_dir_by_name($module, \@dirs)
407
408	Returns the entry in C<@dirs> (or C<@INC> by default) that contains
409	the module C<$module>. A list of directories can be passed in as an
410	optional paramater, otherwise @INC is searched.
411
412	Can be called as either an object or a class method.
413
414	=back
415
416
417	=head1 AUTHOR
418
419	Ken Williams <ken@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
420
421
422	=head1 COPYRIGHT
423
424	Copyright (c) 2001-2005 Ken Williams. All rights reserved.
425
426	This library is free software; you can redistribute it and/or
427	modify it under the same terms as Perl itself.
428
429
430	=head1 SEE ALSO
431
dc8021d3	432	perl(1), L<Module::Build>(3)
bb4e9162	433
	434	=cut
	435