jls-clamp 0.3.1

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+.rvmrc
+.yardoc
+doc
+pkg/*
+Gemfile.lock
+ 

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "rake"
+  gem "rspec", "~> 2.6.0"
+  gem "rr", "~> 1.0.4"
+end

data/README.markdown

@@ -0,0 +1,274 @@
+Clamp
+=====
+
+"Clamp" is a minimal framework for command-line utilities.  
+
+It handles boring stuff like parsing the command-line, and generating help, so you can get on with making your command actually do stuff.
+
+Not another one!
+----------------
+
+Yeah, sorry.  There are a bunch of existing command-line parsing libraries out there, and Clamp draws inspiration from a variety of sources, including [Thor], [optparse], and [Clip].  In the end, though, I wanted a slightly rounder wheel.
+
+[optparse]: http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html
+[Thor]: http://github.com/wycats/thor
+[Clip]: http://clip.rubyforge.org/
+
+Quick Start
+-----------
+
+Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They look something like this:
+
+    class SpeakCommand < Clamp::Command
+
+      option "--loud", :flag, "say it loud"
+      option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
+        Integer(s)
+      end
+
+      parameter "WORDS ...", "the thing to say", :attribute_name => :words
+
+      def execute
+        the_truth = words.join(" ")
+        the_truth.upcase! if loud?
+        iterations.times do
+          puts the_truth
+        end
+      end
+
+    end
+
+Calling `run` on a command class creates an instance of it, then invokes it using command-line arguments (from ARGV, by default).
+
+    SpeakCommand.run
+
+Class-level methods like `option` and `parameter` declare attributes (in a similar way to `attr_accessor`), and arrange for them to be populated automatically based on command-line arguments.  They are also used to generate `help` documentation.  
+
+Declaring options
+-----------------
+
+Options are declared using the `option` method.  The three required arguments are:
+
+  1. the option switch (or switches),
+  2. an option argument name
+  3. a short description
+
+For example:
+
+    option "--flavour", "FLAVOUR", "ice-cream flavour"
+
+It works a little like `attr_accessor`, defining reader and writer methods on the command class.  The attribute name is derived from the switch (in this case, "`flavour`").  When you pass options to your command, Clamp will populate the attributes, which are then available for use in your `#execute` method.
+
+    def execute
+      puts "You chose #{flavour}.  Excellent choice!"
+    end
+
+If you don't like the inferred attribute name, you can override it:
+
+    option "--type", "TYPE", "type of widget", :attribute_name => :widget_type
+                                               # to avoid clobbering Object#type
+
+### Short/long option switches
+
+The first argument to `option` can be an array, rather than a single string, in which case all the switches are treated as aliases:
+
+    option ["-s", "--subject"], "SUBJECT", "email subject line"
+
+### Flag options
+
+Some options are just boolean flags.  Pass "`:flag`" as the second parameter to tell Clamp not to expect an option argument:
+
+    option "--verbose", :flag, "be chatty"
+
+For flag options, Clamp appends "`?`" to the generated reader method; ie. you get a method called "`#verbose?`", rather than just "`#verbose`".
+
+Negatable flags are easy to generate, too: 
+
+    option "--[no-]force", :flag, "be forceful (or not)"
+
+Clamp will handle both "`--force`" and "`--no-force`" options, setting the value of "`#force?`" appropriately.
+
+Declaring parameters
+--------------------
+
+Positional parameters can be declared using `parameter`, specifying
+
+  1. the parameter name, and
+  2. a short description
+
+For example:
+
+    parameter "SRC", "source file"
+
+Like options, parameters are implemented as attributes of the command, with the default attribute name derived from the parameter name (in this case, "`src`"). By convention, parameter names are specified in uppercase, to make them obvious in usage help.
+
+### Optional parameters
+
+Wrapping a parameter name in square brackets indicates that it's optional, e.g.
+
+    parameter "[TARGET_DIR]", "target directory"
+
+### Greedy parameters
+
+Three dots at the end of a parameter name makes it "greedy" - it will consume all remaining command-line arguments.  For example:
+
+    parameter "FILE ...", "input files"
+
+The suffix "`_list`" is appended to the default attribute name for greedy parameters; in this case, an attribute called "`file_list`" would be generated.
+
+Parsing and validation of options and parameters
+------------------------------------------------
+
+When you `#run` a command, it will first attempt to `#parse` command-line arguments, and map them onto the declared options and parameters, before invoking your `#execute` method.
+
+Clamp will verify that all required (ie. non-optional) parameters are present, and signal a error if they aren't.
+
+### Validation block
+
+Both `option` and `parameter` accept an optional block.  If present, the block will be 
+called with the raw string option argument, and is expected to coerce it to 
+the correct type, e.g.
+
+    option "--port", "PORT", "port to listen on" do |s|
+      Integer(s)
+    end
+
+If the block raises an ArgumentError, Clamp will catch it, and report that the value was bad:
+
+    !!!plain
+    ERROR: option '--port': invalid value for Integer: "blah"
+
+### Advanced option/parameter handling
+
+While Clamp provides an attribute-writer method for each declared option or parameter, you always have the option of overriding it to provide custom argument-handling logic, e.g.
+
+    parameter "SERVER", "location of server"
+    
+    def server=(server)
+      @server_address, @server_port = server.split(":")
+    end
+
+### Default values
+
+Default values can be specified for options:
+
+    option "--flavour", "FLAVOUR", "ice-cream flavour", :default => "chocolate"
+
+and also for optional parameters
+
+    parameter "[HOST]", "server host", :default => "localhost"
+
+For more advanced cases, you can also specify default values by defining a method called "`default_#{attribute_name}`":
+
+    option "--http-port", "PORT", "web-server port", :default => 9000
+
+    option "--admin-port", "PORT", "admin port"
+
+    def default_admin_port
+       http_port + 1
+    end
+
+Declaring Subcommands
+---------------------
+
+Subcommand support helps you wrap a number of related commands into a single script (ala tools like "`git`").  Clamp will inspect the first command-line argument (after options are parsed), and delegate to the named subcommand.
+
+Unsuprisingly, subcommands are declared using the `subcommand` method. e.g.
+
+    class MainCommand < Clamp::Command
+
+      subcommand "init", "Initialize the repository" do
+
+        def execute
+          # ...
+        end
+
+      end
+      
+    end
+
+Clamp generates an anonymous subclass of the current class, to represent the subcommand.  Alternatively, you can provide an explicit subcommand class:
+    
+    class MainCommand < Clamp::Command
+
+      subcommand "init", "Initialize the repository", InitCommand
+      
+    end
+
+    class InitCommand < Clamp::Command
+
+      def execute
+        # ...
+      end
+
+    end
+
+### Default subcommand
+
+You can set a default subcommand, at the class level, as follows:
+
+    class MainCommand < Clamp::Command
+
+      self.default_subcommand = "status"
+      
+      subcommand "status", "Display current status" do
+
+        def execute
+          # ...
+        end
+
+      end
+      
+    end
+
+Then, if when no SUBCOMMAND argument is provided, the default will be selected.
+
+### Subcommand options and parameters
+
+Options are inheritable, so any options declared for a command are supported for it's sub-classes (e.g. those created using `subcommand`).  Parameters, on the other hand, are not inherited - each subcommand must declare it's own parameter list.
+
+Note that, if a subcommand accepts options, they must be specified on the command-line _after_ the subcommand name.  
+
+Getting help
+------------
+
+All Clamp commands support a "`--help`" option, which outputs brief usage documentation, based on those seemingly useless extra parameters that you had to pass to `option` and `parameter`.
+
+    $ speak --help
+    Usage:
+        speak [OPTIONS] WORDS ...
+
+    Arguments:
+        WORDS ...                     the thing to say
+
+    Options:
+        --loud                        say it loud
+        -n, --iterations N            say it N times (default: 1)
+        -h, --help                    print help
+
+License
+-------
+
+Copyright (C) 2011 [Mike Williams](mailto:mdub@dogbiscuit.org)
+
+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 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.
+
+Contributing to Clamp
+---------------------
+
+Source-code for Clamp is [on Github](https://github.com/mdub/clamp).  

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+
+task "default" => "spec"
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rspec_opts = ["--colour", "--format", "nested"]
+end

data/clamp.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clamp/version"
+
+Gem::Specification.new do |s|
+
+  s.name          = "jls-clamp"
+  s.version       = Clamp::VERSION.dup
+  s.platform      = Gem::Platform::RUBY
+  s.authors       = ["Mike Williams"]
+  s.email         = "mdub@dogbiscuit.org"
+  s.homepage      = "http://github.com/mdub/clamp"
+
+  s.summary       = %q{a minimal framework for command-line utilities}
+  s.description   = <<EOF
+Clamp provides an object-model for command-line utilities.  
+It handles parsing of command-line options, and generation of usage help.
+EOF
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+end

data/examples/flipflop

@@ -0,0 +1,31 @@
+#! /usr/bin/env ruby
+
+# An example of subcommands
+
+require "clamp"
+require "clamp/version"
+
+class FlipFlop < Clamp::Command
+
+  option ["--version", "-v"], :flag, "Show version" do
+    puts "Powered by Clamp-#{Clamp::VERSION}"
+    exit(0)
+  end
+
+  self.default_subcommand = "flip"
+
+  subcommand "flip", "flip it" do
+    def execute
+      puts "FLIPPED"
+    end
+  end
+
+  subcommand "flop", "flop it" do
+    def execute
+      puts "FLOPPED"
+    end
+  end
+
+end
+
+FlipFlop.run

data/examples/fubar

@@ -0,0 +1,23 @@
+#! /usr/bin/env ruby
+
+# An example of subcommands
+
+require "clamp"
+
+class Fubar < Clamp::Command
+
+  subcommand "foo", "Foo!" do
+
+    subcommand "bar", "Baaaa!" do
+
+      def execute
+        puts "FUBAR"
+      end
+
+    end
+
+  end
+
+end
+
+Fubar.run

data/examples/gitdown

@@ -0,0 +1,61 @@
+#! /usr/bin/env ruby
+
+# Demonstrate how subcommands can be declared as classes
+
+require "clamp"
+
+module GitDown
+
+  class AbstractCommand < Clamp::Command
+
+    option ["-v", "--verbose"], :flag, "be verbose"
+
+    option "--version", :flag, "show version" do
+      puts "GitDown-0.0.0a"
+      exit(0)
+    end
+
+  end
+
+  class CloneCommand < AbstractCommand
+    
+    parameter "REPOSITORY", "repository to clone"
+    parameter "[DIR]", "working directory", :default => "."
+
+    def execute
+      raise NotImplementedError
+    end
+    
+  end
+
+  class PullCommand < AbstractCommand
+
+    option "--[no-]commit", :flag, "Perform the merge and commit the result."
+
+    def execute
+      raise NotImplementedError
+    end
+    
+  end
+
+  class StatusCommand < AbstractCommand
+    
+    option ["-s", "--short"], :flag, "Give the output in the short-format."
+
+    def execute
+      raise NotImplementedError
+    end
+    
+  end
+
+  class MainCommand < AbstractCommand
+    
+    subcommand "clone", "Clone a remote repository.", CloneCommand
+    subcommand "pull", "Fetch and merge updates.", PullCommand
+    subcommand "status", "Display status of local repository.", StatusCommand
+
+  end
+
+end
+
+GitDown::MainCommand.run

data/examples/speak

@@ -0,0 +1,33 @@
+#! /usr/bin/env ruby
+
+# A simple Clamp command, with options and parameters
+
+require "clamp"
+
+class SpeakCommand < Clamp::Command
+
+  self.description = %{
+    Say something.
+  }
+
+  option "--loud", :flag, "say it loud"
+  option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
+    Integer(s)
+  end
+
+  parameter "WORDS ...", "the thing to say", :attribute_name => :words
+
+  def execute
+
+    the_truth = words.join(" ")
+    the_truth.upcase! if loud?
+
+    iterations.times do
+      puts the_truth
+    end
+
+  end
+
+end
+
+SpeakCommand.run

data/lib/clamp/attribute.rb

@@ -0,0 +1,40 @@
+module Clamp
+
+  class Attribute
+
+    attr_reader :description, :attribute_name, :default_value, :env_var
+
+    def help_rhs
+      rhs = description
+      if defined?(@default_value)
+        rhs += " (default: #{@default_value.inspect})"
+      end
+      if defined?(@env_var)
+        rhs += " (env: #{@env_var.inspect})"
+      end
+      rhs
+    end
+
+    def help
+      [help_lhs, help_rhs]
+    end
+
+    def ivar_name
+      "@#{attribute_name}"
+    end
+
+    def read_method
+      attribute_name
+    end
+
+    def default_method
+      "default_#{read_method}"
+    end
+
+    def write_method
+      "#{attribute_name}="
+    end
+
+  end
+
+end

data/lib/clamp/attribute_declaration.rb

@@ -0,0 +1,40 @@
+module Clamp
+
+  module AttributeDeclaration
+
+    protected
+
+    def define_accessors_for(attribute, &block)
+      define_reader_for(attribute)
+      define_default_for(attribute)
+      define_writer_for(attribute, &block)
+    end
+
+    def define_reader_for(attribute)
+      define_method(attribute.read_method) do
+        if instance_variable_defined?(attribute.ivar_name)
+          instance_variable_get(attribute.ivar_name)
+        else
+          send(attribute.default_method)
+        end
+      end
+    end
+
+    def define_default_for(attribute)
+      define_method(attribute.default_method) do
+        attribute.default_value
+      end
+    end
+
+    def define_writer_for(attribute, &block)
+      define_method(attribute.write_method) do |value|
+        if block
+          value = instance_exec(value, &block)
+        end
+        instance_variable_set(attribute.ivar_name, value)
+      end
+    end
+
+  end
+
+end