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.

cpanm HTTP::Server::Simple::Dispatched

perl -MCPAN -e shell
install HTTP::Server::Simple::Dispatched