Sickle

Description

Sickle is dead simple library for building complex command line tools. A lot of ideas and examples were inspired by thor.

Features:

Based on classes and modules
Support for commands
Support for namespaces
Support for command options and global options
Usage and help for free
No external dependencies (only stdlib optparse)

Requirements

Ruby: 1.9.x, 2.0.x, jruby (1.9), rbx (1.9)

Installation

You are probably building command line tool that will be released as gem, just add that line to you gemspec.

spec.add_dependency 'sickle'

Usage

Basic usage

Simple create a class with methods and some options

require "sickle"

class App
  include Sickle::Runner

  global_flag :verbose                        # global flag, defaults to false
  global_option :with_prefix                  # global option, defaults to nil

  # optional before hook with access to global options
  before do
    $verbose = options[:verbose]
  end

  desc "install one of the available apps"    # command description
  flag :force                                 # flag for `install` command
  option :host, :default => "localhost"       # option
  def install(name)
    if options[:force]                         # access options
      do_smth_with options[:host]
    end
    # the rest
  end

  desc "list all apps, search is possible"
  def list(search = "")
    # ...
  end

end

App.run(ARGV) # start parsing ARGV

This will allow for execution command like:

$ mytool install foo
$ mytool install foo --force --verbose --host 127.0.0.1
$ mytool list
$ mytool list rails --verbose

Help is for free:

$ mytool help
USAGE:
  mytool COMMAND [ARG1, ARG2, ...] [OPTIONS]

TASKS:
  help [COMMAND]
  install NAME    # install one of the available apps
  list [SEARCH]   # list all apps, search is possible

GLOBAL OPTIONS:
  --verbose (default: false)

There is also detailed help for command:

$ mytool help install
USAGE:
  mytool install NAME

DESCRIPTION:
  install one of the available apps

OPTIONS:
  --force (default: false)
  --host (default: localhost)

Advanced usage - multiple modules

module Users
  include Sickle::Runner

  desc "list all users"
  def list
    # ...
  end

  desc "create new user"
  def create(name)
    # ...
  end
end

module Projects
  include Sickle::Runner

  desc "list all projects"
  def list
    # ...
  end
end

module Global
  include Sickle::Runner

  desc "have some fun at top level"
  def fun
    # ...
  end
end

class App
  include Sickle::Runner

  desc "top level command"
  def main
    # ...
  end

  include_modules :users => Users,      # bind commands from Users module under "users" namespace
                  :p     => Projects    # bind commands from Projects module under "p" namespace

  include Global                        # bind command from Global module at top level namespace
end

App.run(ARGV)

Run $ mytool help to see how commands are namespaced:

$ mytool help
USAGE:
  mytool COMMAND [ARG1, ARG2, ...] [OPTIONS]

TASKS:
  fun                # have some fun at top level
  help [COMMAND]
  main               # top level command
  p:list             # list all projects
  users:create NAME  # create new user
  users:list         # list all users

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

sickle

Development