{"id":27197668,"url":"https://github.com/preaction/beam-runner","last_synced_at":"2025-07-23T11:04:24.874Z","repository":{"id":56835173,"uuid":"77415929","full_name":"preaction/Beam-Runner","owner":"preaction","description":"Command-line utility to configure, list, document, and execute runnable task objects","archived":false,"fork":false,"pushed_at":"2019-03-08T03:06:46.000Z","size":113,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T20:43:03.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/preaction.png","metadata":{"files":{"readme":"README.mkdn","changelog":"CHANGES","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-27T01:20:09.000Z","updated_at":"2019-03-08T03:06:45.000Z","dependencies_parsed_at":"2022-09-02T03:50:31.593Z","dependency_job_id":null,"html_url":"https://github.com/preaction/Beam-Runner","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/preaction/Beam-Runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FBeam-Runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FBeam-Runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FBeam-Runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FBeam-Runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/preaction","download_url":"https://codeload.github.com/preaction/Beam-Runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FBeam-Runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266665783,"owners_count":23964973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-09T20:29:19.455Z","updated_at":"2025-07-23T11:04:24.608Z","avatar_url":"https://github.com/preaction.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nBeam::Runner - Configure, list, document, and execute runnable task objects\n\n# VERSION\n\nversion 0.016\n\n# STATUS\n\n\u003ca href=\"https://travis-ci.org/preaction/Beam-Runner\"\u003e\u003cimg src=\"https://travis-ci.org/preaction/Beam-Runner.svg?branch=master\"\u003e\u003c/a\u003e\u003ca href=\"https://coveralls.io/r/preaction/Beam-Runner\"\u003e\u003cimg src=\"https://coveralls.io/repos/preaction/Beam-Runner/badge.png\" alt=\"Coverage Status\" /\u003e\u003c/a\u003e\n\n# SYNOPSIS\n\n    beam run \u003ccontainer\u003e \u003ctask\u003e [\u003cargs...\u003e]\n    beam list\n    beam list \u003ccontainer\u003e\n    beam help \u003ccontainer\u003e \u003ctask\u003e\n    beam help\n\n# DESCRIPTION\n\nThis distribution is an execution and organization system for runnable\nobjects (tasks). This allows you to prepare a list of runnable tasks in\nconfiguration files and then execute them. This also allows easy\ndiscovery of configuration files and objects, and allows you to document\nyour objects for your users.\n\n## Tasks\n\nA task is an object that consumes the [Beam::Runnable](https://metacpan.org/pod/Beam::Runnable) role. This role\nrequires only a `run()` method be implemented in the class. This\n`run()` method should accept all the arguments given on the command\nline. It can parse GNU-style options out of this array using\n[\"GetOptionsFromArray\" in Getopt::Long](https://metacpan.org/pod/Getopt::Long#GetOptionsFromArray).\n\nTask modules can compose additional roles to easily add more features,\nlike adding a timeout with [Beam::Runnable::Timeout::Alarm](https://metacpan.org/pod/Beam::Runnable::Timeout::Alarm).\n\nTask modules are expected to have documentation that will be displayed\nby the `beam list` and `beam help` commands. The `beam list` command\nwill display the `NAME` section of the documentation, and the `beam\nhelp` command will display the `NAME`, `SYNOPSIS`, `DESCRIPTION`,\n`ARGUMENTS`, `OPTIONS`, `ENVIRONMENT`, and `SEE ALSO` sections of\nthe documentation.\n\n## Configuration Files\n\nThe configuration file is a [Beam::Wire](https://metacpan.org/pod/Beam::Wire) container file that describes\nobjects. Some of these objects are marked as executable tasks by\nconsuming the [Beam::Runnable](https://metacpan.org/pod/Beam::Runnable) role.\n\nThe container file can have a special entry called `$summary` which\nhas a short summary that will be displayed when using the `beam list`\ncommand.\n\nHere's an example container file that has a summary, configures\na [DBIx::Class](https://metacpan.org/pod/DBIx::Class) schema (using the schema class for CPAN Testers:\n[CPAN::Testers::Schema](https://metacpan.org/pod/CPAN::Testers::Schema)), and configures a runnable task called\n`to_metabase` located in the class\n`CPAN::Testers::Backend::Migrate::ToMetabase`:\n\n    # migrate.yml\n    $summary: Migrate data between databases\n\n    _schema:\n        $class: CPAN::Testers::Schema\n        $method: connect_from_config\n\n    to_metabase:\n        $class: CPAN::Testers::Backend::Migrate::ToMetabase\n        schema:\n            $ref: _schema\n\nFor more information about container files, see [the Beam::Wire\ndocumentation](https://metacpan.org/pod/Beam::Wire).\n\n# QUICKSTART\n\nHere's a short tutorial for getting started with `Beam::Runner`. If you\nwant to try it yourself, start with an empty directory.\n\n## Create a Task\n\nTo create a task, make a Perl module that uses the [Beam::Runnable](https://metacpan.org/pod/Beam::Runnable) role\nand implements a `run` method. For an example, let's create a task that\nprints `Hello, World!` to the screen.\n\n    package My::Runnable::Greeting;\n    use Moo;\n    with 'Beam::Runnable';\n    sub run {\n        my ( $self, @args ) = @_;\n        print \"Hello, World!\\n\";\n    }\n    1;\n\nIf you're following along, save this in the\n`lib/My/Runnable/Greeting.pm` file.\n\n## Create a Configuration File\n\nNow that we have a task to run, we need to create a configuration file\n(or a \"container\"). The configuration file is a YAML file that describes\nall the tasks we can run. Let's create an `etc` directory and name our\ncontainer file `etc/greet.yml`.\n\nInside this file, we define our task. We have to give our task a simple\nname, like `hello`. Then we have to say what task class to run (in our case,\n`My::Runnable::Greeting`).\n\n    hello:\n        $class: My::Runnable::Greeting\n\n## Run the Task\n\nNow we can run our task. Before we do, we need to tell `Beam::Runner` where\nto find our code and our configuration by setting some environment variables:\n\n    $ export PERL5LIB=lib:$PERL5LIB\n    $ export BEAM_PATH=etc\n\nThe `PERL5LIB` environment variable adds directories for `perl` to search\nfor modules (like our task module). The `BEAM_PATH` environment variable\nadds directories to search for configuration files (like ours).\n\nTo validate that our environment variables are set correctly, we can list the\ntasks:\n\n    $ beam list\n    greet\n    - hello -- My::Runnable::Greeting\n\nThe `beam list` command looks through our `BEAM_PATH` directory, opens\nall the configuration files it finds, and lists all the\n[Beam::Runnable](https://metacpan.org/pod/Beam::Runnable) objects inside (helpfully giving us the module name for us\nto find documentation).\n\nThen, to run the command, we use `beam run` and give it the configuration file\n(`greet`) and the task (`hello`):\n\n    $ beam run greet hello\n    Hello, World!\n\n## Adding Documentation\n\nPart of the additional benefits of defining tasks in [Beam::Runnable](https://metacpan.org/pod/Beam::Runnable) modules\nis that the `beam help` command will show the documentation for the task. To\ndo this, we must add documentation to our module.\n\nThis documentation is done as [POD](https://metacpan.org/pod/perlpod), Perl's system of documentation.\nCertain sections of the documentation will be shown: `NAME`, `SYNOPSIS`,\n`DESCRIPTION`, `ARGUMENTS`, `OPTIONS`, and `SEE ALSO`.\n\n    =head1 NAME\n\n    My::Runnable::Greeting - Greet the user\n\n    =head1 SYNOPSIS\n\n        beam run greet hello\n\n    =head1 DESCRIPTION\n\n    This task greets the user warmly and then exits.\n\n    =head1 ARGUMENTS\n\n    No arguments are allowed during a greeting.\n\n    =head1 OPTIONS\n\n    Greeting warmly is the only option.\n\n    =head1 SEE ALSO\n\n    L\u003cBeam::Runnable\u003e\n\nIf we add this documentation to our `lib/My/Runnable/Greeting.pm` file,\nwe can then run `beam help` to see the documentation:\n\n    $ beam help greet hello\n    NAME\n        My::Runnable::Greeting - Greet the user\n\n    SYNOPSIS\n            beam run greet hello\n\n    DESCRIPTION\n        This task greets the user warmly and then exits.\n\n    ARGUMENTS\n        No arguments are allowed during a greeting.\n\n    OPTIONS\n        Greeting warmly is the only option.\n\n    SEE ALSO\n        Beam::Runnable\n\nThe `beam list` command will also use our new documentation to show the `NAME`\nsection:\n\n    $ beam list\n    greet\n    - hello -- My::Runnable::Greeting - Greet the user\n\n## Going Further\n\nFor more information on how to use the configuration file to create more\ncomplex objects like database connections, see\n[Beam::Wire::Help::Config](https://metacpan.org/pod/Beam::Wire::Help::Config).\n\nTo learn how to run your tasks using a distributed job queue to\nparallelize and improve performance, see [Beam::Minion](https://metacpan.org/pod/Beam::Minion).\n\n# SEE ALSO\n\n[beam](https://metacpan.org/pod/beam), [Beam::Runnable](https://metacpan.org/pod/Beam::Runnable), [Beam::Wire](https://metacpan.org/pod/Beam::Wire)\n\n# AUTHOR\n\nDoug Bell \u003cpreaction@cpan.org\u003e\n\n# COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2016 by Doug Bell.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreaction%2Fbeam-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpreaction%2Fbeam-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreaction%2Fbeam-runner/lists"}