NAME

Stenciller - Transforms a flat file format to different output

VERSION

Version 0.1400, released 2016-02-03.

SYNOPSIS

    use Stenciller;
    my $stenciller = Stenciller->new(filepath => 't/corpus/test-1.stencil');
    my $content = $stenciller->transform(plugin_name => 'ToUnparsedText');

DESCRIPTION

Stenciller reads a special fileformat and provides a way to convert the content into different types of output. For example, it can be used to create documentation and tests from the same source file.

File format

    == stencil {} ==

    --input--

    --end input--

    --output--

    --end output--

This is the basic layout. A stencil ends when a new stencil block is discovered (there is no fixed limit to the number of stencils in a file). The (optional) hash is for settings. Each stencil has five parts: before_input, input, between, output and after_output. In addition to this there is a header before the first stencil.

ATTRIBUTES

filepath

File

required

read-only

The textfile to parse.

is_utf8

Bool

optional, default: 1

read-only

Determines how the stencil file is read.

skip_if_input_empty

Bool

optional, default: 1

read-only

If a stencil has no input content, skip entire stencil.

skip_if_output_empty

Bool

optional, default: 1

read-only

If a stencil has no output content, skip entire stencil.

header_lines

ArrayRef [ Str ]

not in constructor

read-only

After parsing, this contains all lines in the header.

stencils

ArrayRef [ Stencil ]

not in constructor

read-only

After parsing, this contains all parsed stencils.

METHODS

transform

    $stenciller->transform(
        plugin_name => 'ToUnparsedText',
        constructor_args => {
            plugin_specific_args => ...,
        },
        tranform_args => {
            transformation_specific_args => ...,
        },
    );

plugin_name is mandatory and should be a class under the Stenciller::Plugin namespace.

constructor_args is optional. This hash reference will be passed on to the plugin constructor. Valid keys depends on the plugin.

transform_args is optional. This hash reference will be passed on to the transform method in the plugin. Valid keys depends on the plugin.

PLUGINS

The actual transforming is done by plugins. There are two plugins bundled in this distribution:

• Stenciller::Plugin::ToUnparsedText

• Stenciller::Plugin::ToHtmlPreBlock

• Pod::Elemental::Transformer::Stenciller

Custom plugins should be in the Stenciller::Plugin namespace and consume the Stenciller::Transformer role.

SOURCE

https://github.com/Csson/p5-Stenciller

HOMEPAGE

https://metacpan.org/release/Stenciller

AUTHOR

Erik Carlsson <info@code301.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 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.

cpanm Stenciller

perl -MCPAN -e shell
install Stenciller