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
  include Runnable
end

That gives you the basics to control the execution of ls command. You can overwrite the name of the command by using the executes macro:

class MyLs
  include Runnable

  executes :ls
end

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.

Custom output and exceptions

Runnable parse a set of user defined regular expresion to set up the command return values.

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

class Nmap
  include Runnable

  executes :nmap

  define_command( :scan, :blocking => true ) { |ip, subnet| "-sP #{ip}/#{subnet}" }
  scan_processors(
    :exceptions => { /^Illegal netmask value/ => ArgumentError },
    :outputs => { /Nmap scan report for (.*)/ => :ip }
  )
end

Nmap.new.scan("192.168.1.1", "24") # should return an array with the ips

Runnable can also raise custom exceptions, using the previously Nmap defined class: Nmap.new.scan("192.168.1.1", "1000") Will raise an ArgumentError exception. Note that Runnable will also raise an exception if the command returned value is not 0.

Background usage

Runnable can be used with background process:

class Ping
  include Runnable

  define_command( :goping, :blocking => false) { "-c5 www.google.es" }

  goping_processors(
    :outputs => { /64 bytes from .* time=(.*) ms/ => :time  }
  )
end

p = Ping.new
p.goping

while p.running?
  p p.output[:time]
  sleep 1
end

About

Runnable is a gem developed by NoSoloSoftware.

License

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