/ 
Dist-Zilla-Plugin-Templates-v0.6.5
River stage one • 1 direct dependent • 1 total dependent
/ Dist::Zilla::Plugin::Templates::File

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.