NAME

Dist::Zilla::Plugin::Templates::File - Frequently used operations on include files

VERSION

Version v0.6.5, released on 2018-03-22 20:35 UTC.

SYNOPSIS

In a template:

    {{ include( 'as-is.txt' ); }}
    {{ include( 'verbatim.txt' )->indent; }}
    {{ include( 'template.txt' )->fill_in; }}
    {{ include( 'readme.pod' )->pod2text; }}
    {{ include( 'assa.txt' )->chomp->trim->indent; }}
    …

DESCRIPTION

This is a helper module for Dist::Zilla::Templates. It provides few frequently used operations on include files.

Usually objects are created by "include" function (see "include" in Dist::Zilla::Plugin::Templates).

The object evaluated in string context returns the file content, so

    $file->content

and

    "$file"

produces the same result.

OBJECT ATTRIBUTES

_plugin

Reference to the plugin created this object.

Object, read-only.

OBJECT METHODS

chomp

    $file->chomp();
    $file->chomp( $count );

Chomps the file content $count times. If $count is not specified, the method chomps all the trailing newlines (more exactly: all the trailing input record separators; see core function chomp for details).

Note: The methods chomps newlines from the end of file, not from each line.

The method returns $self for chaining.

fill_in

    $file->fill_in();
    $file->fill_in( \%variables, \%extra_args );

Calls plugin's fill_in_file method (which is defined in TextTemplater role), passing $self as the first argument. Returns $self.

Primary purpose of the method is including a file which is template itself:

    {{ include( 'doc/chapter1.pod' )->fill_in; }}

Without fill_in, doc/chapter1.pod is included as-is, Perl code fragments, if any, are not evaluated.

See "fill_in_file" in Dist::Zilla::Role::TextTemplater.

indent

    $file->indent();
    $file->indent( $size );

Indents file content by inserting specified number of spaces to the beginning of every non-empty line. By default, file is indented with 4 spaces. The method returns $self for chaining.

Primary purpose of the method is including a file into POD as verbatim paragraph(s):

    =head2 example.pl

    {{ include( 'ex/example.pl' )->indent; }}

    =cut

munge

    $file->munge( \&func );
    $file->munge( sub { …modify $_ here… } );

Calls the specified function. File content is passed to the function in $_ variable. Return value of the function is ignored. Value of $_ variable becomes new file content. The method returns $self for chaining.

pod2text

    $file->pod2text( %options );

Converts POD to plain text. It is a simple wrapper over Pod::Text. See documentation on Pod::Text::new for description of available options. The method returns $self for chaining.

Example:

    {{ include( 'readme.pod' )->pod2text( width => 80, quotes => 'none', loose => 1 ); }}

See "DESCRIPTION" in Pod::Text.

trim

    $file->trim();

Trims trailing whitespaces from every line. The method returns $self for chaining.

SEE ALSO

Dist::Zilla

Dist::Zilla::Role::FileFinderUser

Dist::Zilla::Role::TextTemplater

Text::Template

Pod::Text

Dist::Zilla::Plugin::Templates::Manual

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2015, 2016, 2018 Van de Bugger

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.

cpanm Dist::Zilla::Plugin::Templates

perl -MCPAN -e shell
install Dist::Zilla::Plugin::Templates