lib/MooseX/Runnable.pm

   1 package MooseX::Runnable;
   2 use Moose::Role;
   3
   4 our $VERSION = '0.00_02';
   5
   6 requires 'run';
   7
   8 1;
   9
  10 __END__
  11
  12 =head1 NAME
  13
  14 MooseX::Runnable - tag a class as a runnable application
  15
  16 =head1 SYNOPSIS
  17
  18 Create a class, tag it runnable, and provide a C<run> method:
  19
  20     package App::HelloWorld;
  21     use Moose;
  22
  23     with 'MooseX::Runnable';
  24
  25     sub run {
  26        my $name = shift;
  27        say "Hello, $name.";
  28        return 0; # success
  29     }
  30
  31 Then you can run this class as an application with the included
  32 C<mx-run> script:
  33
  34     $ mx-run App::HelloWorld jrockway
  35     Hello, jrockway.
  36     $
  37
  38 C<MooseX::Runnable> supports L<MooseX::Getopt|MooseX::Getopt>, and
  39 other similar systems (and is extensible, in case you have written
  40 such a system).
  41
  42 =head1 DESCRIPTION
  43
  44 MooseX::Runnable is a framework for making classes runnable
  45 applications.  This role doesn't do anything other than tell the rest
  46 of the framework that your class is a runnable application that has a
  47 C<run> method which accepts arguments and returns the process' exit
  48 code.
  49
  50 This is a convention that the community has been using for a while.
  51 This role tells the computer that your class uses this convention, and
  52 let's the computer abstract away some of the tedium this entails.
  53
  54 =head1 REQUIRED METHODS
  55
  56 =head1 THINGS YOU GET
  57
  58 =head2 C<mx-run>
  59
  60 This is a script that accepts a C<MooseX::Runnable> class and tries to
  61 run it, using C<MooseX::Runnable::Run>.
  62
  63 The syntax is:
  64
  65   mx-run Class::Name
  66
  67   mx-run <args for mx-run> -- Class::Name <args for Class::Name>
  68
  69 for example:
  70
  71   mx-run -Ilib App::HelloWorld --args --go --here
  72
  73 or:
  74
  75   mx-run -Ilib +Persistent --port 8080 -- App::HelloWorld --args --go --here
  76
  77 =head2 C<MooseX::Runnable::Run>
  78
  79 If you don't want to invoke your app with C<mx-run>, you can write a
  80 custom version using L<MooseX::Runnable::Run|MooseX::Runnable::Run>.