Provided by: libdist-metadata-perl_0.927-2_all bug

NAME

       Dist::Metadata::Dist - Base class for format-specific implementations

VERSION

       version 0.927

SYNOPSIS

         # don't use this, use a subclass

DESCRIPTION

       This is a base class for different dist formats.

       The following methods must be defined by subclasses:

       •   "file_content"

       •   "find_files"

METHODS

   new
       Simple constructor that subclasses can inherit.  Ensures the presence of
       "required_attribute" if defined by the subclass.

   default_file_spec
       Defaults to 'Native' in the base class which will let File::Spec determine the value.

   determine_name_and_version
       Some dist formats may define a way to determine the name and version.

   determine_packages
         $packages = $dist->determine_packages(@files);

       Search the specified files (or all files if unspecified) for perl packages.

       Extracts the files to a temporary directory if necessary and uses Module::Metadata to
       discover package names and versions.

   extract_into
         $ddir = $dist->extract_into($dir);
         ($ddir, @dfiles) = $dist->extract_into($dir, @files);

       Extracts the specified files (or all files if not specified) into the specified directory.

       In list context this returns a list of the directory (which may be a subdirectory of the
       $dir passed in) and the files extracted (in native OS (on-disk) format).

       In scalar context just the directory is returned.

   file_content
       Returns the content for the specified file from the dist.

       This must be defined by subclasses.

   file_checksum
         $dist->file_checksum('lib/Mod/Name.pm', 'sha256');

       Returns a checksum (hex digest) of the file content.

       The Digest module is used to generate the checksums.  The value specified should be one
       accepted by "Digest->new".  A small effort is made to translate simpler names like "md5"
       into "MD5" and "sha1" into "SHA-1" (which are the names Digest expects).

       If the type of checksum is not specified "md5" will be used.

   find_files
       Determine the files contained in the dist.

       This is called from "list_files" and cached on the object.

       This must be defined by subclasses.

   file_spec
       Returns the OS name of the File::Spec module used for this format.  This is mostly so
       subclasses can define a specific one (as "default_file_spec") if necessary.

       A "file_spec" attribute can be passed to the constructor to override the default.

       NOTE: This is used for the internal format of the dist.  Tar archives, for example, are
       always in unix format.  For operations outside of the dist, the format determined by
       File::Spec will always be used.

   full_path
         $dist->full_path("lib/Mod.pm"); # "root-dir/lib/Mod.pm"

       Used internally to put the "root" directory back onto the file.

   list_files
       Returns a list of the files in the dist starting at the dist root.

       This calls "find_files" to get a listing of the contents of the dist, determines (and
       caches) the root directory (if any), caches and returns the list of files with the root
       dir stripped.

         @files = $dist->list_files;
         # something like qw( README META.yml lib/Mod.pm )

   name
       The dist name if it could be determined.

   packages_from_directory
         $provides = $dist->packages_from_directory($dir, @files);

       Determines the packages provided by the perl modules found in a directory.  This is thin
       wrapper around "package_versions_from_directory" in Module::Metadata.  It returns a
       hashref like "provides" in CPAN::Meta::Spec.

       NOTE: $dir must be a physical directory on the disk, therefore @files (if specified) must
       be in native OS format.  This function is called internally from "determine_packages"
       (which calls physical_directory (which calls "extract_into")) which manages these
       requirements.

   parse_name_and_version
         ($name, $version) = $dist->parse_name_and_version($path);

       Attempt to parse name and version from the provided string.  This will work for dists
       named like "Dist-Name-1.0".

   path_class_dir
       Returns the class name used for Path::Class::Dir objects.

   path_class_file
       Returns the class name used for Path::Class::File objects.

   path_classify_dir
       This is a shortcut for returning an object representing the provided dir utilizing
       "path_class_dir" and "file_spec".

   path_classify_file
       This is a shortcut for returning an object representing the provided file utilizing
       "path_class_file" and "file_spec".

   perl_files
       Returns the subset of "list_files" that look like perl files.  Currently returns anything
       matching "/\.pm$/"

       TODO: This should probably be customizable.

   physical_directory
         $dir = $dist->physical_directory();
         ($dir, @dir_files) = $dist->physical_directory(@files);

       Returns the path to a physical directory on the disk where the specified files (if any)
       can be found.

       For in-memory formats this will make a temporary directory and write the specified files
       (or all files) into it.

       The return value is the same as "extract_into": In scalar context the path to the
       directory is returned.  In list context the (possibly adjusted) paths to any specified
       files are appended to the return value.

   remove_root_dir
         my ($dir, @rel) = $dm->remove_root_dir(@files);

       If all the @files are beneath the same root directory (as is normally the case) this will
       strip the root directory off of each file and return a list of the root directory and the
       stripped files.

       If there is no root directory the first element of the list will be "undef".

   required_attribute
       A single attribute that is required by the class.  Subclasses can define this to make
       "new" "croak" if it isn't present.

   root
       Returns the root directory of the dist (if there is one).

   set_name_and_version
       This is a convenience method for setting the name and version if they haven't already been
       set.  This is often called by "determine_name_and_version".

   version
       Returns the version if it could be determined from the dist.

SEE ALSO

       •   Dist::Metadata::Tar - for examining a tar file

       •   Dist::Metadata::Dir - for a directory already on the disk

       •   Dist::Metadata::Struct - for mocking up a dist with perl data structures

AUTHOR

       Randy Stauner <rwstauner@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.