NAME
HTTP::Server::Simple::Dispatched - Django-like regex dispatching with request and response objects - no CGI.pm cruft!
VERSION
Version 0.06
SYNOPSIS
Quick and dirty regex-based dispatching inspired by Django, with standard response and request objects to ease some of the pain of HTTP::Server::Simple. Lower level than CGI.pm, which allows you to lose some of the cruft of that hoary old monster.
use HTTP::Server::Simple::Dispatched qw(static);
my $server = HTTP::Server::Simple::Dispatched->new(
hostname => 'myawesomeserver.org',
port => 8081,
debug => 1,
dispatch => [
qr{^/hello/} => sub {
my ($response) = @_;
$response->content_type('text/plain');
$response->content("Hello, world!");
return 1;
},
qr{^/say/(\w+)/} => sub {
my ($response) = @_;
$response->content_type('text/plain');
$response->content("You asked me to say $1.");
return 1;
},
qr{^/counter/} => sub {
my ($response, $request, $context) = @_;
my $num = ++$context->{counter};
$response->content_type('text/plain');
$response->content("Called $num times.");
return 1;
},
qr{^/static/(.*\.(?:png|gif|jpg))} => static("t/"),
qr{^/error/} => sub {
die "This will cause a 500!";
},
],
);
$server->run();EXPORTED VARIABLES
$mime
The registry of mime types, this is a MIME::Types and is referenced during the serving of static files. Not exported by default.
EXPORTED FUNCTIONS
static
Use this in dispatch specifiers to install a static-file handler. It takes one argument, a "root" directory. Your regex must capture the path from that root as $1 - e.g. "qr{^/some_path/(.*\.(?:png))} => static("foo/") to serve only .png files from foo/ as "/some_path/some.png". See the the 'static' example in the synopsis. Not exported by default.
ATTRIBUTES
These are Moose attributes: see its documentation for details, or treat them like regular perl read/write object accessors with convenient keyword arguments in the constructor.
dispatch
An arrayref of regex object => coderef pairs. This bit is why you're using this module - you can map urls to handlers and capture pieces of the url. Any captures in the regex are bound to $1..$n just like in a normal regex. See the 'say' example in the synopsis. Note: these are matched in the order you specify them, so beware permissive regexes!
Handlers receive three arguments: An HTTP::Response, an HTTP::Server::Simple::Dispatched::Request, and the context object. The response object defaults to a 200 OK response with text/html as the content type.
Your handler should return a true value if it handles the request - return 0 otherwise (that entry didn't exist in the database, etc.) and a standard 404 will be generated unless another handler picks it up.
Content-Length will be set for you if you do not set it yourself. This is probably what you want. If you do not, manually set Content-Length to whatever you think it should be.
Any errors in your handler will be caught and raise a 500, so you probably do not need to raise this condition yourself. Anything that is not handled by one of your handlers will raise a 404. The rest is up to you!
hostname
Not to be confused with the parent class's "host" accessor, the hostname has nothing to do with which interface to bind the server to. It is used to fill out Request objects with a full URI (in some cases, the locally known hostname for an interface is NOT what the outside world uses to reach it!
context
Every handler will get passed this object, which is global to the server. It can be anything, but defaults to a hashref. Use this as a quick and dirty stash, and then fix it with something real later.
debug
If this is set to true, 500 errors will display some debugging information to the browser. Defaults to false.
append_slashes
If this is set true (which it is by default), requests for /some/method will be redirected to the /some/method/ handler (if such a handler exists). This is highly recommended, as many user agents start to append slashes if the last component of a path does not have an extension, and it makes things look a little nicer.
METHODS
new
This is a proper subclass of HTTP::Server::Simple, but the constructor takes all ATTRIBUTES and standard PERLy accessors from the parent class as keyword arguments for convenience.
AUTHOR
Paul Driver, <frodwith at cpan.org>
BUGS
Please report any bugs or feature requests to bug-http-server-simple-dispatched at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-Server-Simple-Dispatched. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
CONTRIBUTING
The development branch lives at http://helios.tapodi.net/~pdriver/Bazaar/HTTP-Server-Simple-Dispatched. Creating your own branch and sending me the URL is the preferred way to send patches.
ACKNOWLEDGEMENTS
The static serve code was adapted from HTTP::Server::Simple::Static - I would have reused, but it didn't do what I wanted at all.
As mentioned elsewhere, Django's url dispatching is the inspiration for this module.
SEE ALSO
HTTP::Response, HTTP::Server::Simple::Dispatched::Request, MIME::Types, Moose, HTTP::Server::Simple::Dispatched
COPYRIGHT & LICENSE
Copyright 2008 Paul Driver, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.