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.
.htaccess
### 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 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: http://ourhost.com/test.htm. ### 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/Scriptor.pl, see above). This script is just calling the handlers conveyor for the specified file types.
/_Kernel/Scriptor.pl
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.
.htm
s_copyright
/_Kernel/handlers/s_copyright.pl
s_copyright()
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).
.html
/_Kernel/handlers
perl
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.
$filename
$obj'addhandler(ext1=
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).
h1
h2
$obj'pushhandler($ext, $handler)
Adds the handler $handler th the end of the conveyor for extension $ext.
$handler
$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").
$name
$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.
Dmitry Koterov <koterov at cpan dot org>, http://www.dklab.ru
CGI::WebOut.
CGI::WebOut
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'òåêóùàÿ'. Assuming CP1252
To install Apache::Scriptor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Apache::Scriptor
CPAN shell
perl -MCPAN -e shell install Apache::Scriptor
For more information on module installation, please visit the detailed CPAN module installation guide.