lib/MooseX/Runnable.pm

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