Quickl

Description

Quickl helps you create commandline programs as simply as:

#
# Short description here
#
# SYNOPSIS
#   Usage: ...
#
# OPTIONS:
# #{sumarized_options}
#
# DESCRIPTION
#   Long description here...
#
class SimpleCommand < Quickl::Command(__FILE__, __LINE__)

  # install options below
  options do |opt|
    # _opt_ is an OptionParser instance
  end

  # install the code to run the command
  def execute(args)
    # _args_ are non-option command line parameters
  end

end

Running them as simply as:

SimpleCommand.run(ARGV)

From simple command to complex delegator (ala 'git [--version] [--help] COMMAND [cmd options] ARGS...'), Quickl provides (or aims at providing) the following features:

  • Simple command creations via simple classes
  • Delegator commands and categories via ruby namespaces and naming conventions
  • Command help and documentation provided through rdoc
  • Command options via standard OptionParser
  • Error handling trought special blocks, assertions methods and dedicated Error classes
  • Unit/spec testing of commands, as they are part of the software

Install

sudo gem install quickl

Then?

Try this:

# have a look at options
quickl --help

# generate a hello.rb single command
quickl --layout=single --options=help,version hello > hello.rb

# test your command
ruby hello.rb --help
ruby hello.rb --version
ruby hello.rb bob

# see what has been generated
cat hello.rb

Additional examples (see examples folder):

Version policy

Until version 1.0.0, moditications of public interfaces increase the minor version, while other changes increase the tiny version. After version 1.0.0, same changes will affect major and minor versions, respectively.

0.1.0 -> 0.1.1    # enhancements and private API changes
0.1.0 -> 0.2.0    # broken API on public interfaces

Public interfaces are:

  • Quickl::Command and Quickl::Delegator calls
  • DSL methods used in "subclasses" built by Quickl::Command and Quickl::Delegator
  • RDoc -> command line documentation recognizers (synopsis, overview, documentation, ...)
  • Naming conventions (module <-> command conversions)
  • Default reactions to errors (Quickl::Help, Quickl::Exit, ...)

Until version 1.0.0, to preserve your application from hurting changes you should require quickl as follows:

gem 'quickl', '< 0.2.0'    # Assuming current version is 0.1.xx
require 'quickl'

Licence

(The MIT License)

Copyright (c) 2010 Bernard Lambeau <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.