package MooseX::Runnable;
+# ABSTRACT: Tag a class as a runnable application
use Moose::Role;
requires 'run';
__END__
-=head1 NAME
-
-MooseX::Runnable - tag a class as a runnable application
+=pod
=head1 SYNOPSIS
Create a class, tag it runnable, and provide a C<run> method:
package App::HelloWorld;
+ use feature 'say';
use Moose;
with 'MooseX::Runnable';
sub run {
- my $name = shift;
+ my ($self,$name) = @_;
say "Hello, $name.";
- return 0;
+ return 0; # success
}
Then you can run this class as an application with the included
=head1 REQUIRED METHODS
+=head2 run
+
+Your class must implement C<run>. It accepts the commandline args
+(that were not consumed by another parser, if applicable) and returns
+an integer representing the UNIX exit value. C<return 0> means
+success.
+
=head1 THINGS YOU GET
=head2 C<mx-run>
The syntax is:
- mx-run <args for mx-run> Class::Name <args for Class::Name>
+ mx-run Class::Name
+
+ mx-run <args for mx-run> -- Class::Name <args for Class::Name>
for example:
mx-run -Ilib App::HelloWorld --args --go --here
+or:
+
+ mx-run -Ilib +Persistent --port 8080 -- App::HelloWorld --args --go --here
+
=head2 C<MooseX::Runnable::Run>
If you don't want to invoke your app with C<mx-run>, you can write a
custom version using L<MooseX::Runnable::Run|MooseX::Runnable::Run>.
+
+=head1 ARCHITECTURE
+
+C<MX::Runnable> is designed to be extensible; users can run plugins
+from the command-line, and application developers can add roles to
+their class to control behavior.
+
+For example, if you consume L<MooseX::Getopt|MooseX::Getopt>, the
+command-line will be parsed with C<MooseX::Getopt>. Any recognized
+args will be used to instantiate your class, and any extra args will
+be passed to C<run>.
+
+=head1 BUGS
+
+Many of the plugins shipped are unstable; they may go away, change,
+break, etc. If there is no documentation for a plugin, it is probably
+just a prototype.
+
+=cut