NAME

Contentment::Generator::PerlScript - A generator for Perl scripts

SYNOPSIS

  my $generator = Contentment::Generator::PerlScript->new({
      properties => {
          title => 'Testing',
          description => 'This is a test.',
      },
      code => sub {
          my $args = shift;
          print "Hello $args{who}!\n";
      },
  });

  my $title = $generator->get_property('title');
  my $description = $generator->get_property('description');

  $generator->generate({ who => "World" });

DESCRIPTION

This will run an external Perl script within the current interpreter (i.e., no forks).

These Perl scripts can expect a certain set of calling conventions. The Perl script is called within the same interpreter as the rest of Contentment. Basically, the script can be treated as if it were the body of a subroutine (which isn't far from the truth). Arguments are stored in @_ and the global variables available in Mason objects are also made available here.

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

This constructs a perl script generator. It takes the following arguments:

source (required, unless "code" is given)

This is the Perl source code to generate from. This argument is required unless "code" is given. This argument accepts the same arguments as the argument of the same name in the constructor for Contentment::Generator::Plain.

If this option is used, rather than "code", the generator will also search the source for metadata properties in the source. For example, if this snipped were part of the source:

  =begin meta
      title => 'Testing'
      description => 'This is a test.'
      kind => 'text/html'
  =end meta

The properties "title", "description", and "kind" would be set to the values given above. Also, the generated kind would be set to the value given by "kind". See Contentment::Generator::POD for additional details.

This option may not be used if "code" is used.

code (required, unless "source" is given)

This is the Perl subroutine to actually execute. This by-passes the "source" option by allowing already compiled Perl code to be used and run. If this option is used, any required properties must be set using the "properties" option and the generated kind must be set using the "kind" option.

This option may not be used if "source" is used.

properties (optional, defaults to {})

This is the list of properties the generator should return. It defaults to having no properties. If the "source" option is used, properties within the source will override any set here.

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

This will cause the source to parsed if source was given. The properties within the file will override any specified in the constructor.

$result = $generator->generate(@args)

If given as source, this method wraps the contents of the source in an eval as part of a subroutine and calls the subroutine. Otherwise, the subroutine passed to the code is executed.

The compiled subroutine or code will be executed every time this method is called.

$source = $self->source

This overrides the method provided by Contentment::Generator::POD. In addition to the work the superclass performs, this method also compiles the source code into Perl. This method will throw an exception if compilation fails.

HOOK HANDLERS

Contentment::Generator::PerlScript::match

Handles the "Contentment::VFS::generator" hook for Contentment::Generator::PerlScript and Contentment::Generator::POD.

SEE ALSO

Contentment::MIMETypes, Contentment::Generator::POD

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

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