NAME

Pod::Elemental::Transformer::Stenciller - Injects content from textfiles transformed with Stenciller

Requires Perl 5.14+ coverage 88.6% Build status at Github

VERSION

Version 0.0301, released 2021-06-30.

SYNOPSIS

# in weaver.ini
[-Transformer / Stenciller]
transformer = Stenciller
directory = path/to/stencildir

DESCRIPTION

This transformer uses a special command in pod files to inject content from elsewhere via a Stenciller transformer plugin.

Example

1. Start with the weaver.ini from the "synopsis".

2. Add a textfile, in path/to/stencildir/file-with-stencils.stencil:

== stencil { to_pod => 1 } ==

Header text

--input--

    Input text

--end input--

Between text

--output--

    Output text

--end output--

Footer text

3. Add a Perl module:

package A::Test::Module;

1;

__END__

=pod

=head1 NAME

=head1 DESCRIPTION

:stenciller ToUnparsedText file-with-stencils.stencil

The last line in the Perl module will result in the following:

Pod hash

It is possible to filter stencils by index with an optional hash in the pod:

:stenciller ToUnparsedText 1-test.stencil { stencils => [0, 2..4] }

This will only include the stencils with index 0, 2, 3 and 4 from file-with-stencils.stencil.

Stencil hash

This module checks for the to_pod key in the stencil hash. If it has a true value (or doesn't exist) it is included in the transformation.

However, any stencil excluded by the "Pod hash" is already disregarded. It is probably least confusing to choose one of these places to do all filtering.

ATTRIBUTES

directory

Dir required read-only

Path to directory where the stencil files are.

SEE ALSO

SOURCE

https://github.com/Csson/p5-Pod-Elemental-Transformer-Stenciller

HOMEPAGE

https://metacpan.org/release/Pod-Elemental-Transformer-Stenciller

AUTHOR

Erik Carlsson <info@code301.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Erik Carlsson.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.