The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Apache::Scriptor - Support for Apache handlers conveyor.


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


  • 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.


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

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

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

  ### File /_Kernel/
    #!/usr/local/bin/perl -w 
    use FindBin qw($Bin);          # òåêóùàÿ äèðåêòîðèÿ
    my $HandDir="$Bin/handlers";   # äèðåêòîðèÿ ñ îáðàáîò÷èêàìè
    # This is run not as CGI-script?
      print "This script has to be used only as Apache handler!\n\n";
    # Non-Apache-handler run?
    if(!$ENV{REDIRECT_URL}) {
      print "Location: http"."://$ENV{SERVER_NAME}/\n\n";
    require Apache::Scriptor;
    my $Scr=Apache::Scriptor->new();
    # Setting up the handlers' directory.
    # Go on!

  ### File /_Kernel/handlers/
    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 Koterov (koterov at cpan dot org) -->\n'.$input;
       return 0; # OK

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

  ### Then, user enters the URL:
  ### The result will be:
    Content-type: text/html\n\n
    <!-- Copyright (C) by Dmitry Koterov (koterov at cpan dot org) -->\n
    Hello, world!


This module is used to handle all the requests through the Perl script (such as /_Kernel/, 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/"
  AddHandler s_copyright .htm

Apache sees that, to process .htm document, /_Kernel/ 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/, 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).


require Apache::Scriptor

Loads the module core.


Creates the new Apache::Scriptor object. Then you may set up its properties and run methods (see below).


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.


Removes all the handlers for extension $ext.


Sets up the redirect address for 404 error. By default, this value is bringing up from .htaccess files.


Tells Apache::Scriptor object then Apache user configuration file is called $name (by default $name=".htaccess").


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.


Dmitry Koterov <koterov at cpan dot org>,



1 POD Error

The following errors were encountered while parsing the POD:

Around line 336:

Non-ASCII character seen before =encoding in 'òåêóùàÿ'. Assuming CP1252