Ing
Vanilla ruby command-line scripting.
or gratuitous backronym: I Need a Generator!
(Note this is a work-in-progress. Expect some quirkiness.)
The command-line syntax is similar to Thor's, and it incorporates Thor's (Rails') generator methods and shell conventions like
if yes? 'process foo files?', :yellow
inside('foo') { create_file '%foo_file%.rb' }
end
but unlike Thor or Rake, it does not define its own DSL. Your tasks correspond to plain ruby classes and methods. Ing just handles routing from the command line to them, and setting options. Your classes (or even Procs) do the rest.
Option parsing courtesy of the venerable and excellent Trollop, under the hood.
Installation
gem install ing
To generate a default ing.rb
file that loads from a tasks
directory:
ing setup
A quick tour
The command line
The ing command line is generally parsed as
[ing command] [ing command options] [subcommand] [args] [subcommand options]
But in cases where the first argument isn't a built-in ing command or options, it's simplified to
[subcommand] [args] [subcommand ]
The "subcommand" is your task. To take some examples.
ing -r ./path/to/some/task.rb some:task run something --verbose
ing -r
loads specified ruby files or libraries/gems; then- it dispatches to
Some::Task.new(:verbose => true).run("something")
.
(Assuming you define a task Some::Task#run
, in /path/to/some/task.rb
.)
You can -r as many libaries/files as you like. Of course, that gets pretty long-winded.
By default, it requires a file ./ing.rb
if it exists (the equivalent of
Rakefile or Thorfile). In which case, assuming your task class is
defined or loaded from there, the command can be simply
ing some:task run something --verbose
Built-in commands
Ing has some built-in commands. These are still being implemented, but
you can see what they are so far with ing list -n ing:commands
.
The most significant subcommand is generate
or g
, which
simplifies a common and familiar use-case (at the expense of some file-
system conventions):
ing generate some:task --force
Unlike Thor/Rails generators, these don't need to be packaged up as gems and preloaded into ruby. They can be either parsed as:
- A file relative to a root dir: e.g. some/task, or
- A subdirectory of the root dir, in which case it attempts to
preload
ing.rb
within that subdirectory: e.g. some/task/ing.rb
The command above is then dispatched as normal to
Some::Task.new(:force => true).call
(#call
is used if no method is
specified). So you should put the task code within that namespace in the
preloaded file.
(By default, the generator root directory is specified by
ENV['ING_GENERATORS_ROOT']
or failing that, ~/.ing/generators
.)
TODO: more examples needed
A simple example of a plain old ruby task
Let's say you want to run your project's tests with a command like ing test
.
The default is to run the whole suite; but if you just want unit tests you can
say ing test unit
. This is what it would look like (in ./ing.rb
):
class Test
# no options passed, but you need the constructor
def initialize(); end
# `ing test`
def call(*args)
suite
end
# `ing test suite`
def suite
unit; functional; acceptance
end
# `ing test unit`
def unit
type 'unit'
end
# `ing test functional`
def functional
type 'functional'
end
# `ing test acceptance`
def acceptance
type 'acceptance'
end
def type(dir)
Dir["./test/#{dir}/*.rb"].each { |f| require_relative f }
end
end
As you can see, the second arg corresponds to the method name. call
is what
gets called when there is no second arg. Organizing the methods like this means
you can also do ing test type custom
: extra non-option arguments are passed
into the method as parameters.
For more worked examples of ing tasks, see the examples directory.
Option arguments
Your tasks (ing subcommands) can specify what options they take by defining a
class method specify_options
. For example:
class Cleanup
def self.(spec)
spec.text "Clean up your path"
spec.text "\nUsage:"
spec.text "ing cleanup [OPTIONS]"
spec.text "\nOptions:"
spec.opt :quiet, "Run silently"
spec.opt :path, "Path to clean up", :type => :string, :default => '.'
end
attr_accessor :options
def initialize()
self. =
end
# ...
end
The syntax used in self.specify_options
is Trollop - in fact what you are
doing is building a Trollop::Parser
which then emits the parsed options into
your constructor.
In general your constructor should just save the options to an instance variable like this, but in some cases you might want to do further processing of the passed options.
Using the Task base class
To save some boilerplate, and to allow more flexible options specification,
as well as a few more conveniences, you can inherit from Ing::Task
and
rewrite this example as:
class Cleanup < Ing::Task
desc "Clean up your path"
usage "ing cleanup [OPTIONS]"
opt :quiet, "Run silently"
opt :path, "Path to clean up", :type => :string, :default => '.'
# ...
end
This gives you a slightly more automated help message, with the description lines followed by usage followed by options, and with headers for each section.
Ing::Task
also lets you inherit options. Say you have another task:
class BigCleanup < Cleanup
opt :servers, "On servers", :type => :string, :multi => true
end
This task will have the two options from its superclass as well as its own. (Note the description and usage lines are not inherited this way, only the options).
Generator tasks
If you want to use Thor-ish generator methods, your task classes need a few more things added to their interface. Basically, it should look something like this.
class MyGenerator
def self.(spec)
# ...
end
include Ing::Files
attr_accessor :destination_root, :source_root, :options, :shell
# default == execution from within your project directory
def destination_root
@destination_root ||= Dir.pwd
end
# default == current file is within root directory of generator files
def source_root
@source_root ||= File.(File.dirname(__FILE__))
end
def initialize()
self. =
end
# ...
end
The generator methods need :destination_root
, :source_root
, and :shell
.
Also, include Ing::Files
after you specify any options (this is because
Ing::Files
adds several options automatically).
If you prefer, you can inherit from Ing::Generator
, which gives you all of
the above defaults, plus the functionality of Ing::Task
.
Like Ing::Task
, Ing::Generator
is simply a convenience for common scenarios.
Motivation
I wanted to use Thor's generator methods and shell conventions to write my own generators. But I didn't want to fight against Thor's hijacking of ruby classes.
Brief note about the design
One of the design principles is to limit inheritance (classical and mixin), and most importantly to avoid introducing new state via inheritance. An important corollary of this is that the application objects, ie. your task classes, must themselves take responsibility for their interface with the underlying resources they mix in or compose, instead of those resources providing the interface (via so-called macro-style class methods, for instance).
Q & A
But what about task dependency resolution?
That's what require
and ||=
are for ;)
Seriously, you do have Ing.invoke Some::Task, :some_method
and Ing.execute ...
for this kind of thing. Personally I think it's a code smell to put reusable
code in things that are also run from the command line. Is it application or
library code? Controller or model? But invoke
is there if you must, hopefully
with a suitably ugly syntax to dissuade you. :P
But what about security?
Yes, this means any ruby library and even built-in classes can be exercised from the command line... but so what?
You can't run module methods, and the objects you invoke need to have a hash constructor. So Kernel, Process, IO, File, etc. are pretty much ruled out. Most of the ruby built-in classes are ruled out in fact.
More to the point, you're already in a shell with much more dangerous knives lying around. You had better trust the scripts you're working with!