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.