rprogram

RProgram

• Source
• Issues
• Documentation
• [Email](mailto:postmodern.mod3 at gmail.com)

Description

RProgram is a library for creating wrappers around command-line programs. RProgram provides a Rubyful interface to programs and all their options or non-options. RProgram can also search for programs installed on a system.

Features

• Safely executes individual programs and their separate command-line arguments, to prevent command or option injection.
• Supports using Ruby 1.9 exec options.
• Supports specifying environment variables of a process (only available on Ruby 1.9).
• Allows running programs with IO.popen (only available on Ruby 1.9).
• Allows running programs under sudo.
• Provides cross-platform access to the PATH environment variable.
• Supports leading/tailing non-options.
• Supports long-options and short-options.
• Supports custom formating of options.

Examples

First, create the class to represent the options of the program, using {RProgram::Task} as the base class:

require 'rprogram/task'

class MyProgTask < RProgram::Task

  # map in the short-options
  short_option :flag => '-o', :name => :output
  short_option :flag => '-oX', :name => :xml_output

  # map in long options
  long_option :flag => '--no-resolv', :name => :disable_resolv

  # long_option can infer the :name option, based on the :flag
  long_option :flag => '--mode'

  # options can also take multiple values
  long_option :flag => '--includes', :multiple => true

  # options with multiple values can have a custom separator character
  long_option :flag      => '--ops',
              :multiple  => true,
              :separator => ','

  # define any non-options (aka additional arguments)
  non_option :tailing => true, :name => :files

end

Next, create the class to represent the program you wish to interface with, using {RProgram::Program} as the base class:

require 'my_prog_task'

require 'rprogram/program'

class MyProg < RProgram::Program

  # identify the file-name of the program
  name_program 'my_prg'

  # add a top-level method which finds and runs your program.
  def self.my_run(options={},&block)
    self.find.my_run(options,&block)
  end

  # add a method which runs the program with MyProgTask.
  def my_run(options={},&block)
    run_task(MyProgTask.new(options,&block))
  end

end

Finally, run your program with options or a block:

MyProgram.my_run(:mode => :fast, :files => ['test1'])
# => true

MyProgram.my_run do |my_prog|
  my_prog.includes = ['one', 'two', 'three']
  my_prog.mode     = :safe

  my_prog.output = 'output.txt'
  my_prog.files  = ['test1.txt', 'test2.txt']
end
# => true

Install

$ gem install rprogram

License

Copyright (c) 2007-2012 Hal Brodigan

See {file:LICENSE.txt} for license information.