view release on metacpan or  search on metacpan

lib/Beam/Runner.pm  view on Meta::CPAN

#pod
#pod For more information about container files, see L<the Beam::Wire
#pod documentation|Beam::Wire>.
#pod
#pod =head1 QUICKSTART
#pod
#pod Here's a short tutorial for getting started with C<Beam::Runner>. If you
#pod want to try it yourself, start with an empty directory.
#pod
#pod =head2 Create a Task
#pod
#pod To create a task, make a Perl module that uses the L<Beam::Runnable> role
#pod and implements a C<run> method. For an example, let's create a task that
#pod prints C<Hello, World!> to the screen.
#pod
#pod     package My::Runnable::Greeting;
#pod     use Moo;
#pod     with 'Beam::Runnable';
#pod     sub run {
#pod         my ( $self, @args ) = @_;
#pod         print "Hello, World!\n";
#pod     }
#pod     1;
#pod
#pod If you're following along, save this in the
#pod C<lib/My/Runnable/Greeting.pm> file.
#pod
#pod =head2 Create a Configuration File
#pod
#pod Now that we have a task to run, we need to create a configuration file
#pod (or a "container"). The configuration file is a YAML file that describes
#pod all the tasks we can run. Let's create an C<etc> directory and name our
#pod container file C<etc/greet.yml>.
#pod
#pod Inside this file, we define our task. We have to give our task a simple
#pod name, like C<hello>. Then we have to say what task class to run (in our case,
#pod C<My::Runnable::Greeting>).
#pod
#pod     hello:
#pod         $class: My::Runnable::Greeting
#pod
#pod =head2 Run the Task
#pod
#pod Now we can run our task. Before we do, we need to tell C<Beam::Runner> where
#pod to find our code and our configuration by setting some environment variables:
#pod
#pod     $ export PERL5LIB=lib:$PERL5LIB
#pod     $ export BEAM_PATH=etc
#pod
#pod The C<PERL5LIB> environment variable adds directories for C<perl> to search
#pod for modules (like our task module). The C<BEAM_PATH> environment variable
#pod adds directories to search for configuration files (like ours).
#pod
#pod To validate that our environment variables are set correctly, we can list the
#pod tasks:
#pod
#pod     $ beam list
#pod     greet
#pod     - hello -- My::Runnable::Greeting
#pod
#pod The C<beam list> command looks through our C<BEAM_PATH> directory, opens
#pod all the configuration files it finds, and lists all the
#pod L<Beam::Runnable> objects inside (helpfully giving us the module name for us
#pod to find documentation).
#pod
#pod Then, to run the command, we use C<beam run> and give it the configuration file
#pod (C<greet>) and the task (C<hello>):
#pod
#pod     $ beam run greet hello
#pod     Hello, World!
#pod
#pod =head2 Adding Documentation
#pod
#pod Part of the additional benefits of defining tasks in L<Beam::Runnable> modules
#pod is that the C<beam help> command will show the documentation for the task. To
#pod do this, we must add documentation to our module.
#pod
#pod This documentation is done as L<POD|perlpod>, Perl's system of documentation.
#pod Certain sections of the documentation will be shown: C<NAME>, C<SYNOPSIS>,
#pod C<DESCRIPTION>, C<ARGUMENTS>, C<OPTIONS>, and C<SEE ALSO>.
#pod
#pod     =head1 NAME
#pod
#pod     My::Runnable::Greeting - Greet the user
#pod
#pod     =head1 SYNOPSIS
#pod
#pod         beam run greet hello
#pod
#pod     =head1 DESCRIPTION
#pod
#pod     This task greets the user warmly and then exits.
#pod
#pod     =head1 ARGUMENTS
#pod
#pod     No arguments are allowed during a greeting.
#pod
#pod     =head1 OPTIONS
#pod
#pod     Greeting warmly is the only option.
#pod
#pod     =head1 SEE ALSO
#pod
#pod     L<Beam::Runnable>
#pod
#pod If we add this documentation to our C<lib/My/Runnable/Greeting.pm> file,
#pod we can then run C<beam help> to see the documentation:
#pod
#pod     $ beam help greet hello
#pod     NAME
#pod         My::Runnable::Greeting - Greet the user
#pod
#pod     SYNOPSIS
#pod             beam run greet hello
#pod
#pod     DESCRIPTION
#pod         This task greets the user warmly and then exits.
#pod
#pod     ARGUMENTS
#pod         No arguments are allowed during a greeting.
#pod

