Runfile lets you create command line tools in a way similar to Rake, but with the full power of Docopt command line options.
You create a runfile, and execute commands with
run command arguments -and --flags.
Runfile is designed primarily for Ruby developers, but if you need to add a command line "toolbelt" for your projects, you can use it regardless.
$ gem install runfile --pre$ run new # create a new runfile
$ run --help # show the usage patterns
$ vi runfile # edit the runfileA simple runfile looks like this. You can get this template by running
run new (in a directory without other runfiles).
title 'Greeter'
summary 'A sample runfile'
usage 'hello [NAME --shout]'
help 'Say hello'
option '--shout, -s', 'Greet louder'
action 'hello' do |args|
name = args['NAME'] || 'You...'
message = "Hello #{name}"
message = "#{message.upcase}!" if args['--shout']
say "gu`#{message}`"
endYou can then run it by executing this command:
$ run hello Luke
Hello LukeIt will behave in the same way you expect any standard command line interface to behave,
# Show usage summary
$ run
Usage:
run hello [NAME --shout]
run (--help | -h)
# Show detailed help
$ run --help
Greeter
A sample runfile
Usage:
run hello [NAME --shout]
run (--help | -h)
Commands:
hello
Say hello
Options:
--shout, -s
Greet louder
--help, -h
Show this messageYou can learn almost everything there is to know about runfile from the examples.
You can get any of these examples directly in your terminal by running:
$ run example --helpFor a more formal documentation, see the User Guide.
Show section
If you are using a version earlier than 1.0, note that version 1.0.0 includes some breaking changes. You can read more about them in this Pull Request.
If you have used the multi-runfile config file, this no longer exists.
Use a standard runfile instead, along with the import directive.
If you have used the action :global do notation, this is replaced with the
simpler use action do instead. Also, there is no more need for
empty usage '', just delete it if you have it in your runfiles.
If you have used it to cross-call other actions, it is no longer available. As
an alternative, you can define common code in separate classes and require
them, or use the new helpers directive to define functions that will be
available to all actions.
If your runfiles include other ruby code, especially def method, you should
now use the new helpers block and tuck this code inside it.
If your old runfiles trap the Interrupt signal, there is no longer a need to
do so, as it is trapped by default.
If your runfiles required and include Colsole, there is no longer a need to
do it. Colsole is bundled and available in actions.
This is a cosmetic change for consistency. All generated output shows long flags
before short flags --force, -f instead of -f, --force. Update your custom
usage directives accordingly.
If you were using the example directive, it will no longer add the initial
run in front of your examples. Add it yourself. This is intended to allow
providing more elaborate examples.
The runfile-tasks gem is also updated to 1.x, with a modified syntax. If you are using it, make sure to upgrade it as well.
If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.