($Release: 0.1.0 $)
Benry-ActionRunner is a task runner. Similar to Rake, but much improved over Rake.
The main feature of Benry-ActionRunner compared to Rake is that each actions can take options and arguments.
For example, arun hello -l fr Alice runs hello action with an option -l fr and an argument Alice.
(Benry-ActionRunner requires Ruby >= 2.3)
$ gem install benry-actionrunner
$ arun --version
1.0.0
[bash]$ arun -h | less # print help message
[bash]$ arun -g # generate action file ('Actionfile.rb')
[bash]$ less Actionfile.rb # read content of action file
[bash]$ arun # list actions (or: `arun -l`)
[bash]$ arun -h hello # show help message of 'hello' action
[bash]$ arun hello Alice # run 'hello' action with arguments
Hello, Alice!
[bash]$ arun hello Alice -l fr # run 'hello' action with args and options
Bonjour, Alice!
[bash]$ arun xxxx: # list actions starting with 'xxxx:'
[bash]$ arun : # list prefixes of actions (or '::', ':::')
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class MyAction < Action
@action.("print greeting message")
def hello()
puts "Hello, world!"
end
end
Output:
[bash]$ ls Actionfile.rb
Actionfile.rb
[bash]$ arun hello
Hello, world!
It is not allowed to override existing method by action method.
For example, you can't define print() or test() method as action method
because these methods are defined in parent or ancestor class.
In this case, please rename action methods to print_() or test_().
These action methods are treated as action name print or test.
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class MyAction < Action
@action.("print greeting message")
def hello(name="world")
puts "Hello, #{name}!"
end
end
Output:
[bash]$ arun hello Alice
Hello, Alice!
Arguments are displayed in help message of actions.
[bash]$ arun -h hello
arun hello --- print greeting message
Usage:
$ arun hello [<options>] [<name>]
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class MyAction < Action
@action.("print greeting message")
@option.(:lang, "-l, --lang=<lang>", "language (en/fr/it)")
@option.(:repeat, "-n <N>", "repeat N times")
def hello(name="world", lang: "en", repeat: 1)
repeat.times do
case lang
when "en" ; puts "Hello, #{name}!"
when "fr" ; puts "Bonjour, #{name}!"
when "it" ; puts "Chao, #{name}!"
else ; raise "#{lang}: Unknown language."
end
end
end
end
Output:
[bash]$ arun hello -l fr Alice # or: arun hello Alice -l fr
Bonjour, Alice!
[bash]$ arun hello --lang=it Alice # or: arun hello Alice --lang=it
Chao, Alice!
Available option formats:
-h --- short--help --- long-h, --help --- both-f <file> --- short--file=<file> --- long-f, --file=<file> --- both-i[<width>] --- short--indent[=<width>] --- long-i, --indent[=<width>] --- bothNotice: --lang it style option is not supported for usability reason.
Use --lang=it style instead.
Keyword arguments of @option.():
type: Integer --- Option value should be an integer.enum: ["A", "B", "C"] --- Option value should be one of "A", "B", or "C".File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class MyAction < Action
@action.("print greeting message")
@option.(:lang, "-l, --lang=<lang>", "language", enum: ["en", "fr", "it"])
@option.(:repeat, "-n <N>", "repeat N times", type: Integer, range: 1..5)
def hello(name="world", lang: "en", repeat: 1)
repeat.times do
case lang
when "en" ; puts "Hello, #{name}!"
when "fr" ; puts "Bonjour, #{name}!"
when "it" ; puts "Chao, #{name}!"
else ; raise "#{lang}: Unknown language."
end
end
end
end
Output:
[bash]$ arun hello -l po Alice
[ERROR] -l po: Expected one of en/fr/it.
[bash]$ arun hello -n 99 Alice
[ERROR] -n 99: Too large (max: 5)
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class MyAction < Action
@action.("print greeting message")
@option.(:lang, "-l, --lang=<lang>", "language", enum: ["en", "fr", "it"])
@option.(:repeat, "-n <N>", "repeat N times", type: Integer, range: 1..5)
@option.(:color, "-c, --color[=<on|off>]", "color mode", type: TrueClass)
def hello(name="world", lang: "en", repeat: 1, color: false)
if color
name = "\e[32m#{name}\e[0m"
end
repeat.times do
case lang
when "en" ; puts "Hello, #{name}!"
when "fr" ; puts "Bonjour, #{name}!"
when "it" ; puts "Chao, #{name}!"
else ; raise "#{lang}: Unknown language."
end
end
end
end
Output:
[bash]$ arun hello --color=on Alice
Hello, Alice! # displayed with color
[bash]$ arun hello --color Alice
Hello, Alice! # displayed with color
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class GitAction < Action
prefix "git:" # should be "git:", not "git" !!!
@action.("show current status in compact format")
def status(path=".")
sys "git status -sb #{path}" # `sys` is like `system` or `sh`.
end
end
### or:
#class GitAction < Action
# @action.("show current status in compact format")
# def git__status(path=".")
# sys "git status -sb #{path}"
# end
#end
Output:
[bash]$ arun -l
Actions:
git:status : show current status in compact format
help : print help message (of action if specified)
[bash]$ arun git:status
$ git status -sb .
Prefix name should be a string which ends with ":". Symbol is not avaiable.
class GitAction < Action
prefix :git #=> error because Symbol is specified
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class GitAction < Action
prefix "git:" do
prefix "commit:" do
@action.("create a commit of current changes")
def create(msg); sys "git commit -m '#{msg}'"; end
end
prefix "branch:" do
@action.("create a new branch")
def create(name); sys "git checkout -b #{name}" ; end
@action.("switch current branch")
def switch(name); sys "git checkout #{name}"; end
end
end
end
Output:
[bash]$ arun -l
Actions:
git:branch:create : create a new branch
git:branch:switch : switch current branch
git:commit:create : create a commit of current changes
help : print help message (of action if specified)
Alias is a shortcut of action.
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class GitAction < Action
prefix "git:" do
prefix "commit:" do
@action.("create a commit of current changes")
def create(msg); sys "git commit -m '#{msg}'"; end
end
prefix "branch:" do
@action.("create a new branch")
def create(name); sys "git checkout -b #{name}" ; end
@action.("switch current branch")
def switch(name); sys "git checkout #{name}"; end
end
end
end
## define aliases
define_alias "ci" , "git:commit:create"
define_alias "fork" , "git:branch:create"
define_alias "sw" , "git:branch:switch"
Output:
[bash]$ arun -l
Actions:
ci : alias of 'git:commit:create'
fork : alias of 'git:branch:create'
git:branch:create : create a new branch
git:branch:switch : switch current branch
git:commit:create : create a commit of current changes
help : print help message (of action if specified)
sw : alias of 'git:branch:switch'
[bash]$ arun fork topic-foo # same as `arun git:branch:create topic-foo`
[bash]$ arun sw topic-foo # same as `arun git:branch:switch topic-foo`
Alias definition can include options and arguments.
For example, define_alias "correct", ["git:commit", "--amend"] defines an alias correct which invokes git:commit action with --amend option.
Rename git:status action to git (= prefix name):
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class GitAction < Action
prefix "git:", action: "status"
@action.("show current status in compact format")
def status(path=".")
sys "git status -sb #{path}" # `sys` is like `system` or `sh`.
end
end
Output: (git:status is renamed to git)
[bash]$ arun -l
Actions:
git : show current status in compact format
help : print help message (of action if specified)
Define an alias of git:status task as git (= prefix name):
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class GitAction < Action
prefix "git:", alias_of: "status"
@action.("show current status in compact format")
def status(path=".")
sys "git status -sb #{path}" # `sys` is like `system` or `sh`.
end
end
Output: (git is an alias of git:status)
[bash]$ arun -l
Actions:
git : alias of 'git:status'
git:status : show current status in compact format
help : print help message (of action if specified)
Prerequisite Action is not supported.
Instead, use run_once() which invokes other action only once.
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
class BuildAction < Action
@action.("setup something")
def setup()
puts ".... setup ...."
## register teardown block which will be invoked at end of process.
at_end {
puts ".... teardown ...."
}
end
@action.("build something")
def build()
run_once "setup" # invoke other action only once
run_once "setup" # !!! not invoked !!!
#run_action "setup" # run anyway
puts ".... build ...."
end
end
Output:
[bash]$ arun build
.... setup ....
.... build ....
.... teardown ....
Global long option such as --release=1.2.3 is recognized as global variable name and value.
File: Actionfile.rb
# coding: utf-8
require 'benry/actionrunner'
include Benry::ActionRunner::Export
## global variables
$project = "exmaple"
$release = "1.0.0"
class MyAction < Action
@action.("show global variables")
def gvars()
puts "$project=#{$project.inspect}, $release=#{$release.inspect}"
end
end
Output:
[bash]$ arun --project=myapp --release=1.2.3 gvars
$project="myapp", $release="1.2.3"
Debug option -D prints global variables specified in commiand-line.
This is useful to debug values of global variables.
[bash]$ arun -l -D --project=myapp --release=1.2.3
[DEBUG] $project = "myapp"
[DEBUG] $release = "1.2.3"
Actions:
gvars : show global variables
help : print help message (of action if specified)
Values of global variables in command-line are parsed as JSON string. If failed to parse as JSON string, it is handled as string value.
### parsed as JSON format
[bash]$ arun -l -D --data='["abc",123,true]' | grep DEBUG
[DEBUG] $data = ["abc", 123, true]
### 'null' in JSON results in 'nil' in Ruby
[bash]$ arun -l -D --data="null" | grep DEBUG
[DEBUG] $data = nil
### parsed as JSON quoted string
[bash]$ arun -l -D --data='"foo"' | grep DEBUG
[DEBUG] $data = "foo"
### failed to parse, because single quotation is not available in JSON
[bash]$ arun -l -D --data="'foo'" | grep DEBUG
[DEBUG] $data = "'foo'"
### failed to parse as JSON, therefore handled as just a string
[bash]$ arun -l -D --data="foo" | grep DEBUG
[DEBUG] $data = "foo"
In action methods, UNIX-like commands are available. These commands are implemented in Benry-UnixCommand and different from FileUtils.rb. For example:
mv "*.txt", to: "dir" instead of mv Dir["*.txt"], "dir".cp :p, "*.txt", to: "dir" instead of cp_p Dir["*.txt"], "dir".rm :rf, "dir/*" instead of rm_rf Dir["dir/*"].mkdir :p, "dir" instead of mkdir_p "dir".sys "command" instead of sh "command" or system "command".See the document of Benry-UnixCommand for details: https://kwatch.github.io/benry-ruby/benry-unixcommand.html
In contrast to Rake, Benry-ActionRunner doesn't automatically look for action file in the parent or higher directory (this is for security reason).
If you want Benry-ActionRunner to behave like Rake, add -u and -w options.
-u --- search for action file in parent or upper directory.-w --- change current directory to where action file exists.If you want to add these options always, set environment variable $ACTIONRUNNER_OPTION.
[bash]$ ls Actionfile.rb
Actionfile.rb
[bash]$ mkdir -p foo/bar/
[bash]$ cd foo/bar/ # Change current directory.
[bash]$ arun -l # Error because action file not found here.
[ERROR] Action file ('Actionfile.rb') not found. Create it by `arun -g` command firstly.
[bash]$ arun -l -wu # Search 'Actionfile.rb' and change current directory.
Actions:
hello : print greeting message
help : print help message (of action if specified)
[bash]$ export ACTIONRUNNER_OPTION="-up"
[bash]$ arun -l # No need to add `-wu`.
$ cd ../..
Actions:
build : build something
help : print help message (of action if specified)
setup : setup something
It is possible to make visibility of actions/aliases/options as hidden.
@action.("preparation", hidden: true)
@option.(:debug, "--debug", "enable debug mode", hidden: true)
def preparation()
....
end
define_alias "prep", "preparation", hidden: true
Hidden actions and options are not displayed in help message.
If you want to display hidden actions or options, add -a or --all option.
[bash]$ arun -la # show all actions including hidden ones
[bash]$ arun -la hello # show all options of action including hidden ones
It is possible to mark actions/aliases/options as important or not.
@action.("print greeting message", important: true)
@option.(:lang, "-l, --lang=<lang>", "language", important: true)
@option.(:repeat, "--repeat=<N>", "repeat N times", important: false)
def hello(name="world", lang: "en", repeat: 1)
# ....
end
define_alias "hi", "hello", important: false
undef_alias("fork") ## delete an alias
undef_action("git:branch:create") ## delete an action
CONFIG.default_action = "xxxx"
Benry-ActionRunner is empowerd by Benry-CmdApp. Many features of Benry-ActionRunner is derived from Benry-CmdApp.
If you are looking for any features not written in this document, see the document of Benry-CmdApp framework: https://kwatch.github.io/benry-ruby/benry-cmdapp.html
$License: MIT License $
$Copyright: copyright(c) 2023 kwatch@gmail.com $
FAQs
Unknown package
We found that benry-actionrunner demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.