NAME
Dist::Zilla::Plugin::Manifest::Write - Have annotated MANIFEST in your distribution
VERSION
Version v0.8.1, released on 2015-09-15 21:00 UTC.
WHAT?
Manifest::Write is a plugin for Dist::Zilla, a replacement for standard plugin Manifest. Manifest::Write writes annotated MANIFEST: each filename is followed by a comment, explaining origin of the file, whether it is part of software, meta information, or 3rd party file.
This is Dist::Zilla::Plugin::Manifest::Write module documentation. Read this if you are going to hack or extend Manifest::Write.
If you want to have annotated MANIFEST in your distribution, read the manual. General topics like getting source, building, installing, bug reporting and some others are covered in the README.
SYNOPSIS
package Dist::Zilla::Plugin::Manifest::Write::FileSize;
use Moose;
use namespace::autoclean;
extends 'Dist::Zilla::Plugin::Manifest::Write';
our $VERSION = '0.007';
# Overload any method or modify it with all the Moose power, e. g.:
around _comment => sub {
my ( $orig, $self, $file ) = @_;
my $comment = $self->$orig( $file );
if ( $file->name ne $self->manifest ) { # Avoid infinite recursion.
$comment .= sprintf( ' (%d bytes)', length( $file->encoded_content ) );
};
return $comment;
};
__PACKAGE__->meta->make_immutable;
1;DESCRIPTION
Dist::Zilla::Plugin::Manifest::Write class plays Dist::Zilla::Role::FileGatherer role. To perform the role, the class implements gather_files method. Other methods are supporting helpers for this one.
Most of attributes are initialized by builder for easier customization by subclassing. Code is also divided into small methods for the same purpose.
CLASS METHODS
BUILDARGS
The method splits source_providers and metainfo_providers options. It allows user to specify multiple plugin names in one line in dist.ini file, e. g.:
[Manifest::Write]
source_providers = GatherDir GatherDir::TemplateOBJECT ATTRIBUTES
strict
Strictness of checking source and metainfo provider names: -1 (no checks), 0 (some mistakes are fatal, some are not), or 1 (all mistakes are fatal).
Int, read-only. Default is 1.
See "strict" in Dist::Zilla::Plugin::Manifets::Write::Manual.
manifest
Name of manifest file to write.
Str, read-only. Default value is 'MANIFEST'.
source_list
Array of source providers.
ArrayRef[Str], read-only, default value is empty array. Init argument (and configure file option) name is source_providers.
metainfo_list
Array of metainfo providers.
ArrayRef[Str], read-only, default value is empty array. Init argument (and configure file option) name is metainfo_providers.
source_hash
Hash of source providers (plugin name => boolean), lazily initialized from source_list. Introduced to make check "is plugin a source provider?" easier.
HashRef[Str], read-only, not an init arg.
metainfo_hash
Like source_hash, but for metainfo providers.
file_deeds
"File deed" is a file ownership: if file belongs to a project, is a metainfo, or third-party file.
This attribute maps internal file deed identifiers (source, metainfo, other) to user-visible names used in manifest (project name, metainfo, and 3rd party respectively).
HashRef, read-only.
file_deed_width
Width of file deed column. Computed from file deed visible names.
Int, read-only.
OBJECT METHODS
before_build
The method checks validity of source and metainfo provider names.
gather_files
This is the main method of the class. It adds a file with name $self->manifest to the distribution. File content is specified by CodeRef to postpone actual file creation. Being evaluated, the code iterates through all the files in distribution in alphabetical order, and fulfills the manifest with filenames and comments.
_comment
$str = $self->_comment( $file ); # Without leading sharp.The method returns comment to be used with the specified file. Comment should not include leading sharp character (#).
_file_history
$arrayref = $self->_file_history( $file );The method parses file's added_by log. Internally, added_by log is a list of strings. Here are few examples:
content added by COPYING (Dist::Zilla::Plugin::GenerateFile line 114)
filename set by GatherFromManifest (Dist::Zilla::Plugin::GatherFromManifest line 125)
encoded_content added by GatherFromManifest (Dist::Zilla::Plugin::GatherFromManifest line 126)
text from coderef added by MetaJSON (Dist::Zilla::Plugin::MetaJSON line 83)
content set by TemplateFiles (Dist::Zilla::Plugin::TemplateFiles line 35)
content set by OurPkgVersion (Dist::Zilla::Plugin::OurPkgVersion line 82)
content set by PodWeaver (Dist::Zilla::Plugin::PodWeaver line 175)Thus, each string in added_by log follows the format:
<action> by <name> (<package> line <number>)The method parses these strings and returns file history in more convenient for further processing form:
[ { action => …, name => …, package => …, line => … }, { … }, … ]_plugin
$str = $self->_plugin( $history->[ $n ] );The method calculates plugin err… not name, but err… TODO!
_file_name
$str = $self->_file_name( $file );Returns filename to be used in manifest. If filename does not include special characters (spaces, backslashes (\), apostrophes (')), it is the same as real filename, otherwise special characters are escaped, and entire filename is enclosed into apostrophes.
_file_deed
$str = $self->_file_deed( $file, $history ); # e. g. '3rd party'.Returns user-visible name of file deed.
_file_breed
$str = $self->_file_breed( $file, $history ); # 'added' or 'built'.Returns file breed, i. e. how the file appeared in the distribution — was it copied from project sources (added) or generated (built).
Current implementations checks file object class: if it is a Dist::Zilla::File::OnDisk, the file added to distribution, otherwise file built.
mvp_multivalue_args
This method tells Dist::Zilla that source_providers and metainfo_providers are multi-value options (i. e. can be specified in dist.ini several times).
FUNCTIONS
I would expect to find these functions in Dist::Zilla. Actually, Dist::Zilla::Util defines the function expand_config_package_name, but that function "is likely to change or go away" and there is no reverse transformation.
__plugin_name
$str = __plugin_name( 'Dist::Zilla::Plugin::Name' ); # 'Name'
$str = __plugin_name( $plugin );The function takes either reference to a plugin object or a string, package name, and returns Dist::Zilla plugin name: If its package name begins with Dist::Zilla::Plugin::, this common prefix is dropped, otherwise the package name prepended with =.
__package_name
$str = __package_name( 'Name' ); # 'Dist::Zilla::Plugin::Name'
$str = __package_name( $plugin );This is operation opposite to __plugin_name. It takes either reference to plugin object, or string, plugin name, and returns package name.
This function is similar to expand_config_package_name from Dist::Zilla::Util, with minor difference: this function works with plugins only (not with plugin bundles and stashes), and accepts also reference to plugin objects.
SEE ALSO
- Dist::Zilla
- Dist::Zilla::Role
- Dist::Zilla::Role::Plugin
- Dist::Zilla::Role::FileInjector
- Dist::Zilla::Role::FileGatherer
- Dist::Zilla::Plugin::Manifest
- Dist::Zilla::Plugin::Manifest::Write::Manual
AUTHOR
Van de Bugger <van.de.bugger@gmail.com>
COPYRIGHT AND LICENSE
Copyright © 2015 Van de Bugger
This file is part of perl-Dist-Zilla-Plugin-Manifest-Write.
perl-Dist-Zilla-Plugin-Manifest-Write is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
perl-Dist-Zilla-Plugin-Manifest-Write is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with perl-Dist-Zilla-Plugin-Manifest-Write. If not, see <http://www.gnu.org/licenses/>.