-
-
08 Mar 2019 03:07:13 UTC
- Distribution: Beam-Runner
- Module version: 0.016
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (6)
- Testers (536 / 16 / 4)
- Kwalitee
Bus factor: 1- 95.11% Coverage
- License: perl_5
- Perl: v5.10.0
- Activity
24 month- Tools
- Download (35.79KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
NAME
Beam::Runner - Configure, list, document, and execute runnable task objects
VERSION
version 0.016
SYNOPSIS
beam run <container> <task> [<args...>] beam list beam list <container> beam help <container> <task> beam help
DESCRIPTION
This distribution is an execution and organization system for runnable objects (tasks). This allows you to prepare a list of runnable tasks in configuration files and then execute them. This also allows easy discovery of configuration files and objects, and allows you to document your objects for your users.
Tasks
A task is an object that consumes the Beam::Runnable role. This role requires only a
run()
method be implemented in the class. Thisrun()
method should accept all the arguments given on the command line. It can parse GNU-style options out of this array using "GetOptionsFromArray" in Getopt::Long.Task modules can compose additional roles to easily add more features, like adding a timeout with Beam::Runnable::Timeout::Alarm.
Task modules are expected to have documentation that will be displayed by the
beam list
andbeam help
commands. Thebeam list
command will display theNAME
section of the documentation, and thebeam help
command will display theNAME
,SYNOPSIS
,DESCRIPTION
,ARGUMENTS
,OPTIONS
,ENVIRONMENT
, andSEE ALSO
sections of the documentation.Configuration Files
The configuration file is a Beam::Wire container file that describes objects. Some of these objects are marked as executable tasks by consuming the Beam::Runnable role.
The container file can have a special entry called
$summary
which has a short summary that will be displayed when using thebeam list
command.Here's an example container file that has a summary, configures a DBIx::Class schema (using the schema class for CPAN Testers: CPAN::Testers::Schema), and configures a runnable task called
to_metabase
located in the classCPAN::Testers::Backend::Migrate::ToMetabase
:# migrate.yml $summary: Migrate data between databases _schema: $class: CPAN::Testers::Schema $method: connect_from_config to_metabase: $class: CPAN::Testers::Backend::Migrate::ToMetabase schema: $ref: _schema
For more information about container files, see the Beam::Wire documentation.
QUICKSTART
Here's a short tutorial for getting started with
Beam::Runner
. If you want to try it yourself, start with an empty directory.Create a Task
To create a task, make a Perl module that uses the Beam::Runnable role and implements a
run
method. For an example, let's create a task that printsHello, 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
lib/My/Runnable/Greeting.pm
file.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
etc
directory and name our container fileetc/greet.yml
.Inside this file, we define our task. We have to give our task a simple name, like
hello
. Then we have to say what task class to run (in our case,My::Runnable::Greeting
).hello: $class: My::Runnable::Greeting
Run the Task
Now we can run our task. Before we do, we need to tell
Beam::Runner
where to find our code and our configuration by setting some environment variables:$ export PERL5LIB=lib:$PERL5LIB $ export BEAM_PATH=etc
The
PERL5LIB
environment variable adds directories forperl
to search for modules (like our task module). TheBEAM_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
beam list
command looks through ourBEAM_PATH
directory, opens all the configuration files it finds, and lists all the Beam::Runnable objects inside (helpfully giving us the module name for us to find documentation).Then, to run the command, we use
beam run
and give it the configuration file (greet
) and the task (hello
):$ beam run greet hello Hello, World!
Adding Documentation
Part of the additional benefits of defining tasks in Beam::Runnable modules is that the
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 POD, Perl's system of documentation. Certain sections of the documentation will be shown:
NAME
,SYNOPSIS
,DESCRIPTION
,ARGUMENTS
,OPTIONS
, andSEE 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
lib/My/Runnable/Greeting.pm
file, we can then runbeam 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. OPTIONS Greeting warmly is the only option. SEE ALSO Beam::Runnable
The
beam list
command will also use our new documentation to show theNAME
section:$ beam list greet - hello -- My::Runnable::Greeting - Greet the user
Going Further
For more information on how to use the configuration file to create more complex objects like database connections, see Beam::Wire::Help::Config.
To learn how to run your tasks using a distributed job queue to parallelize and improve performance, see Beam::Minion.
SEE ALSO
beam, Beam::Runnable, Beam::Wire
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Module Install Instructions
To install Beam::Runner, copy and paste the appropriate command in to your terminal.
cpanm Beam::Runner
perl -MCPAN -e shell install Beam::Runner
For more information on module installation, please visit the detailed CPAN module installation guide.