Runnable

A Ruby gem that allow programmer to control UNIX system commands as a Ruby class.

Usage

All you have to do is to create a class named exactly as command and make it inherit from class Runnable.

class LS < Runnable
end

That gives you the basics to control the execution of ls command.

Now you can create an instance like this:

my_command = LS.new

And run the command as follows

my_command.run

Many other options are available; you can stop the command, kill it or look for some important information about the command and its process. Entire documentation of this gem can be generated using yardoc. To do this use rake doc.

Return values

Runnable has two special methods which are called at the end of a command execution.
:finish if commands finalized in a correct way and :fail if an error ocurred. In case something went wrong and a :fail method is called, Runnable also provide an array containing the command return value as the parameter of a SystemCallError exception and optionally others exceptions ocurred at runtime.

This is an example of how we can receive the return value of a command:

class LS < Runnable

  def finish
    puts "Everything went better than expected :)"
  end

  def failed( exceptions )
    puts "Something went wrong :("
    exceptions.each do |exception|
      puts exception.message
    end   
  end

end

my_command = LS.new    
my_command.run

Custom exceptions

As we saw in previous chapter, if a command execution does not ends succesfully, Runnable fires a :fail event whit an exceptions array. We can add exceptions to that array based on the output of command. For example, we can controll that parameters passed to a command are valids if we know the command output for an invalid parameters.

First we have to do is override the method exceptions defined in runnable as follows

class LS < Runnable
  def exceptions
    { /ls: (invalid option.*)/ => ArgumentError }
  end
end

exceptions method should return a hash containing a regular expression which will be match against the command output, and a value which will be the exception added to exception array. This means that if the command output match the regular expression, a new exception will be include in :fail event parameter.

About

Runnable is a gem developed by NoSoloSoftware.

License

Runnable is distributed under GPLv3 license. More details can be found at COPYING file.