flesh out and publically document the cli API of Web::Simple::Application

Conflicts:
	lib/Web/Simple/Application.pm

Conflicts:
	Changes

diff --git a/Changes b/Changes
index 34bf8f1..89fec86 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,6 @@
 Revision history for Web-Simple
 
+  - flesh out and publically document the cli API of Web::Simple::Application
   - fixes a memory leak that occurs when calling
     Web::Simple::Application::to_psgi_app
 

diff --git a/lib/Web/Simple/Application.pm b/lib/Web/Simple/Application.pm
index 337cd4a..e3040f3 100644 (file)
--- a/lib/Web/Simple/Application.pm
+++ b/lib/Web/Simple/Application.pm
@@ -88,14 +88,15 @@ sub run {
     || ( -S STDIN && !$ENV{GATEWAY_INTERFACE} );
     # If STDIN is a socket, almost certainly FastCGI, except for mod_cgid
   return $self->_run_cgi if $ENV{GATEWAY_INTERFACE};
-  return $self->_run_cli(@ARGV) if !@ARGV || $ARGV[0] !~ m{(^[A-Z/])|\@};
-  return $self->run_cli_request(@ARGV);
+  return $self->run_cli(@ARGV);
 }
 
 sub run_cli_request {
   my ($self, @args) = @_;
+  return if !@args || $args[0] !~ m{(^[A-Z/])|\@};
   unshift @args, 'GET' if $args[0] !~ /^[A-Z]/;
-  return $self->_run_cli_test_request(@args);
+  $self->_run_cli_test_request(@args);
+  return 1;
 }
 
 sub _test_request_spec_to_http_request {
@@ -168,13 +169,14 @@ sub _run_cli_test_request {
   print STDOUT $content if $content;
 }
 
-sub _run_cli {
-  my $self = shift;
-  die $self->_cli_usage;
+sub run_cli {
+  my ($self, @args) = @_;
+  return $self->run_cli_request(@args) || die $self->cli_request_usage;
 }
 
-sub _cli_usage {
-  "To run this script in CGI test mode, pass a URL path beginning with /:\n".
+sub cli_request_usage {
+  "This application does not implement its own run_cli method. To run\n".
+  "this script in CGI test mode, pass a URL path beginning with /:\n".
   "\n".
   "  $0 /some/path\n".
   "  $0 /\n"
@@ -228,7 +230,7 @@ then C<config> will contain:
 
 =head2 run_if_script
 
-The run_if_script method is designed to be used at the end of the script
+The C<run_if_script> method is designed to be used at the end of the script
 or .pm file where your application class is defined - for example:
 
   ## my_web_simple_app.pl
@@ -259,8 +261,22 @@ This returns a true value, so your file is now valid as a module - so
 will work fine (and you can rename it to lib/HelloWorld.pm later to make it
 a real use-able module).
 
-However, it detects if it's being run as a script (via testing $0) and if
-so attempts to do the right thing.
+Specifically, this true value is a PSGI app. You can you can pass the return
+value of C<HelloWorld->run_if_script> to code expecting a PSGI app and you can
+treat the file as though it were a standard PSGI application file (*.psgi). For
+example you can start it up with C<plackup>
+
+  plackup my_web_simple_app.pl
+
+or C<starman>
+
+  starman my_web_simple_app.pl
+
+If C<run_if_script> is called from a situation where there is no caller, i.e. as
+C<perl my_web_simple_app.pl> on the shell, or by a web server, it will call the
+C<run> method to run the actual application itself.
+
+=head2 run
 
 If run under a CGI environment, your application will execute as a CGI.
 
@@ -268,8 +284,27 @@ If run under a FastCGI environment, your application will execute as a
 FastCGI process (this works both for dynamic shared-hosting-style FastCGI
 and for apache FastCgiServer style setups).
 
-If run from the commandline with a URL path, it runs a GET request against
-that path -
+If neither of these are the case, it defaults to running the C<run_cli> method
+with C<@ARGV> as arguments.
+
+=head2 run_cli
+
+This method is meant to be overriden to implement your own command line mode for
+the app, be this a debugger, interactive mode or page generator.
+
+Its default implementation calls the C<run_cli_request> method with the
+arguments it was given, or, if that indicates failure by returning 0, calls
+C<cli_request_usage> to print a message explaining the correct CLI usage.
+
+=head2 run_cli_request
+
+Looks at the arguments passed to it, typically C<@ARGV> captured somewhere up the
+callstack, and tries to convert that into a sensible request against the
+application, which it then runs. Any results are printed to C<STDOUT>. Returns
+C<1> if it was able to run the request, and C<undef> if it was not able to
+covert the arguments into a sensible request.
+
+If run with a URL path, it runs a GET request against that path -
 
   $ perl -Ilib examples/hello-world/hello-world.cgi /
   200 OK
@@ -303,14 +338,10 @@ To send basic authentication credentials, use user:pass@ syntax -
 
   $ ./myapp GET bob:secret@/protected/path
 
-Additionally, you can treat the file as though it were a standard PSGI
-application file (*.psgi).  For example you can start up up with C<plackup>
+=head2 cli_request_usage
 
-  plackup my_web_simple_app.pl
-
-or C<starman>
-
-  starman my_web_simple_app.pl
+Prints a message explaining how to pass CLI parameters. Can be overridden for
+your own purposes.
 
 =head2 to_psgi_app
 
@@ -351,13 +382,6 @@ a separate C<*.psgi> file -
 This method can be called as a class method, in which case it implicitly
 calls ->new, or as an object method ... in which case it doesn't.
 
-=head2 run
-
-Used for running your application under stand-alone CGI and FCGI modes.
-
-I should document this more extensively but run_if_script will call it when
-you need it, so don't worry about it too much.
-
 =head2 run_test_request
 
   my $res = $app->run_test_request(GET => '/' => %headers);

diff --git a/t/request_mode_heuristics.t b/t/request_mode_heuristics.t
index 848a22e..51b469a 100644 (file)
--- a/t/request_mode_heuristics.t
+++ b/t/request_mode_heuristics.t
@@ -17,8 +17,7 @@ sub run {
     no warnings 'redefine';
     local *Web::Simple::Application::_run_fcgi             = sub { $res = "fcgi" };
     local *Web::Simple::Application::_run_cgi              = sub { $res = "cgi" };
-    local *Web::Simple::Application::_run_cli              = sub { $res = "cli" };
-    local *Web::Simple::Application::_run_cli_test_request = sub { $res = "test" };
+    local *Web::Simple::Application::run_cli               = sub { $res = "cli" };
     use strictures;
 
     {