lib/MooseX/Runnable.pm

   1 package MooseX::Runnable;
   2 # ABSTRACT: Tag a class as a runnable application
   3 use Moose::Role;
   4
   5 requires 'run';
   6
   7 1;
   8
   9 __END__
  10
  11 =pod
  12
  13 =head1 SYNOPSIS
  14
  15 Create a class, tag it runnable, and provide a C<run> method:
  16
  17     package App::HelloWorld;
  18     use feature 'say';
  19     use Moose;
  20
  21     with 'MooseX::Runnable';
  22
  23     sub run {
  24        my ($self,$name) = @_;
  25        say "Hello, $name.";
  26        return 0; # success
  27     }
  28
  29 Then you can run this class as an application with the included
  30 C<mx-run> script:
  31
  32     $ mx-run App::HelloWorld jrockway
  33     Hello, jrockway.
  34     $
  35
  36 C<MooseX::Runnable> supports L<MooseX::Getopt|MooseX::Getopt>, and
  37 other similar systems (and is extensible, in case you have written
  38 such a system).
  39
  40 =head1 DESCRIPTION
  41
  42 MooseX::Runnable is a framework for making classes runnable
  43 applications.  This role doesn't do anything other than tell the rest
  44 of the framework that your class is a runnable application that has a
  45 C<run> method which accepts arguments and returns the process' exit
  46 code.
  47
  48 This is a convention that the community has been using for a while.
  49 This role tells the computer that your class uses this convention, and
  50 let's the computer abstract away some of the tedium this entails.
  51
  52 =head1 REQUIRED METHODS
  53
  54 =head2 run
  55
  56 Your class must implement C<run>.  It accepts the commandline args
  57 (that were not consumed by another parser, if applicable) and returns
  58 an integer representing the UNIX exit value.  C<return 0> means
  59 success.
  60
  61 =head1 THINGS YOU GET
  62
  63 =head2 C<mx-run>
  64
  65 This is a script that accepts a C<MooseX::Runnable> class and tries to
  66 run it, using C<MooseX::Runnable::Run>.
  67
  68 The syntax is:
  69
  70   mx-run Class::Name
  71
  72   mx-run <args for mx-run> -- Class::Name <args for Class::Name>
  73
  74 for example:
  75
  76   mx-run -Ilib App::HelloWorld --args --go --here
  77
  78 or:
  79
  80   mx-run -Ilib +Persistent --port 8080 -- App::HelloWorld --args --go --here
  81
  82 =head2 C<MooseX::Runnable::Run>
  83
  84 If you don't want to invoke your app with C<mx-run>, you can write a
  85 custom version using L<MooseX::Runnable::Run|MooseX::Runnable::Run>.
  86
  87 =head1 ARCHITECTURE
  88
  89 C<MX::Runnable> is designed to be extensible; users can run plugins
  90 from the command-line, and application developers can add roles to
  91 their class to control behavior.
  92
  93 For example, if you consume L<MooseX::Getopt|MooseX::Getopt>, the
  94 command-line will be parsed with C<MooseX::Getopt>.  Any recognized
  95 args will be used to instantiate your class, and any extra args will
  96 be passed to C<run>.
  97
  98 =head1 BUGS
  99
 100 Many of the plugins shipped are unstable; they may go away, change,
 101 break, etc.  If there is no documentation for a plugin, it is probably
 102 just a prototype.
 103
 104 =cut