# 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 uses another gems called ```Publisher```. It allow Runnable to fire 
events that can be processed or ignored. When a command ends its execution, 
Runnable always fire and event: ```:finish``` if commands finalized in a correct way 
or ```:fail``` if an error ocurred. In case something went wrong and a ```:fail``` 
events was fired, 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 can we receive the return value of a command:

    class LS < Runnable
    end

    my_command = LS.new

    my_command.when :finish do
      puts "Everything went better than expected :)"
    end

    my_command.when :fail do |exceptions|
      puts "Something went wrong"
      exceptions.each do |exception|
        puts exception.message
      end
    end

    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.