NAME

Apache::Scriptor - Support for Apache handlers conveyor.

SYNOPSIS

Synopsis are not so easy as in other modules, that's why let's see example below.

FEATURES

Uses ONLY perl binary.
Helps to organize the Apache handler conveyor. That means you can redirect the output from one handler to another handler.
Supports non-existance URL handling and 404 Error processing.
Uses .htaccess files to configure.

EXAMPLE

  ### Consider the server structure:
  ### /
  ###   _Kernel/
  ###      handlers/
  ###        s_copyright.pl
  ###        ...
  ###      .htaccess
  ###      Scriptor.pl
  ###   .htaccess
  ###   test.htm

  ### File /.htaccess:
    # Setting up the conveyor for .htm:
    # "input" => eperl => s_copyright => "output" 
    Action     perl "/_Kernel/Scriptor.pl"
    AddHandler perl .htm
    Action     s_copyright "/_Kernel/Scriptor.pl"
    AddHandler s_copyright .htm

  ### File /_Kernel/.htaccess:
    # Enables Scriptor.pl as perl executable
    Options ExecCGI
    AddHandler cgi-script .pl

  ### File /_Kernel/Scriptor.pl:
    #!/usr/local/bin/perl -w 
    use FindBin qw($Bin);          # текущая директория
    my $HandDir="$Bin/handlers";   # директория с обработчиками
    # This is run not as CGI-script?
    if(!$ENV{DOCUMENT_ROOT} || !$ENV{SCRIPT_NAME} || !$ENV{SERVER_NAME}) {
      print "This script has to be used only as Apache handler!\n\n";
      exit;
    }
    # Non-Apache-handler run?
    if(!$ENV{REDIRECT_URL}) {
      print "Location: http"."://$ENV{SERVER_NAME}/\n\n";
      exit;
    }
    require Apache::Scriptor;
    my $Scr=Apache::Scriptor->new();
    # Setting up the handlers' directory.
    $Scr->set_handlers_dir($HandDir);
    # Go on!
    $Scr->run_uri($ENV{REQUEST_URI},$ENV{PATH_TRANSLATED});

  ### File /_Kernel/handlers/s_copyright.pl:
    sub s_copyright
    {  my ($input)=@_;
       -f $ENV{SCRIPT_FILENAME} or return -1; # Error indicator
       # Adds the comment string BEFORE all the output.
       print '<!-- Copyright (C) by Dmitry Koteroff (koteroff@cpan.org) -->\n'.$input;
       return 0; # OK
    }

  ### File /test.htm:
    print "<html><body>Hello, world!</body></html>";

  ### Then, user enters the URL: http://ourhost.com/test.htm.
  ### The result will be:
    Content-type: text/html\n\n
    <!-- Copyright (C) by Dmitry Koteroff (koteroff@cpan.org) -->\n
    Hello, world!

OVERVIEW

This module is used to handle all the requests through the Perl script (such as /_Kernel/Scriptor.pl, see above). This script is just calling the handlers conveyor for the specified file types.

When you place directives like these in your .htaccess file:

  Action     s_copyright "/_Kernel/Scriptor.pl"
  AddHandler s_copyright .htm

Apache sees that, to process .htm document, /_Kernel/Scriptor.pl handler should be used. Then, Apache::Scriptor starts, reads this .htaccess and remembers the handler name for .htm document: it is s_copyright. Apache::Scriptor searches for /_Kernel/handlers/s_copyright.pl, trying to find the subroutine with the same name: s_copyright(). Then it runs that and passes the document body, returned from the previous handler, as the first parameter.

How to start the new conveyor for extension .html, for example? It's easy: you place some Action-AddHandler pairs into the .htaccess file. You must choose the name for these handlers corresponding to the Scriptor handler file names (placed in /_Kernel/handlers). Apache does NOT care about these names, but Apache::Scriptor does. See example above (it uses two handlers: built-in perl and user-defined s_copyright).

DESCRIPTION

require Apache::Scriptor: Loads the module core.
Apache::Scriptor'new: Creates the new Apache::Scriptor object. Then you may set up its properties and run methods (see below).
$obj'set_handlers_dir($dir): Sets up the directory, which is used to search for handlers.
$obj'run_uri($uri [, $filename]): Runs the specified URI through the handlers conveyer and prints out the result. If $filename parameter is specified, module does not try to convert URL to filename and uses it directly.
$obj'addhandler(ext1=[h1, h2,...], ext2=>[...])>: Manually sets up the handlers' conveyor for document extensions. Values of h1, h2 etc. could be code references or late-loadable function names (as while parsing the .htaccess file).
$obj'pushhandler($ext, $handler): Adds the handler $handler th the end of the conveyor for extension $ext.
$obj'removehandler($ext): Removes all the handlers for extension $ext.
$obj'set_404_url($url): Sets up the redirect address for 404 error. By default, this value is bringing up from .htaccess files.
$obj'set_htaccess_name($name): Tells Apache::Scriptor object then Apache user configuration file is called $name (by default $name=".htaccess").
$obj'process_htaccess($filename): Processes all the directives in the .htaccess file $filename and adds all the found handlers th the object.
package Apache::Scriptor::Handlers: This package holds ALL the handler subroutines. You can place some user-defined handlers into it before loading the module to avoid their late loading from handlers directory.

AUTHOR

Dmitry Koteroff <koteroff@cpan.org>, http://www.dklab.ru