runfile
runfile copied to clipboard
DannyBen
Command line for your projects
Runfile - command line for your projects
A beautiful command line utility builder
Rake-inspired ✦ Docopt inside
runfile.dannyb.co
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.
Demo
Install
$ gem install runfile --pre
Quick Start
$ run new # create a new runfile
$ run --help # show the usage patterns
$ vi runfile # edit the runfile
Example
A 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}`"
end
You can then run it by executing this command:
$ run hello Luke
Hello Luke
It 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 message
More Examples
You 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 --help
Documentation
For a more formal documentation, see the User Guide.
Breaking Changes in 1.0.0
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.
Upgrading to 1.0.0
No more .runfile config
If you have used the multi-runfile config file, this no longer exists.
Use a standard runfile instead, along with the import directive.
No more action :global
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.
No more execute directive
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.
Code outside of actions should be inside helpers
If your runfiles include other ruby code, especially def method, you should
now use the new helpers block and tuck this code inside it.
No more need for trap(:INT)
If your old runfiles trap the Interrupt signal, there is no longer a need to
do so, as it is trapped by default.
Colsole is included
If your runfiles required and include Colsole, there is no longer a need to
do it. Colsole is bundled and available in actions.
Long flags before short flags
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.
Examples no longer add implicit 'run'
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.
RunfileTasks
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.
Contributing / Support
If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.
DannyBen