lib/Beam/Runner.pm  view on Meta::CPAN

For more information about container files, see L<the Beam::Wire
documentation|Beam::Wire>.

=head1 QUICKSTART

Here's a short tutorial for getting started with C<Beam::Runner>. If you
want to try it yourself, start with an empty directory.

=head2 Create a Task

To create a task, make a Perl module that uses the L<Beam::Runnable> role
and implements a C<run> method. For an example, let's create a task that
prints C<Hello, World!> to the screen.

    package My::Runnable::Greeting;
    use Moo;
    with 'Beam::Runnable';
    sub run {
        my ( $self, @args ) = @_;
        print "Hello, World!\n";
    }
    1;

If you're following along, save this in the
C<lib/My/Runnable/Greeting.pm> file.

=head2 Create a Configuration File

Now that we have a task to run, we need to create a configuration file
(or a "container"). The configuration file is a YAML file that describes
all the tasks we can run. Let's create an C<etc> directory and name our
container file C<etc/greet.yml>.

Inside this file, we define our task. We have to give our task a simple
name, like C<hello>. Then we have to say what task class to run (in our case,
C<My::Runnable::Greeting>).

    hello:
        $class: My::Runnable::Greeting

=head2 Run the Task

Now we can run our task. Before we do, we need to tell C<Beam::Runner> where
to find our code and our configuration by setting some environment variables:

    $ export PERL5LIB=lib:$PERL5LIB
    $ export BEAM_PATH=etc

The C<PERL5LIB> environment variable adds directories for C<perl> to search
for modules (like our task module). The C<BEAM_PATH> environment variable
adds directories to search for configuration files (like ours).

To validate that our environment variables are set correctly, we can list the
tasks:

    $ beam list
    greet
    - hello -- My::Runnable::Greeting

The C<beam list> command looks through our C<BEAM_PATH> directory, opens
all the configuration files it finds, and lists all the
L<Beam::Runnable> objects inside (helpfully giving us the module name for us
to find documentation).

Then, to run the command, we use C<beam run> and give it the configuration file
(C<greet>) and the task (C<hello>):

    $ beam run greet hello
    Hello, World!

=head2 Adding Documentation

Part of the additional benefits of defining tasks in L<Beam::Runnable> modules
is that the C<beam help> command will show the documentation for the task. To
do this, we must add documentation to our module.

This documentation is done as L<POD|perlpod>, Perl's system of documentation.
Certain sections of the documentation will be shown: C<NAME>, C<SYNOPSIS>,
C<DESCRIPTION>, C<ARGUMENTS>, C<OPTIONS>, and C<SEE ALSO>.

    =head1 NAME

    My::Runnable::Greeting - Greet the user

    =head1 SYNOPSIS

        beam run greet hello

    =head1 DESCRIPTION

    This task greets the user warmly and then exits.

    =head1 ARGUMENTS

    No arguments are allowed during a greeting.

    =head1 OPTIONS

    Greeting warmly is the only option.

    =head1 SEE ALSO

    L<Beam::Runnable>

If we add this documentation to our C<lib/My/Runnable/Greeting.pm> file,
we can then run C<beam help> to see the documentation:

    $ beam help greet hello
    NAME
        My::Runnable::Greeting - Greet the user

    SYNOPSIS
            beam run greet hello

    DESCRIPTION
        This task greets the user warmly and then exits.

    ARGUMENTS
        No arguments are allowed during a greeting.