Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Dist::Metadata(3)     User Contributed Perl Documentation    Dist::Metadata(3)

NAME
       Dist::Metadata -	Information about a perl module	distribution

VERSION
       version 0.926

SYNOPSIS
	 my $dist = Dist::Metadata->new(file =>	$path_to_archive);

	 my $description = sprintf "Dist %s (%s)", $dist->name,	$dist->version;

	 my $provides =	$dist->package_versions;
	 while(	my ($package, $version)	= each %$provides ){
	   print "$description includes	$package $version\n";
	 }

DESCRIPTION
       This module provides an easy interface for getting various metadata
       about a Perl module distribution.

       It takes	care of	the common logic of:

       o   reading a tar file (Archive::Tar)

       o   finding and reading the correct META	file if	the distribution
	   contains one	(CPAN::Meta)

       o   and determining some	of the metadata	if there is no META file
	   (Module::Metadata, CPAN::DistnameInfo)

       This is mostly a	wrapper	around CPAN::Meta providing an easy interface
       to find and load	the meta file from a tar.gz file.  A dist can also be
       represented by a	directory or merely a structure	of data.

       If the dist does	not contain a meta file	the module will	attempt	to
       determine some of that data from	the dist.

       NOTE: This interface is still being defined.  Please submit any
       suggestions or concerns.

METHODS
   new
	 Dist::Metadata->new(file => $path);

       A dist can be represented by a tar file,	a directory, or	a data
       structure.

       The format will be determined by	the presence of	the following options
       (checked	in this	order):

       o   "struct" - hash of data to build a mock dist; See
	   Dist::Metadata::Struct.

       o   "dir" - path	to the root directory of a dist

       o   "file" - the	path to	a .tar.gz file

       You can also slyly pass in your own object as a "dist" parameter	in
       which case this module will just	use that.  This	can be useful if you
       need to use your	own subclass (perhaps while developing a new format).

       Other options that can be specified:

       o   "name" - dist name

       o   "version" - dist version

       o   "determine_packages"	- boolean to indicate whether dist should be
	   searched for	packages if no META file is found.  Defaults to	true.

       o   "include_inner_packages" - When determining provided	packages the
	   default behavior is to only include packages	that match the name of
	   the file that defines them (like "Foo::Bar" matches "*/Bar.pm").
	   This	way only modules that can be loaded (via "use" or "require")
	   will	be returned (and "inner" packages will be ignored).  This
	   mimics the behavior of PAUSE.  Set this to true to include any
	   "inner" packages provided by	the dist (that are not otherwise
	   excluded by another mechanism (such as "no_index")).

   dist
       Returns the dist	object (subclass of Dist::Metadata::Dist).

   default_metadata
       Returns a hashref of default values used	to initialize a	CPAN::Meta
       object when a META file is not found.  Called from
       "determine_metadata".

   determine_metadata
       Examine the dist	and try	to determine metadata.	Returns	a hashref
       which can be passed to "new" in CPAN::Meta.  This is used when the dist
       does not	contain	a META file.

   determine_packages
	 my $provides =	$dm->determine_packages($meta);

       Attempt to determine packages provided by the dist.  This is used when
       the META	file does not include a	"provides" section and
       "determine_packages" is not set to false	in the constructor.

       If a CPAN::Meta object is not provided a	default	one will be used.
       Files contained in the dist and packages	found therein will be checked
       against the meta	object's "no_index" attribute (see "should_index_file"
       in CPAN::Meta and  "should_index_package" in CPAN::Meta).  By default
       this ignores any	files found in inc/, t/, or xt/	directories.

   load_meta
       Loads the metadata from the "dist".

   meta
       Returns the CPAN::Meta instance in use.

   meta_from_struct
	 $meta = $dm->meta_from_struct(\%struct);

       Passes the provided "\%struct" to "create" in CPAN::Meta	and returns
       the result.

   package_versions
	 $pv = $dm->package_versions();
	 # { 'Package::Name' =>	'1.0', 'Module::2' => '2.1' }

       Returns a simplified version of "provides": a hashref with package
       names as	keys and versions as values.

       This can	also be	called as a class method which will operate on a
       passed in hashref.

	 $pv = Dist::Metadata->package_versions(\%provides);

   module_info
       Returns a hashref of meta data for each of the packages provided	by
       this dist.

       The hashref starts with the same	data as	"provides" but additional data
       can be added to the output by specifying	options	in a hashref:

       "checksum"
	   Use the specified algorithm to compute a hex	digest of the file.
	   The type you	specify	will be	the key	in the returned	hashref.  You
	   can use an arrayref to specify more than one	type.

	     $dm->module_info({checksum	=> ['sha256', 'md5']});
	     # returns:
	     {
	       'Mod::Name' => {
		 file	 => 'lib/Mod/Name.pm',
		 version => '0.1',
		 md5	 => '258e88dcbd3cd44d8e7ab43f6ecb6af0',
		 sha256	 => 'f22136124cd3e1d65a48487cecf310771b2fd1e83dc032e3d19724160ac0ff71',
	       },
	     }

	   See "file_checksum" in Dist::Metadata::Dist for more	information.

       "provides"
	   The default is to start with	the hashref returned from "provides"
	   but you can pass in an alternate hashref using this key.

       Other options may be added in the future.

INHERITED METHODS
       The following methods are available on this object and simply call the
       corresponding method on the CPAN::Meta object.

       o
	    name

       o
	    provides

       o
	    version

TODO
       o   More	tests

       o   "trust_meta"	option (to allow setting it to false)

       o   Guess main module from dist name if no packages can be found

       o   Determine abstract?

       o   Add change log info (CPAN::Changes)?

       o   Subclass as "CPAN::Dist::Metadata" just so that it has "CPAN" in
	   the name?

       o   Use File::Find::Rule::Perl?

SEE ALSO
   Dependencies
       o   CPAN::Meta

       o   Module::Metadata

       o   CPAN::DistnameInfo

   Related Modules
       o   MyCPAN::Indexer

       o   CPAN::ParseDistribution

SUPPORT
   Perldoc
       You can find documentation for this module with the perldoc command.

	 perldoc Dist::Metadata

   Websites
       The following websites have more	information about this module, and may
       be of help to you. As always, in	addition to those websites please use
       your favorite search engine to discover more resources.

       o   MetaCPAN

	   A modern, open-source CPAN search engine, useful to view POD	in
	   HTML	format.

	   <http://metacpan.org/release/Dist-Metadata>

   Bugs	/ Feature Requests
       Please report any bugs or feature requests by email to
       "bug-dist-metadata at rt.cpan.org", or through the web interface	at
       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Metadata>. You
       will be automatically notified of any progress on the request by	the
       system.

   Source Code
       <https://github.com/rwstauner/Dist-Metadata>

	 git clone https://github.com/rwstauner/Dist-Metadata.git

AUTHOR
       Randy Stauner <rwstauner@cpan.org>

CONTRIBUTORS
       o   David Steinbrunner <dsteinbrunner@pobox.com>

       o   Jeffrey Ryan	Thalhammer <thaljef@cpan.org>

       o   Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2011 by Randy Stauner.

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

perl v5.32.0			  2015-04-29		     Dist::Metadata(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | INHERITED METHODS | TODO | SEE ALSO | SUPPORT | AUTHOR | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dist::Metadata&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help