From: David Golden Date: Wed, 3 Aug 2011 01:38:30 +0000 (-0400) Subject: Edited documentation X-Git-Tag: release_1.0.5^0 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6290f67cbac16f68d0c2b536fa9d5457230e2e41;p=p5sagit%2FModule-Metadata.git Edited documentation --- diff --git a/Changes b/Changes index 0280df0..8e2d20b 100644 --- a/Changes +++ b/Changes @@ -1,7 +1,9 @@ -1.0.5 2011-08-01 08:24:00 +1.0.5 2011-08-02 09:45:00 - Localize $package::VERSION during version discovery (MIYAGAWA) - Fix references to Module::Build::ModuleInfo [RT #66133] (DAGOLDEN) - Added 'new_from_handle()' method [RT #68875] (DAGOLDEN) + - Improved documentation (SYNOPSIS, broke out class/object method, and + other minor edits) (DAGOLDEN) 1.0.4 2011-02-03 07:55:00 - Fix broken metadata.t when @INC has relative paths (JJORE) diff --git a/lib/Module/Metadata.pm b/lib/Module/Metadata.pm index 8629a98..514dd1c 100644 --- a/lib/Module/Metadata.pm +++ b/lib/Module/Metadata.pm @@ -665,18 +665,38 @@ sub pod { Module::Metadata - Gather package and POD information from perl module files +=head1 SYNOPSIS + + use Module::Metadata; + + # information about a .pm file + my $info = Module::Metadata->new_from_file( $file ); + my $version = $info->version; + + # information about a directory full of .pm files + my $provides = + Module::Metadata->package_versions_from_directory('lib'); + =head1 DESCRIPTION +This module provides a standard way to gather metadata about a .pm file +without executing unsafe code. + +=head1 USAGE + +=head2 Class methods + =over 4 -=item new_from_file($filename, collect_pod => 1) +=item C<< new_from_file($filename, collect_pod => 1) >> -Construct a C object given the path to a file. Takes an optional -argument C 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. +Construct a C object given the path to a file. Takes an +optional argument C 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. Returns undef if the filename +does not exist. -=item new_from_handle($handle, $filename, collect_pod => 1) +=item C<< new_from_handle($handle, $filename, collect_pod => 1) >> This works just like C, except that a handle can be provided as the first argument. Note that there is no validation to confirm that the @@ -684,50 +704,15 @@ handle is a handle or something that can act like one. Passing something that isn't a handle will cause a exception when trying to read from it. The C argument is mandatory or undef will be returned. -=item new_from_module($module, collect_pod => 1, inc => \@dirs) +=item C<< new_from_module($module, collect_pod => 1, inc => \@dirs) >> Construct a C object given a module or package name. In addition to accepting the C argument as described above, this method accepts a C argument 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 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. +default is @INC. Returns undef if the module cannot be found. -=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) +=item C<< 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 parameter, otherwise @@ -735,7 +720,7 @@ of directories can be passed in as an optional parameter, otherwise Can be called as either an object or a class method. -=item find_module_dir_by_name($module, \@dirs) +=item C<< 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 @@ -743,7 +728,7 @@ optional parameter, otherwise @INC is searched. Can be called as either an object or a class method. -=item package_versions_from_directory($dir, \@files?) +=item C<< package_versions_from_directory($dir, \@files?) >> Scans C<$dir> for .pm files (unless C<@files> is given, in which case looks for those files in C<$dir> - and reads each file for packages and versions, @@ -757,23 +742,66 @@ returning a hashref of the form: 'OtherPackage::Name' => ... } -=item log_info (internal) +=item C<< log_info (internal) >> Used internally to perform logging; imported from Log::Contextual if Log::Contextual has already been loaded, otherwise simply calls warn. =back +=head2 Object methods + +=over 4 + +=item C<< 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 C<< version($package) >> + +Returns the version as defined by the $VERSION variable for the +package as returned by the C 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 C<< filename() >> + +Returns the absolute path to the file. + +=item C<< packages_inside() >> + +Returns a list of packages. + +=item C<< pod_inside() >> + +Returns a list of POD sections. + +=item C<< contains_pod() >> + +Returns true if there is any POD in the file. + +=item C<< pod($section) >> + +Returns the POD data in the given section. + +=back + =head1 AUTHOR -Ken Williams , Randy W. Sims +Original code from Module::Build::ModuleInfo by Ken Williams +, Randy W. Sims Released as Module::Metadata by Matt S Trout (mst) with -assistance from David Golden (xdg) +assistance from David Golden (xdg) . =head1 COPYRIGHT -Copyright (c) 2001-2011 Ken Williams. All rights reserved. +Original code Copyright (c) 2001-2011 Ken Williams. +Additional code Copyright (c) 2010-2011 Matt Trout and David Golden. +All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.