# 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](http://nosolosoftware.biz).

# License
Runnable is Copyright 2011 NoSoloSoftware, it is free software.

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