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 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!
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 Koterov <koterov at cpan dot org>, http://www.dklab.ru
SEE ALSO
CGI::WebOut
.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 336:
Non-ASCII character seen before =encoding in 'òåêóùàÿ'. Assuming CP1252