Clue

Clue is an oriented-object wrapper around command line utilities. It allows you to execute complex shell commands without the harass of building the string manually. The use-case in mind when creating this gem was rake tasks/capistrano recipes involving third party tools.

Prerequisites

Build Status

This gem depends only on activesupport. It is tested agains many rubies: 1.8.7, 1.9.3, 2.0.0, jruby-18, jruby-19, rubinius-18, rubinius-19, thanks to travis-ci.

While it is tested against Ruby 1.8, we do not garanty support in future releases, as it is approaching end of life.

Installation

Directly : gem install clue

Gemfile : gem 'clue'

Usage

There is only one class, Clue. First, instantiate the object, then invoke call without arguments on it. In most cases, the only difference of usage will be the options passed to the constructor, though you can set them later.

Example

clue = Clue.new 'mytool', :options => [:drop, {:depth => 1}], :arguments => '~/.hidden', :stdout => '~/not_hidden'
clue.call

# Will execute:
# mytool --depth '1' --drop ~/.hidden > '~/not_hidden'

Command name

The command name can be supplied when initializing the object, as done above, or at a later point, by setting command to some value. Calling call will raise an exception if command is not present.

Config

Not all command line tools expects the same format of options, value, inputs; you can configure those when initialiazing the object, or at a later point using the config hash. It recognizes :

  • between_arguments: defaults to ' '. Used between arguments list
  • between_options: defaults to ' '. Used between options list.
  • between_streams: defaults to ' '. Used between streams list.
  • option_value_separator: defaults to ' '. Used between an option and its value. Will usually be ' ' or =.
  • option_prefix: defaults to '--'. Prepended to an option. Will usually be -, or --.
  • option_delimiter: defaults to "'". Surrounds an option value, in order to prevent escaping issues.
  • stream_delimiter: defaults to "'". Surrounds a stream, in order to prevent escaping issues.

Options

Clue accepts options when initializing, as in clue = Clue.new(options: [:first, :second, {third: :value}]).

You must supply "singular" (options without value) first, and "valued" options as a trailing hash, as shown above. You can add options at a later point use add_singular_option, add_singular_options, add_option, and add_options.

Arguments

Clue accepts arguments when initializing, as in clue = Clue.new(arguments: 'path/to/file'). While in most of the case a single argument will be passed, you can pass an array as well.

Streams

Clue handles stdin, stdout, and stderr when initializing, as in clue = Clue.new(stdout: 'path/to/file'). Only strings will be recognized.

Verbose/dry-run

Clue can run in verbose or dry_run mode. The first prints the command before running, the latter only prints it. You can activate those modes when initializing, by supplying verbose: true or dry_run: true, or by setting the values at a later point. Both of them are false by default.

Hooks

There is two type of hooks, running at two points: before/after initialize/call. They allow you to print extra data or to execute specific manipulation when subclassing Clue.

One use case is in novelys/gomon, where after_initialize is used to parse & split the uri option, and before/after_call are used to inform of what is happening.

Validations

There is no mecanisme built-in for validating the presence/format of arguments, as we feel there is not a great need for it. However, if you come with an elegant and tested solution, we'll consider merging it.

Contributions

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. In the first case, please include a use-case.
  2. Fork the repository on Github, make a feature branch, work on this branch.
  3. If necessary, write a test which shows that the bug was fixed or that the feature works as expected.
  4. Send a pull request and annoy us until we notice it. :)

Changelog

  • 1.1.0: Allow configuration of cli command string defaults.
  • 1.0.0: First version.