view release on metacpan or  search on metacpan

lib/Flea.pm  view on Meta::CPAN

C<any> will match any request method, and the others will only match the
corresponding method.  If you need to match some other method or combination
of methods, see L</method>.  Aren't you glad you can rename these? (see
L<Exporter::Declare>).

Next come a regex to match path_info against.  You should surround the regex
with single quotes.  B<LISTEN>:  are you listening?  B<SINGLE QUOTES>.  This
isn't a real perl string, it's parsed with Devel::Declare magic (you'll end up
with a compiled regex).  If you try to use C<qr> or something cute like that,
you'll get B<bitten>.  If you need to do something fancy, use L</route> instead
of these sugary things.

Last of all comes a block.  This receives the PSGI env as its first argument
and any matches from the regex as extra arguments.  It can return either a raw
PSGI response or something with a finalize() method that returns a PSGI
response (like Plack::Response).

=head2 method

Just like get/post/etc, except you can tack on method names (separated by
spaces) to say which methods will match.

    method options '^/regex$' {
    }

    method options head '^/regex$' {
    }

=head2 route($methods, $regex, $sub)

This is an honest to goodness real perl subroutine, unlike the magic bits
above.  You call it like:
    
    route ['get', 'head'], qr{^a/real/regex/please$}, sub {
        ...
    };

Yes, $methods has to be an arrayref.  No, $regex doesn't have to be compiled,
you can pass it a string if you want.  But then, why are you using route?
Yes, you need the semicolon at the end.

=head2 request($env)

Short for Plack::Request->new($env)

=head2 response($request)

Short for $request->new_response(200).

=head2 uri($request, $path)

Returns a canonical L<URI> representing the path you passed with
$request->base welded onto the front.  Does the Right Thing if $request->base
or $path have leading/trailing slashes.  Handy for links which are internal to
your app, because it will still behave if you mount your app somewhere other
than C</>.

=head2 json($str)

Returns a full C<200 OK>, C<content-type application/json; charset=UTF-8>
response.  Pass it something that JSON::encode_json can turn into a string.

=head2 text($str)

text/plain; charset=UTF-8.

=head2 html($str)

text/html; charset=UTF-8.  Seeing a pattern?

=head2 file($filename, $mime_type?)

Dump the contents of the file you named.  If you don't give a mime type,
text/html is assumed.

=head2 handle($fh, $mime_type?)

Much like file, except you pass an open filehandle instead of a filename.

=head2 http($code, @args)

Shortcut for HTTP::Exception->throw.  Accepts the same arguments.

=head2 pass

Throws a Flea::Pass exception, which causes Flea to pretend that your
handler didn't match and keep trying other handlers.  By the way, the default
action when no handler is found (or they all passed) is to throw a 404
exception.

=head1 MATURITY

This module is extremely immature as of this writing.  Not only does the
author have the mind of a child, he has never before tinkered with
Devel::Declare magic, although L<Exporter::Declare> sure does help.  The
author hasn't thought very hard about the interface, either, so that could
change.  When Flea breaks or doesn't do what you want, fork it on L</GITHUB>
and/or send the author a patch or something.  Or go use a real web framework
for grownups, like L<Catalyst>.

=head1 GITHUB

Oh yeah, Flea is hosted on Github at L<http://github.com/frodwith/flea>.

=head1 IRC

You can try hopping into #flea on irc.perl.org.  The author might even be
there.  He might even be paying attention to his irc client!

=head1 SEE ALSO

L<PSGI>, L<Plack>, L<Dancer>, L<Exporter::Declare>