.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Dispatch::PSGI 3pm"
.TH CGI::Application::Dispatch::PSGI 3pm "2012-11-04" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Application::Dispatch::PSGI \- Dispatch requests to
CGI::Application based objects using PSGI
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Out of Box"
.IX Subsection "Out of Box"
Under mod_perl:
.PP
.Vb 1
\& # change "Apache1" to "Apache2" as needed.
\&
\&
\& SetHandler perl\-script
\& PerlHandler Plack::Handler::Apache1
\& PerlSetVar psgi_app /path/to/app.psgi
\&
\&
\&
\& use Plack::Handler::Apache1;
\& Plack::Handler::Apache1\->preload("/path/to/app.psgi");
\&
.Ve
.PP
Under \s-1CGI:\s0
.PP
This would be the instance script for your application, such
as /cgi\-bin/dispatch.cgi:
.PP
.Vb 6
\& ### in your dispatch.psgi:
\& # ( in a persistent environment, use FindBin::Real instead. )
\& use FindBin \*(AqBin\*(Aq;
\& use lib "$Bin/../perllib\*(Aq;
\& use Your::Application::Dispatch;
\& Your::Application::Dispatch\->as_psgi;
\&
\& ### In Your::Application::Dispatch;
\& package Your::Application::Dispatch;
\& use base \*(AqCGI::Application::Dispatch::PSGI\*(Aq;
.Ve
.SS "With a dispatch table"
.IX Subsection "With a dispatch table"
.Vb 2
\& package MyApp::Dispatch;
\& use base \*(AqCGI::Application::Dispatch::PSGI\*(Aq;
\&
\& sub dispatch_args {
\& return {
\& prefix => \*(AqMyApp\*(Aq,
\& table => [
\& \*(Aq\*(Aq => { app => \*(AqWelcome\*(Aq, rm => \*(Aqstart\*(Aq },
\& \*(Aq:app/:rm\*(Aq => { },
\& \*(Aqadmin/:app/:rm\*(Aq => { prefix => \*(AqMyApp::Admin\*(Aq },
\& ],
\& };
\& }
.Ve
.PP
The \f(CW\*(C`.psgi\*(C'\fR file is constructed as above.
.SS "With a custom query object"
.IX Subsection "With a custom query object"
If you want to supply your own \s-1PSGI\s0 object, something like this in
your .psgi file will work:
.PP
.Vb 12
\& sub {
\& my $env = shift;
\& my $app = CGI::Application::Dispatch::PSGI\->as_psgi(
\& table => [
\& \*(Aq/:rm\*(Aq => { app => \*(AqTestApp\*(Aq }
\& ],
\& args_to_new => {
\& QUERY => CGI::PSGI\->new($env)
\& }
\& );
\& return $app\->($env);
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a way to look at the path (as returned by \f(CW\*(C`$env\->{PATH_INFO}\*(C'\fR) of the incoming request, parse off the desired
module and its run mode, create an instance of that module and run it.
.PP
It will translate a \s-1URI\s0 like this (in a persistent environment)
.PP
.Vb 1
\& /app/module_name/run_mode
.Ve
.PP
or this (vanilla \s-1CGI\s0)
.PP
.Vb 1
\& /app/index.cgi/module_name/run_mode
.Ve
.PP
into something that will be functionally similar to this
.PP
.Vb 2
\& my $app = Module::Name\->new(..);
\& $app\->mode_param(sub {\*(Aqrun_mode\*(Aq}); #this will set the run mode
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "as_psgi(%args)"
.IX Subsection "as_psgi(%args)"
This is the primary method used during dispatch.
.PP
.Vb 3
\& #!/usr/bin/perl
\& use strict;
\& use CGI::Application::Dispatch::PSGI;
\&
\& CGI::Application::Dispatch::PSGI\->as_psgi(
\& prefix => \*(AqMyApp\*(Aq,
\& default => \*(Aqmodule_name\*(Aq,
\& );
.Ve
.PP
This method accepts the following name value pairs:
.IP "default" 4
.IX Item "default"
Specify a value to use for the path if one is not available.
This could be the case if the default page is selected (eg: \*(L"/\*(R" ).
.IP "prefix" 4
.IX Item "prefix"
This option will set the string that will be prepended to the name of
the application module before it is loaded and created. So to use our
previous example request of
.Sp
.Vb 1
\& /app/index.cgi/module_name/run_mode
.Ve
.Sp
This would by default load and create a module named
\&'Module::Name'. But let's say that you have all of your application
specific modules under the 'My' namespace. If you set this option to
\&'My' then it would instead load the 'My::Module::Name' application
module instead.
.IP "args_to_new" 4
.IX Item "args_to_new"
This is a hash of arguments that are passed into the \f(CW\*(C`new()\*(C'\fR
constructor of the application.
.IP "table" 4
.IX Item "table"
In most cases, simply using Dispatch with the \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`prefix\*(C'\fR
is enough to simplify your application and your URLs, but there are
many cases where you want more power. Enter the dispatch table. Since
this table can be slightly complicated, a whole section exists on its
use. Please see the \*(L"\s-1DISPATCH\s0 \s-1TABLE\s0\*(R" section.
.IP "debug" 4
.IX Item "debug"
Set to a true value to send debugging output for this module to
\&\s-1STDERR\s0. Off by default.
.IP "auto_rest" 4
.IX Item "auto_rest"
This tells Dispatch that you are using \s-1REST\s0 by default and that you
care about which \s-1HTTP\s0 method is being used. Dispatch will append the
\&\s-1HTTP\s0 method name (upper case by default) to the run mode that is
determined after finding the appropriate dispatch rule. So a \s-1GET\s0
request that translates into \f(CW\*(C`MyApp::Module\->foo\*(C'\fR will become
\&\f(CW\*(C`MyApp::Module\->foo_GET\*(C'\fR.
.Sp
This can be overridden on a per-rule basis in a custom dispatch table.
.IP "auto_rest_lc" 4
.IX Item "auto_rest_lc"
In combinaion with auto_rest this tells Dispatch that you prefer
lower cased \s-1HTTP\s0 method names. So instead of \f(CW\*(C`foo_POST\*(C'\fR and
\&\f(CW\*(C`foo_GET\*(C'\fR you'll have \f(CW\*(C`foo_post\*(C'\fR and \f(CW\*(C`foo_get\*(C'\fR.
.SS "\fIdispatch_args()\fP"
.IX Subsection "dispatch_args()"
Returns a hashref of args that will be passed to dispatch(). It
will return the following structure by default.
.PP
.Vb 8
\& {
\& prefix => \*(Aq\*(Aq,
\& args_to_new => {},
\& table => [
\& \*(Aq:app\*(Aq => {},
\& \*(Aq:app/:rm\*(Aq => {},
\& ],
\& }
.Ve
.PP
This is the perfect place to override when creating a subclass to
provide a richer dispatch table.
.PP
When called, it receives 1 argument, which is a reference to the hash
of args passed into dispatch.
.SS "translate_module_name($input)"
.IX Subsection "translate_module_name($input)"
This method is used to control how the module name is translated from
the matching section of the path (see \*(L"Path Parsing\*(R". The main
reason that this method exists is so that it can be overridden if it
doesn't do exactly what you want.
.PP
The following transformations are performed on the input:
.IP "The text is split on '_'s (underscores) and each word has its first letter capitalized. The words are then joined back together and each instance of an underscore is replaced by '::'." 4
.IX Item "The text is split on '_'s (underscores) and each word has its first letter capitalized. The words are then joined back together and each instance of an underscore is replaced by '::'."
.PD 0
.IP "The text is split on '\-'s (hyphens) and each word has its first letter capitalized. The words are then joined back together and each instance of a hyphen removed." 4
.IX Item "The text is split on '-'s (hyphens) and each word has its first letter capitalized. The words are then joined back together and each instance of a hyphen removed."
.PD
.PP
Here are some examples to make it even clearer:
.PP
.Vb 3
\& module_name => Module::Name
\& module\-name => ModuleName
\& admin_top\-scores => Admin::TopScores
.Ve
.SS "require_module($module_name)"
.IX Subsection "require_module($module_name)"
This class method is used internally to take a module name (supplied
by get_module_name) and require it in a secure fashion. It is
provided as a public class method so that if you override other
functionality of this module, you can still safely require user
specified modules. If there are any problems requiring the named
module, then we will \f(CW\*(C`croak\*(C'\fR.
.PP
.Vb 1
\& CGI::Application::Dispatch::PSGI\->require_module(\*(AqMyApp::Module::Name\*(Aq);
.Ve
.SH "DISPATCH TABLE"
.IX Header "DISPATCH TABLE"
Sometimes it's easiest to explain with an example, so here you go:
.PP
.Vb 10
\& CGI::Application::Dispatch::PSGI\->as_psgi(
\& prefix => \*(AqMyApp\*(Aq,
\& args_to_new => {
\& TMPL_PATH => \*(Aqmyapp/templates\*(Aq
\& },
\& table => [
\& \*(Aq\*(Aq => { app => \*(AqBlog\*(Aq, rm => \*(Aqrecent\*(Aq},
\& \*(Aqposts/:category\*(Aq => { app => \*(AqBlog\*(Aq, rm => \*(Aqposts\*(Aq },
\& \*(Aq:app/:rm/:id\*(Aq => { app => \*(AqBlog\*(Aq },
\& \*(Aqdate/:year/:month?/:day?\*(Aq => {
\& app => \*(AqBlog\*(Aq,
\& rm => \*(Aqby_date\*(Aq,
\& args_to_new => { TMPL_PATH => "events/" },
\& },
\& ]
\& );
.Ve
.PP
So first, this call to as_psgi sets the prefix and passes a \f(CW\*(C`TMPL_PATH\*(C'\fR
into args_to_new. Next it sets the table.
.SS "\s-1VOCABULARY\s0"
.IX Subsection "VOCABULARY"
Just so we all understand what we're talking about....
.PP
A table is an array where the elements are gouped as pairs (similar to
a hash's key-value pairs, but as an array to preserve order). The
first element of each pair is called a \f(CW\*(C`rule\*(C'\fR. The second element in
the pair is called the rule's \f(CW\*(C`arg list\*(C'\fR. Inside a rule there are
slashes \f(CW\*(C`/\*(C'\fR. Anything set of characters between slashes is called a
\&\f(CW\*(C`token\*(C'\fR.
.SS "\s-1URL\s0 \s-1MATCHING\s0"
.IX Subsection "URL MATCHING"
When a \s-1URL\s0 comes in, Dispatch tries to match it against each rule in
the table in the order in which the rules are given. The first one to
match wins.
.PP
A rule consists of slashes and tokens. A token can one of the following types:
.IP "literal" 4
.IX Item "literal"
Any token which does not start with a colon (\f(CW\*(C`:\*(C'\fR) is taken to be a literal
string and must appear exactly as-is in the \s-1URL\s0 in order to match. In the rule
.Sp
.Vb 1
\& \*(Aqposts/:category\*(Aq
.Ve
.Sp
\&\f(CW\*(C`posts\*(C'\fR is a literal token.
.IP "variable" 4
.IX Item "variable"
Any token which begins with a colon (\f(CW\*(C`:\*(C'\fR) is a variable token. These
are simply wild-card place holders in the rule that will match
anything in the \s-1URL\s0 that isn't a slash. These variables can later be
referred to by using the \f(CW\*(C`$self\->param\*(C'\fR mechanism. In the rule
.Sp
.Vb 1
\& \*(Aqposts/:category\*(Aq
.Ve
.Sp
\&\f(CW\*(C`:category\*(C'\fR is a variable token. If the \s-1URL\s0 matched this rule, then
you could the value of that token from whithin your application like
so:
.Sp
.Vb 1
\& my $category = $self\->param(\*(Aqcategory\*(Aq);
.Ve
.Sp
There are some variable tokens which are special. These can be used to
further customize the dispatching.
.RS 4
.IP ":app" 4
.IX Item ":app"
This is the module name of the application. The value of this token
will be sent to the translate_module_name method and then prefixed
with the prefix if there is one.
.IP ":rm" 4
.IX Item ":rm"
This is the run mode of the application. The value of this token will be the
actual name of the run mode used. The run mode can be optional, as
noted below. Example:
.Sp
.Vb 1
\& /foo/:rm?
.Ve
.Sp
If no run mode is found, it will default to using the \f(CW\*(C`start_mode()\*(C'\fR, just like
invoking CGI::Application directly. Both of these URLs would end up dispatching
to the start mode associated with /foo:
.Sp
.Vb 2
\& /foo/
\& /foo
.Ve
.RE
.RS 4
.RE
.IP "optional-variable" 4
.IX Item "optional-variable"
Any token which begins with a colon (\f(CW\*(C`:\*(C'\fR) and ends with a question
mark (>) is considered optional. If the rest of the \s-1URL\s0 matches the
rest of the rule, then it doesn't matter whether it contains this
token or not. It's best to only include optional-variable tokens at
the end of your rule. In the rule
.Sp
.Vb 1
\& \*(Aqdate/:year/:month?/:day?\*(Aq
.Ve
.Sp
\&\f(CW\*(C`:month?\*(C'\fR and \f(CW\*(C`:day?\*(C'\fR are optional-variable tokens.
.Sp
Just like with variable tokens, optional-variable tokens' values
can also be retrieved by the application, if they existed in the \s-1URL\s0.
.Sp
.Vb 3
\& if( defined $self\->param(\*(Aqmonth\*(Aq) ) {
\& ...
\& }
.Ve
.IP "wildcard" 4
.IX Item "wildcard"
The wildcard token \*(L"*\*(R" allows for partial matches. The token \s-1MUST\s0
appear at the end of the rule.
.Sp
.Vb 1
\& \*(Aqposts/list/*\*(Aq
.Ve
.Sp
By default, the \f(CW\*(C`dispatch_url_remainder\*(C'\fR param is set to the
remainder of the \s-1URL\s0 matched by the *. The name of the param can be
changed by setting \*(L"*\*(R" argument in the \*(L"\s-1ARG\s0 \s-1LIST\s0\*(R".
.Sp
.Vb 1
\& \*(Aqposts/list/*\*(Aq => { \*(Aq*\*(Aq => \*(Aqpost_list_filter\*(Aq }
.Ve
.IP "method" 4
.IX Item "method"
You can also dispatch based on \s-1HTTP\s0 method. This is similar to using
auto_rest but offers more fine grained control. You include the
method (case insensitive) at the end of the rule and enclose it in
square brackets.
.Sp
.Vb 3
\& \*(Aq:app/news[post]\*(Aq => { rm => \*(Aqadd_news\*(Aq },
\& \*(Aq:app/news[get]\*(Aq => { rm => \*(Aqnews\*(Aq },
\& \*(Aq:app/news[delete]\*(Aq => { rm => \*(Aqdelete_news\*(Aq },
.Ve
.PP
The main reason that we don't use regular expressions for dispatch
rules is that regular expressions provide no mechanism for named back
references, like variable tokens do.
.SS "\s-1ARG\s0 \s-1LIST\s0"
.IX Subsection "ARG LIST"
Each rule can have an accompanying arg-list. This arg list can contain
special arguments that override something set higher up in dispatch
for this particular \s-1URL\s0, or just have additional args passed available
in \f(CW\*(C`$self\->param()\*(C'\fR
.PP
For instance, if you want to override prefix for a specific rule,
then you can do so.
.PP
.Vb 1
\& \*(Aqadmin/:app/:rm\*(Aq => { prefix => \*(AqMyApp::Admin\*(Aq },
.Ve
.SH "Path Parsing"
.IX Header "Path Parsing"
This section will describe how the application module and run mode are
determined from the path if no \*(L"\s-1DISPATCH\s0 \s-1TABLE\s0\*(R" is present, and what
options you have to customize the process. The value for the path to
be parsed is retrieved from \f(CW\*(C`$env\->{PATH_INFO}\*(C'\fR.
.SS "Getting the module name"
.IX Subsection "Getting the module name"
To get the name of the application module the path is split on
backslahes (\f(CW\*(C`/\*(C'\fR). The second element of the returned list (the first
is empty) is used to create the application module. So if we have a
path of
.PP
.Vb 1
\& /module_name/mode1
.Ve
.PP
then the string 'module_name' is used. This is passed through the
translate_module_name method. Then if there is a \f(CW\*(C`prefix\*(C'\fR (and
there should always be a prefix) it is added to the beginning of
this new module name with a double colon \f(CW\*(C`::\*(C'\fR separating the two.
.PP
If you don't like the exact way that this is done, don't fret you do
have a couple of options. First, you can specify a \*(L"\s-1DISPATCH\s0 \s-1TABLE\s0\*(R"
which is much more powerful and flexible (in fact this default
behavior is actually implemented internally with a dispatch table).
Or if you want something a little simpler, you can simply subclass and
extend the translate_module_name method.
.SS "Getting the run mode"
.IX Subsection "Getting the run mode"
Just like the module name is retrieved from splitting the path on
slashes, so is the run mode. Only instead of using the second element
of the resulting list, we use the third as the run mode. So, using the
same example, if we have a path of
.PP
.Vb 1
\& /module_name/mode2
.Ve
.PP
Then the string 'mode2' is used as the run mode.
.SH "Exception Handling"
.IX Header "Exception Handling"
A CGI::Application object can throw an exception up to \f(CW\*(C`CGI::Application::Dispatch::PSGI\*(C'\fR if no \f(CW\*(C`error_mode()\*(C'\fR is implemented or if
the error_mode itself throws an exception. In these cases we generally return a
generic \*(L"500\*(R" response, and log some details for the developer with a warning.
.PP
However, we will check to see if the exception thrown is an HTTP::Exception
object. If that's the case, we will rethrow it, and you can handle it yourself using
something like Plack::Middleware::HTTPExceptions.
.SH "MISC NOTES"
.IX Header "MISC NOTES"
.IP "\(bu" 8
\&\s-1CGI\s0 query strings
.Sp
\&\s-1CGI\s0 query strings are unaffected by the use of \f(CW\*(C`PATH_INFO\*(C'\fR to obtain
the module name and run mode. This means that any other modules you
use to get access to you query argument (ie, \s-1CGI\s0,
Apache::Request) should not be affected. But, since the run mode
may be determined by CGI::Application::Dispatch::PSGI having a query
argument named 'rm' will be ignored by your application module.
.SH "CLEAN URLS WITH MOD_REWRITE"
.IX Header "CLEAN URLS WITH MOD_REWRITE"
With a dispatch script, you can fairly clean \s-1URLS\s0 like this:
.PP
.Vb 1
\& /cgi\-bin/dispatch.cgi/module_name/run_mode
.Ve
.PP
However, including \*(L"/cgi\-bin/dispatch.cgi\*(R" in ever \s-1URL\s0 doesn't add any
value to the \s-1URL\s0, so it's nice to remove it. This is easily done if
you are using the Apache web server with \f(CW\*(C`mod_rewrite\*(C'\fR
available. Adding the following to a \f(CW\*(C`.htaccess\*(C'\fR file would allow you
to simply use:
.PP
.Vb 1
\& /module_name/run_mode
.Ve
.PP
If you have problems with mod_rewrite, turn on debugging to see
exactly what's happening:
.PP
.Vb 2
\& RewriteLog /home/project/logs/alpha\-rewrite.log
\& RewriteLogLevel 9
.Ve
.SS "mod_rewrite related code in the dispatch script."
.IX Subsection "mod_rewrite related code in the dispatch script."
This seemed necessary to put in the dispatch script to make mod_rewrite happy.
Perhaps it's specific to using \f(CW\*(C`RewriteBase\*(C'\fR.
.PP
.Vb 3
\& # mod_rewrite alters the PATH_INFO by turning it into a file system path,
\& # so we repair it.
\& $ENV{PATH_INFO} =~ s/^$ENV{DOCUMENT_ROOT}// if defined $ENV{PATH_INFO};
.Ve
.SS "Simple Apache Example"
.IX Subsection "Simple Apache Example"
.Vb 1
\& RewriteEngine On
\&
\& # You may want to change the base if you are using the dispatcher within a
\& # specific directory.
\& RewriteBase /
\&
\& # If an actual file or directory is requested, serve directly
\& RewriteCond %{REQUEST_FILENAME} !\-f
\& RewriteCond %{REQUEST_FILENAME} !\-d
\&
\& # Otherwise, pass everything through to the dispatcher
\& RewriteRule ^(.*)$ /cgi\-bin/dispatch.cgi/$1 [L,QSA]
.Ve
.ie n .SS "More complex rewrite: dispatching ""/"" and multiple developers"
.el .SS "More complex rewrite: dispatching ``/'' and multiple developers"
.IX Subsection "More complex rewrite: dispatching / and multiple developers"
Here is a more complex example that dispatches \*(L"/\*(R", which would otherwise
be treated as a directory, and also supports multiple developer directories,
so \f(CW\*(C`/~mark\*(C'\fR has its own separate dispatching system beneath it.
.PP
Note that order matters here! The Location block for \*(L"/\*(R" needs to come
before the user blocks.
.PP
.Vb 3
\&
\& RewriteEngine On
\& RewriteBase /
\&
\& # Run "/" through the dispatcher
\& RewriteRule ^home/project/www/$ /cgi\-bin/dispatch.cgi [L,QSA]
\&
\& # Don\*(Aqt apply this rule to the users sub directories.
\& RewriteCond %{REQUEST_URI} !^/~.*$
\& # If an actual file or directory is requested, serve directly
\& RewriteCond %{REQUEST_FILENAME} !\-f
\& RewriteCond %{REQUEST_FILENAME} !\-d
\& # Otherwise, pass everything through to the dispatcher
\& RewriteRule ^(.*)$ /cgi\-bin/dispatch.cgi/$1 [L,QSA]
\&
\&
\&
\& RewriteEngine On
\& RewriteBase /~mark
\&
\& # Run "/" through the dispatcher
\& RewriteRule ^/home/mark/www/$ /~mark/cgi\-bin/dispatch.cgi [L,QSA]
\&
\& # Otherwise, if an actual file or directory is requested, serve directly
\& RewriteCond %{REQUEST_FILENAME} !\-f
\& RewriteCond %{REQUEST_FILENAME} !\-d
\&
\& # Otherwise, pass everything through to the dispatcher
\& RewriteRule ^(.*)$ /~mark/cgi\-bin/dispatch.cgi/$1 [L,QSA]
\&
\& # These examples may also be helpful, but are unrelated to dispatching.
\& SetEnv DEVMODE mark
\& SetEnv PERL5LIB /home/mark/perllib:/home/mark/config
\& ErrorDocument 404 /~mark/errdocs/404.html
\& ErrorDocument 500 /~mark/errdocs/500.html
\&
.Ve
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
While Dispatch tries to be flexible, it won't be able to do everything
that people want. Hopefully we've made it flexible enough so that if
it doesn't do \fIThe Right Thing\fR you can easily subclass it.
.SH "AUTHORS"
.IX Header "AUTHORS"
Mark Stosberg
.PP
Heavily based on CGI::Application::Dispatch, written by Michael Peters
and others
.SH "COMMUNITY"
.IX Header "COMMUNITY"
This module is a part of the larger CGI::Application community. If
you have questions or comments about this module then please join us
on the cgiapp mailing list by sending a blank message to
\&\*(L"cgiapp\-subscribe@lists.erlbaum.net\*(R". There is also a community wiki
located at http://www.cgi\-app.org/
.SH "SOURCE CODE REPOSITORY"
.IX Header "SOURCE CODE REPOSITORY"
A public source code repository for this project is hosted here:
.PP
https://github.com/markstos/CGI\*(--Application\-\-Dispatch
.SH "SECURITY"
.IX Header "SECURITY"
Since C::A::Dispatch::PSGI will dynamically choose which modules to use as the
content generators, it may give someone the ability to execute random modules
on your system if those modules can be found in you path. Of course those
modules would have to behave like CGI::Application based modules, but that
still opens up the door more than most want. This should only be a problem if
you don't use a prefix. By using this option you are only allowing Dispatch
to pick from a namespace of modules to run.
.SH "Backwards Compatibility"
.IX Header "Backwards Compatibility"
Versions 0.2 and earlier of this module injected the \*(L"as_psgi\*(R" method into
CGI::Application::Dispatch, creating a syntax like this:
.PP
.Vb 4
\& ### in your dispatch.psgi:
\& use Your::Application::Dispatch;
\& use CGI::Application::Dispatch::PSGI;
\& Your::Application::Dispatch\->as_psgi;
\&
\& ### In Your::Application::Dispatch;
\& use base \*(AqCGI::Application::Dispatch::PSGI\*(Aq;
.Ve
.PP
In the current design, the \f(CW\*(C`as_pgsi\*(C'\fR method is directly in this module, so
a couple of lines of code need to be changed:
.PP
.Vb 3
\& ### in your dispatch.psgi:
\& use Your::Application::Dispatch;
\& Your::Application::Dispatch\->as_psgi;
\&
\& ### In Your::Application::Dispatch;
\& use base \*(AqCGI::Application::Dispatch::PSGI\*(Aq;
.Ve
.SH "Differences with CGI::Application::Dispatch"
.IX Header "Differences with CGI::Application::Dispatch"
.IP "\fIdispatch()\fR" 4
.IX Item "dispatch()"
Use \f(CW\*(C`as_psgi()\*(C'\fR instead.
.Sp
Note that the \f(CW\*(C`error_document\*(C'\fR key is not supported here. Use the
Plack::Middleware::ErrorDocument or another \s-1PSGI\s0 solution instead.
.IP "\fIdispatch_path()\fR" 4
.IX Item "dispatch_path()"
The \fIdispatch_path()\fR method is not supported. The alternative is to
reference \f(CW\*(C`$env\->{PATH_INFO}\*(C'\fR which is available per the \s-1PSGI\s0
spec.
.IP "\fIhandler()\fR" 4
.IX Item "handler()"
This provided an Apache-specific handler. Other \s-1PSGI\s0 components like
Plack::Handler::Apache2 provide Apache handlers now instead.
.IP "\fI_http_method()\fR" 4
.IX Item "_http_method()"
This method has been eliminated. Check \f(CW\*(C`$env\->{REQUEST_METHOD}\*(C'\fR
directly instead.
.IP "\fI_parse_path()\fR" 4
.IX Item "_parse_path()"
The private \fI_parse_path()\fR method now accepts an additional argument,
the \s-1PSGI\s0 \f(CW$env\fR hash.
.IP "\fI_run_app()\fR" 4
.IX Item "_run_app()"
The private \fI_run_app()\fR method now accepts an additional argument, the
\&\s-1PSGI\s0 \f(CW$env\fR hash.
.IP "\fI_r()\fR" 4
.IX Item "_r()"
This method has been eliminated. It does not apply in \s-1PSGI\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::Application, Apache::Dispatch
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright Michael Peters and Mark Stosberg 2008\-2010, all rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.