From: John Napiorkowski Date: Mon, 6 Dec 2010 21:22:46 +0000 (-0500) Subject: documentation corrections and updates X-Git-Tag: v0.005~12 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FWeb-Simple.git;a=commitdiff_plain;h=6a4808bf0d52746eec29e8335002600600ea07c4 documentation corrections and updates --- diff --git a/lib/Web/Simple.pm b/lib/Web/Simple.pm index 9d4135c..0e4797c 100644 --- a/lib/Web/Simple.pm +++ b/lib/Web/Simple.pm @@ -74,12 +74,12 @@ If you save this file into your cgi-bin as C and then visit: http://my.server.name/cgi-bin/hello-world.cgi/ you'll get the "Hello world!" string output to your browser. For more complex -examples and non-CGI deployment, see below. To get help with Web::Simple, +examples and non-CGI deployment, see below. To get help with L, please connect to the irc.perl.org IRC network and join #web-simple. =head1 DESCRIPTION -The philosophy of L is to keep to an absolute bare minimum, for +The philosophy of L is to keep to an absolute bare minimum for everything. It is not designed to be used for large scale applications; the L web framework already works very nicely for that and is a far more mature, well supported piece of software. @@ -88,17 +88,17 @@ However, if you have an application that only does a couple of things, and want to not have to think about complexities of deployment, then L might be just the thing for you. -The only public interface the Web::Simple module itself provides is an -import based one: +The only public interface the L module itself provides is an +C based one: use Web::Simple 'NameOfApplication'; -This setups up your package (in this case "NameOfApplication" is your package) +This sets up your package (in this case "NameOfApplication" is your package) so that it inherits from L and imports L, as well as installs a C constant for convenience, as well as some other subroutines. -Importing L will automatically make you code use the C and +Importing L will automatically make your code use the C and C pragma, so you can skip the usual: use strict; @@ -118,6 +118,10 @@ the the equivalent of: extends 'Web::Simple::Application'; } +So you can use L features in your application, such as creating attributes +using the C subroutine, etc. Please see the documentation for L for +more information. + It also exports the following subroutines for use in dispatchers: response_filter { ... }; @@ -136,7 +140,7 @@ is encountered in other code. =head1 DISPATCH STRATEGY -L dispite being straightforward to use, has a powerful system +L despite being straightforward to use, has a powerful system for matching all sorts of incoming URLs to one or more subroutines. These subroutines can be simple actions to take for a given URL, or something more complicated, including entire L applications, L @@ -328,10 +332,9 @@ Finally, sub (/foo/...) { -will match /foo/ on the beginning of the path -and- strip it, much like -.html strips the extension. This is designed to be used to construct -nested dispatch structures, but can also prove useful for having e.g. an -optional language specification at the start of a path. +Will match /foo/ on the beginning of the path -and- strip it. This is designed +to be used to construct nested dispatch structures, but can also prove useful +for having e.g. an optional language specification at the start of a path. Note that the '...' is a "maybe something here, maybe not" so the above specification will match like this: @@ -344,8 +347,8 @@ specification will match like this: sub (.html) { -will match and strip .html from the path (assuming the subroutine itself -returns something, of course). This is normally used for rendering - e.g. +will match .html from the path (assuming the subroutine itself returns +something, of course). This is normally used for rendering - e.g. sub (.html) { response_filter { $self->render_html($_[1]) } @@ -355,8 +358,7 @@ Additionally, sub (.*) { -will match any extension and supplies the stripped extension as a match -argument. +will match any extension and supplies the extension as a match argument. =head3 Query and body parameter matches @@ -652,7 +654,7 @@ None required yet. Maybe this module is perfect (hahahahaha ...). =head1 COPYRIGHT -Copyright (c) 2009 the Web::Simple L and L +Copyright (c) 2010 the Web::Simple L and L as listed above. =head1 LICENSE diff --git a/lib/Web/Simple/Application.pm b/lib/Web/Simple/Application.pm index 05873c5..99e6436 100644 --- a/lib/Web/Simple/Application.pm +++ b/lib/Web/Simple/Application.pm @@ -99,7 +99,7 @@ sub _cli_usage { =head1 NAME -Web::Simple::Application - A base class for your Web-Simple applications +Web::Simple::Application - A base class for your Web-Simple application =head1 DESCRIPTION @@ -109,11 +109,12 @@ lifting' for you in that regards. =head1 METHODS -This class exposes the follow public methods. +This class exposes the following public methods. =head2 default_config -Provide configuration information to your application, for example: +Merges with the C initializer to provide configuration information for +your application. For example: sub default_config { ( @@ -122,12 +123,18 @@ Provide configuration information to your application, for example: ); } -Now, C<$self> will have an attribute C which will be set to a HashRef +Now, the C attribute of C<$self> will be set to a HashRef containing keys 'title' and 'posts_dir'. +If you construct your application like: + + MyWebSimpleApp::Web->new(config=>{environment=>'dev'}) + +then C will have a C key with a value of 'dev'. + =head2 run_if_script -In the case where you wish to run you L based application as a +In the case where you wish to run your L based application as a stand alone CGI application, you can simple do: ## my_web_simple_app.pl @@ -155,6 +162,18 @@ Or (even more simply) just inline the entire application: HelloWorld->run_if_script; +Additionally, you can treat the above script as though it were a standard PSGI +application file (*.psgi). For example you can start up up with C + + plackup my_web_simple_app.pl + +Which means you can write a L application as a plain old CGI +application and seemlessly migrate to a L based solution when you are +ready for that. + +Lastly, L will automatically detect and support a Fast CGI +environment. + =head2 to_psgi_app Given a L application root namespace, return it in a form suitable @@ -182,6 +201,26 @@ L application; your app.psgi could be as simple as: use MyWebSimpleApp::Web; MyWebSimpleApp::Web->to_psgi_app; +This means if you want to provide a 'default' set of middleware, one option is +to modify this method: + + use Web::Simple 'HelloWorld'; + use Plack::Builder; + + { + package HelloWorld; + + + around 'to_psgi_app', sub { + my ($orig, $self) = (shift, shift); + my $app = $self->$orig(@_); + builder { + enable ...; ## whatever middleware you want + $app; + }; + }; + } + As always, mix and match the pieces you actually need and remember the L philosophy of trying to keep it as minimal and simple as possible. @@ -204,7 +243,7 @@ None required yet. Maybe this module is perfect (hahahahaha ...). =head1 COPYRIGHT -Copyright (c) 2009 the Web::Simple L and L +Copyright (c) 2010 the Web::Simple L and L as listed above. =head1 LICENSE diff --git a/t/sub-dispatch-args.t b/t/sub-dispatch-args.t index c7b5830..8762459 100644 --- a/t/sub-dispatch-args.t +++ b/t/sub-dispatch-args.t @@ -12,6 +12,8 @@ use Test::More ( use Web::Simple 't::Web::Simple::SubDispatchArgs'; package t::Web::Simple::SubDispatchArgs; + has 'attr' => (is=>'ro'); + sub dispatch_request { my $self = shift; sub (/) {