Michael Robinton

NAME

Apache::EmbeddedPerl::Lite - light weight embedded perl parser

SYNOPSIS

  PerlModule Apache::EmbeddedPerl::Lite

  <Files *.ebhtml>
    SetHandler perl-script
    PerlHandler Apache::EmbeddedPerl::Lite
    PerlSetVar ContentType text/html
  </Files>

or

  use Apache::EmbeddedPerl::Lite qw(
        embedded
  };

  $response = embedded($class,$r,$filename,@args)

DESCRIPTION

This modules is a light weight perl parser designed to be used in conjunction wit mod_perl and Apache 1 or Apache 2. It may be used as a handler for files containing embedded perl or it may be called as a subroutine to conditionally parse files of your choosing.

Perl code may be embedded in a file parsed by this module as described below. Each section of perl code is collected and eval'd as a subroutine that is passed the two arguments ($classnam,$r) in its input array @_;

Embedded perl should have the following format:

  On a line by itself:

  {optional whitespace}  <!-- {whitespace} perl 

  perl code here

# terminating bracket on a line by itself {optional whitespace} -->

The beginning and terminating brackets may optionally be followed by a white space and comments, which will be ignored.

  i.e.

  <!--  perl
# perl code goes here, it will be executed as a subroutine
#
# anon_sub($classname,$r) {
      my($class,$r) = @_;
      $r->print("Hello World, I am in package $class\n");
# }
  -->
  • $http_response = handler($classname,$r);

    The function "handler" has the prototype:

            handler ($$) : method {

    which receives the arguments $class, $r from Apache mod_perl.

      input:        class name,     (a scalar, not a ref)
                    request handle
    
      return:       Apache response code or undef
    
      handler is not exported.

    Expected Codes:

              0     OK
            404     File Not Found
            500     Server Error
    
      404 could not find, open, etc... file
      500 missing closing embedded perl bracket
          embedded perl has an error

    When a 500 error is returned, a warning will be issued to STDERR providing details about the error.

    A ContentType header will not be sent unless the type is specified as follows:

            PerlSetVar      ContentType     text/html

    mod_perl configuration is as follows:

      PerlModule Apache::EmbeddedPerl::Lite
    
      <Files *.ebhtml>
        SetHandler perl-script
        PerlHandler Apache::EmbeddedPerl::Lite
        PerlSetVar ContentType text/html
      </Files>
  • $http_response = embedded($classname,$r,$file,@args);

    The function "embedded" is similar to "handler" above except that it does not send any headers. Headers are the responsibility of the application "handler", or the embedded code.

    @args are optional arguments that may be passed from your handler to embedded.

      input:        class name,     (a scalar, not a ref)
                    request handle,
                    file name
                    @args   [optional] appication specific
    
      return:       Apache response code or undef
    
      ... at startup or .httaccess ...
    
      use Apache::EmbeddedPerl::Lite qw(embedded);
    
      ... in the application handler ...
    
            if ($r->filename =~ /\.ebhtml$/) {
      ...     set content type, etc...
    
              $response = embedded(__PACKAGE__,$r,$r->filename);
            } else {
              $response = embedded(__PACKAGE__,$r,$someotherfile);
            }
            return $response if $response; # contains error
    
      ...     do something else

PREREQUISITES

        Apache
  or
        Apache2
        Apache2::RequestRec
        Apache2::RequestUtil;
        Apache2::RequestIO;
    

EXPORT_OK

        embedded

AUTHOR

Michael Robinton, michael@bizsystems.com

COPYRIGHT

Copyright 2013-2014, Michael Robinton & BizSystems This program is free software; you can redistribute it and/or modify it under the same terms of the Apache Software License, a copy of which is included in this distribution.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 79:

'=item' outside of any '=over'

Around line 211:

You forgot a '=back' before '=head1'