Commit | Line | Data |
d42333d2 |
1 | package MooseX::Runnable; |
d1de1498 |
2 | # ABSTRACT: Tag a class as a runnable application |
d42333d2 |
3 | use Moose::Role; |
4 | |
d42333d2 |
5 | requires 'run'; |
6 | |
c527660e |
7 | 1; |
8 | |
9 | __END__ |
10 | |
d1de1498 |
11 | =pod |
c527660e |
12 | |
13 | =head1 SYNOPSIS |
d42333d2 |
14 | |
c527660e |
15 | Create a class, tag it runnable, and provide a C<run> method: |
16 | |
17 | package App::HelloWorld; |
05e7b5d0 |
18 | use feature 'say'; |
c527660e |
19 | use Moose; |
20 | |
21 | with 'MooseX::Runnable'; |
22 | |
23 | sub run { |
05e7b5d0 |
24 | my ($self,$name) = @_; |
c527660e |
25 | say "Hello, $name."; |
00d7989a |
26 | return 0; # success |
d42333d2 |
27 | } |
28 | |
c527660e |
29 | Then you can run this class as an application with the included |
30 | C<mx-run> script: |
d42333d2 |
31 | |
c527660e |
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 | |
fc5720d5 |
54 | =head2 run |
55 | |
fdbedd6c |
56 | Your class must implement C<run>. It accepts the command-line args |
fc5720d5 |
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 | |
c527660e |
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 | |
6c3ff9ca |
70 | mx-run Class::Name |
71 | |
2503822b |
72 | mx-run <args for mx-run> -- Class::Name <args for Class::Name> |
c527660e |
73 | |
74 | for example: |
75 | |
6c3ff9ca |
76 | mx-run -Ilib App::HelloWorld --args --go --here |
c527660e |
77 | |
2503822b |
78 | or: |
79 | |
6c3ff9ca |
80 | mx-run -Ilib +Persistent --port 8080 -- App::HelloWorld --args --go --here |
81 | |
c527660e |
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>. |
fc5720d5 |
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 | |
d1de1498 |
104 | =cut |