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.