NAME

Dist::Zilla::Plugin::Manifest::Write - Have annotated distribution manifest

VERSION

Version v0.9.7, released on 2016-12-14 22:51 UTC.

WHAT?

Dist-Zilla-Plugin-Manifest-Write (or Manifest::Write for brevity) is a plugin for Dist::Zilla, a replacement for standard plugin Manifest. Manifest::Write writes annotated distribution manifest: each filename is followed by a comment explaining origin of the file: if it is a part of software, meta information, or 3rd-party file. Also it can exclude built files from distribution, e. g. extra tests have to be built (to run) but need not be distributed.

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 distribution manifest, read the plugin user manual. General topics like getting source, building, installing, bug reporting and some others are covered in the README.

SYNOPSIS

package ManifestWithFileSize;

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 _file_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

In order to add a manifest file to the distribution, Dist::Zilla::Plugin::Manifest::Write class consumes Dist::Zilla::Role::FileGatherer role. To meet the role requirements, the class implements gather_files method. Other methods are supporting helpers for this one.

Most of attributes are initialized by builders for easier customization by subclassing. Code is also divided into small methods for the same purpose.

CLASS METHODS

BUILDARGS

The method splits values of source_providers option into separate plugin names using whitespaces as delimiters, combines result of splitting with source_provider option values, then filters out empty values. Resulting ArrayRef saved as source_providers options.

The same for metainfo_providers and metainfo_provider options.

OBJECT ATTRIBUTES

manifest

Name of manifest file to write.

Str, read-only. Default value is 'MANIFEST'.

manifest_skip

Name of manifest.skip file to write.

Str, read-only. Default value is 'MANIFEST.SKIP'.

source_providers

List of plugin names. Enlisted plugins are considered as source file providers. A file added to distribution by any of these plugins is considered as source file.

ArrayRef[Str], read-only, default value is empty array. Init argument (and config file multi-value option) name is source_provider. (BUILDARGS also handles source_providers option.)

metainfo_providers

Like source_providers but enlists meta info file providers.

ArrayRef[Str], read-only, default value is CPANFile, Manifest, MetaYAML, MetaJSON, and the plugin itself. Init argument (and config file multi-value option) name is metainfo_provider. (BUILDARGS also handles metainfo_providers option.)

Note: Do not confuse Manifest::Write's term metainfo providers with Dist::Zilla's MetaProvider role. Plugins do MetaProvider role provide metadata, while Manifest::Write is interested in plugins which adds files containing metadata to the distribution (such plugins do FileInjector role, not MetaProvider).

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::Manifest::Write::Manual.

show_mungers

If 1, file mungers will be included into annotation. By default mungers are not included.

Bool, read-only. Default is 0.

deeds

This attribute maps internal file deed constants (SOURCE, META, OTHER) to user-visible names used in manifest (project name, metainfo, and 3rd party respectively).

HashRef[Str], read-only.

breeds

This attribute maps internal file deed constants ($ADDED and $BUILT) to user-visible names used in manifest. By default user-visible breed names are the same as internal identifiers.

HashRef[Str], read-only.

_providers

This attribute maps provider names to file deeds. It makes _file_deed method implementation simpler and faster.

HashRef[Str], read-only, not an init arg.

_dw

Max length of user-visible deed names.

Int, read-only, not an init arg.

OBJECT METHODS

before_build

This method is called by Dist::Zilla automatically before build. The method checks validity of source and metainfo provider names.

before_archive

This method is called by Dist::Zilla automatically before build the archive. The method prunes files found by file finders specified in the exclude_files option.

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.

_file_name

$str = $self->_file_name( $file );

Returns filename to be used in manifest. If filename does not include special characters (spaces, backslashes (\), apostrophes ('), hashes (#)), it is the same as real filename, otherwise filename encoded like Perl single-quoted string: backslashes and apostrophes are escaped, and entire filename is enclosed into apostrophes.

_file_comment

$str = $self->_file_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 calls _file_added_by then does post-processing: all filename set records are filtered out as insignificant and makes sure the log is not empty.

_file_added_by

$arrayref = $self->_file_added_by( $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 a more convenient for further processing form:

[ { action => …, name => …, package => …, line => … }, { … }, … ]

Do not call this method directly, use _file_history instead.

_file_deed

$str = $self->_file_deed( $file, $history );    # $SOURCE, $META, or $OTHER.

Returns internal identifier of file deed.

_file_breed

$str = $self->_file_breed( $file, $history );   # ADDED or BUILT.

Returns internal identifier of file breed, either $ADDED or $BUILT.

Current implementation checks file object class: if it is a Dist::Zilla::File::OnDisk, the file is added to distribution, otherwise the file is built.

_file_adder

$str = $self->_file_adder( $file, $history );

Returns moniker of the plugin added the file to the distribution.

_file_mungers

@list = $self->_file_mungers( $file, $history );

If show_mungers attribute is true, returns list of monikers of the plugins munged the file. Otherwise returns empty list.

_file_munger

$str = $self->_file_munger( $file, $history->[ $n ] );

The method is supposed to return a moniker of plugin munged the file. But… see "Correctness of Information" in Dist::Zilla::Plugin::Manifest::Write.

mvp_multivalue_args

This method tells Dist::Zilla that source_provider, source_providers, metainfo_provider, and metainfo_providers are multi-value options (i. e. can be specified in 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_moniker

$str = __plugin_moniker( 'Dist::Zilla::Plugin::Name' );     # 'Name'
$str = __plugin_moniker( 'Non::Standard::Name' );           # '=Non::Standard::Name'
$str = __plugin_moniker( $plugin );

The function takes either reference to a plugin object or a string, package name, and returns Dist::Zilla plugin moniker: 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' );   # returns 'Dist::Zilla::Plugin::Name'
$str = __package_name( '=Name' );  # returns 'Name'
$str = __package_name( $plugin );

This is operation opposite to __plugin_moniker. It takes either reference to plugin object, or string, plugin moniker, 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 object.

EXAMPLES

Manifest with File Size

A module shown in Synopsis is a real example. Its result looks like:

# This file was generated with ManifestWithFileSize 0.007.
MANIFEST     #  metainfo file built by =ManifestWithFileSize
dist.ini     #     Dummy file added by GatherDir (239 bytes)
lib/Dummy.pm #     Dummy file added by GatherDir (22 bytes)

AUTHOR

Van de Bugger <van.de.bugger@gmail.com>

COPYRIGHT AND LICENSE

License GPLv3+: The GNU General Public License version 3 or later <http://www.gnu.org/licenses/gpl-3.0.txt>.

This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

To install Dist::Zilla::Plugin::Manifest::Write, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Dist::Zilla::Plugin::Manifest::Write

CPAN shell

perl -MCPAN -e shell
install Dist::Zilla::Plugin::Manifest::Write

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)