lib/Maypole/CLI.pm

   1 package Maypole::CLI;
   2 use UNIVERSAL::require;
   3 use URI;
   4 use URI::QueryParam;
   5 use Maypole::Constants;
   6
   7 use strict;
   8 use warnings;
   9 my $package;
  10 our $buffer;
  11
  12 # Command line action
  13 CHECK {
  14     if ( ( caller(0) )[1] eq "-e" ) {
  15         $package->handler() == OK and print $buffer;
  16     }
  17 }
  18
  19 sub import {
  20     $package = $_[1];
  21     $package->require;
  22     die "Couldn't require $package - $@" if $@;
  23     no strict 'refs';
  24     unshift @{ $package . "::ISA" }, "Maypole::CLI";
  25 }
  26
  27 sub get_template_root { $ENV{MAYPOLE_TEMPLATES} || "." }
  28
  29 sub parse_location {
  30     my $self = shift;
  31     my $url  = URI->new( shift @ARGV );
  32     my $root = URI->new( $self->config->uri_base )->path;
  33     $self->{path} = $url->path;
  34     $self->{path} =~ s/^$root//i if $root;
  35     $self->parse_path;
  36     $self->parse_args($url);
  37 }
  38
  39 sub parse_args {
  40     my ( $self, $url ) = @_;
  41     $self->{params} = $url->query_form_hash;
  42     $self->{query}  = $url->query_form_hash;
  43 }
  44
  45 sub send_output { $buffer = shift->{output} }
  46
  47 sub call_url {
  48     my $self = shift;
  49     @ARGV = @_;
  50     $package->handler() == OK and return $buffer;
  51 }
  52
  53
  54 1;
  55
  56 =head1 NAME
  57
  58 Maypole::CLI - Command line interface to Maypole for testing and debugging
  59
  60 =head1 SYNOPSIS
  61
  62   % setenv MAYPOLE_TEMPLATES /var/www/beerdb/
  63   % perl -MMaypole::CLI=BeerDB -e1 http://localhost/beerdb/brewery/frontpage
  64
  65 =head1 DESCRIPTION
  66
  67 This module is used to test Maypole sites without going through a web
  68 server or modifying them to use a CGI frontend. To use it, you should
  69 first either be in the template root for your Maypole site or set the
  70 environment variable C<MAYPOLE_TEMPLATES> to the right value.
  71
  72 Next, you import the C<Maypole::CLI> module specifying your base Maypole
  73 subclass. The usual way to do this is with the C<-M> flag:
  74 C<perl -MMaypole::CLI=MyApp>. This is equivalent to:
  75
  76     use Maypole::CLI qw(MyApp);
  77
  78 Now Maypole will automatically call your application's handler with the
  79 URL specified as the first command line parameter. This should be the
  80 full URL, starting from whatever you have defined as the C<uri_base> in
  81 your application's configuration, and may include query parameters.
  82
  83 The Maypole HTML output should then end up on standard output.
  84
  85 =head1 Support for testing
  86
  87 The module can also be used as part of a test script.
  88
  89 When used programmatically, rather than from the command line, its
  90 behaviour is slightly different.
  91
  92 Although the URL is taken from C<@ARGV> as normal, your application's
  93 C<handler> method is not called automatically, as it is when used on the
  94 command line; you need to call it manually. Additionally, when
  95 C<handler> is called, the output is not printed to standard output but
  96 stored in C<$Maypole::CLI::buffer>, to allow you to check the contents
  97 more easily.
  98
  99 For instance, a test script could look like this:
 100
 101     use Test::More tests => 3;
 102     use Maypole::CLI qw(BeerDB);
 103     use Maypole::Constants;
 104     $ENV{MAYPOLE_TEMPLATES} = "t/templates";
 105
 106     # Hack because isa_ok only supports object isa not class isa
 107     isa_ok( (bless {},"BeerDB") , "Maypole");
 108
 109     like(BeerDB->call_url("http://localhost/beerdb/"), qr/frontpage/, "Got the front page");
 110
 111     like(BeerDB->call_url("http://localhost/beerdb/beer/list"), qr/Organic Best/, "Found a beer in the list");
 112
 113 =head1 METHODS
 114
 115 =over
 116
 117 =item call_url
 118
 119 for use in scripts. takes an url as argument, and returns the buffer.
 120
 121 =back
 122
 123
 124 =head1 Implementation
 125
 126 This class overrides a set of methods in the base Maypole class to provide it's
 127 functionality. See L<Maypole> for these:
 128
 129 =over
 130
 131 =item get_template_root
 132
 133 =item parse_args
 134
 135 =item parse_location
 136
 137 =item send_output
 138
 139 =back
 140
 141 =cut