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