NAME

Contentment::Generator::Plain - Generator for plain files

SYNOPSIS

my $source = <<'END_OF_TEXT';
This is a nice text file.

It contains text. Very exciting.
END_OF_TEXT

my $generator = Contentment::Generator::Plain->new({
    kind => 'text/plain',
    properties => {
        foo => 1,
        bar => 2,
    },
    source => $source,
});

my $foo = $generator->get_property('foo');
my $kind = $generator->generated_kind();

$generator->generate;

DESCRIPTION

A generator for plain text files. Given a scalar, it will output that scalar. This package also provides file type matching features to allow this generator to operate as a fallback generator for the VFS.

$generator = Contentment::Generator::Plain->new(\%args)

This constructs a plain generator. It takes the following arguments:

source (required)

This is the source text to generate from. Since the plain generator doesn't do anything to the given text, it will output whatever it is given during generation.

The source may be specified as a scalar containing the text to generate, a reference to a file handle from which to read the text to generate, or a reference to a subroutine that prints the text to generate to standard output. If given a subroutine, that subroutine will be called at most once and will not be passed any arguments.

properties (optional, defaults to {})

This is the list of properties the generator should return. It defaults to having no properties.

$source = $generator->source

This accessor returns the source as a text string.

$test = $generator->is_sourced

This method returns true of the source has already been processed. It returns false if it has not been. This is mainly useful to authors that want to subclass Contentment::Generator::Plain and need to perform some processing only when sourcing.

$properties = $generate->properties

$properties = $generate->properties(\%properties);

The accessor returns a reference to the properties as a hash. The mutator replaces the stored properties with those stored in the hash.

$value = $generator->get_property($key)

Always returns undef. This is literally short-hand for:

$value = $generator->properties->{$key};

$result = $generator->generate

Uses the $data argument to the constructor to print to standard output.

PLAIN GENERATOR GUTS

If you would like to subclass the plain generator, it exists as a blessed hash where the following keys are used: "source", "properties", and "cache". Do not access these directly, but use of the provided accessors. If you need to store additional data, don't use those keys.

If you need to define some action that is performed when the source is read (compiling templates, code, reading properties, etc.), then you should subclass the source() method like this:

sub source {
    my $self = shift;

    # Skip it if the source has already been processed.
    return $self->SUPER::source if $self->is_sourced;

    # Otherwise process it
    my $source = $self->SUPER::source;

    # do the processing....

    return $source;
}

By following this pattern, your class can be further subclassed to perform even more processing as well.

HOOK HANDLERS

Contentment::Generator::Plain::match

Used to handle the "Contentment::VFS::generator" hook. Always returns a Contentment::Generator::Plain object for the file.

Contentment::Generator::Plain::final_kind

Used to handle the "Contentment::Request::final_kind" hook.

SEE ALSO

Contentment::MIMETypes

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is distributed and licensed under the same terms as Perl itself.