clamp 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+.yardoc
+doc
+pkg/*

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    clamp (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    rake (0.8.7)
+    rr (1.0.0)
+    rspec (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+      rspec-mocks (~> 2.0.1)
+    rspec-core (2.0.1)
+    rspec-expectations (2.0.1)
+      diff-lcs (>= 1.1.2)
+    rspec-mocks (2.0.1)
+      rspec-core (~> 2.0.1)
+      rspec-expectations (~> 2.0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  clamp!
+  rake
+  rr (~> 1.0.0)
+  rspec (~> 2.0.1)

data/README.markdown

@@ -0,0 +1,40 @@
+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, and command invocations as instances of that class.
+
+"Command classes" are subclasses of `Clamp::Command`.  They look like this:
+
+    class InstallCommand < Clamp::Command
+    
+      option "--force", :flag, ""
+        
+      def execute
+        # do something
+      end
+        
+    end
+
+Class-level methods are available to declare command-line options, and document usage.  
+
+Clamp commands are invoked like so:
+
+    InstallCommand.run
+
+This will instantiate a new `InstallCommand`, handle command-line args, and finally call the  `#execute` method to do the real work.

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          = "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 makes 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/rename

@@ -0,0 +1,35 @@
+#! /usr/bin/env ruby
+
+require "clamp"
+
+class Rename < Clamp::Command
+
+  usage "[OPTIONS] TRANSFORM FILE ..."
+
+  argument "TRANSFORM", "a Ruby expression"
+  argument "FILE", "a file to rename"
+  
+  option ["-v", "--verbose"], :flag, "be verbose"
+
+  option ["-n", "--times"], "TIMES", "repetitions" do |n|
+    n = Integer(n)
+    raise ArgumentError, "too big" if n > 9
+    n
+  end
+
+  help_option
+  
+  def initialize(name)
+    super
+    @times = 1
+  end
+  
+  def execute
+    @times.times do
+      puts "Blah blah blah" if verbose?
+    end
+  end
+  
+end
+
+Rename.run

data/lib/clamp.rb

@@ -0,0 +1,3 @@
+require 'clamp/version'
+
+require 'clamp/command'

data/lib/clamp/argument.rb

@@ -0,0 +1,6 @@
+module Clamp
+  
+  class Argument < Struct.new(:name, :description)
+  end
+  
+end

data/lib/clamp/command.rb

@@ -0,0 +1,196 @@
+require 'clamp/argument'
+require 'clamp/option'
+
+module Clamp
+  
+  class Command
+    
+    def initialize(name)
+      @name = name
+    end
+    
+    attr_reader :name
+    attr_reader :arguments
+
+    def parse(arguments)
+      while arguments.first =~ /^-/
+        case (switch = arguments.shift)
+
+        when /\A--\z/
+          break
+
+        else
+          option = find_option(switch)
+          value = if option.flag?
+            option.flag_value(switch)
+          else
+            arguments.shift
+          end
+          begin
+            send("#{option.attribute_name}=", value)
+          rescue ArgumentError => e
+            signal_usage_error "option '#{switch}': #{e.message}"
+          end
+          
+        end
+      end
+      @arguments = arguments
+    end
+    
+    def execute
+      raise "you need to define #execute"
+    end
+    
+    def run(arguments)
+      parse(arguments)
+      execute
+    end
+
+    def help
+      self.class.help.gsub("__COMMAND__", name)
+    end
+    
+    private
+
+    def find_option(switch)
+      self.class.find_option(switch) || 
+      signal_usage_error("Unrecognised option '#{switch}'")
+    end
+
+    def signal_usage_error(message)
+      e = UsageError.new(message, self)
+      e.set_backtrace(caller)
+      raise e
+    end
+    
+    class << self
+    
+      def options
+        @options ||= []
+      end
+      
+      def option(switches, argument_type, description, opts = {}, &block)
+        option = Clamp::Option.new(switches, argument_type, description, opts)
+        self.options << option
+        declare_option_reader(option)
+        declare_option_writer(option, &block)
+      end
+      
+      def help_option(switches = ["-h", "--help"])
+        option(switches, :flag, "print help", :attribute_name => :help_requested) do
+          raise Clamp::HelpWanted.new(self)
+        end
+      end
+        
+      def has_options?
+        !options.empty?
+      end
+      
+      def find_option(switch)
+        options.find { |o| o.handles?(switch) }
+      end
+
+      def usage(usage)
+        @usages ||= []
+        @usages << usage
+      end
+
+      def arguments
+        @arguments ||= []
+      end
+      
+      def argument(name, description)
+        arguments << Argument.new(name, description)
+      end
+
+      def derived_usage
+        parts = arguments.map { |a| a.name }
+        parts.unshift("[OPTIONS]") if has_options?
+        parts.join(" ")
+      end
+      
+      def help
+        help = StringIO.new
+        help.puts "Usage:"
+        usages = @usages || [derived_usage]
+        usages.each_with_index do |usage, i|
+          help.puts "    __COMMAND__ #{usage}".rstrip
+        end
+        detail_format = "    %-29s %s"
+        unless arguments.empty?
+          help.puts "\nArguments:"
+          arguments.each do |argument|
+            help.puts detail_format % [argument.name, argument.description]
+          end
+        end
+        unless options.empty?
+          help.puts "\nOptions:"
+          options.each do |option|
+            help.puts detail_format % option.help
+          end
+        end
+        help.string
+      end
+      
+      def run(name = $0, args = ARGV)
+        begin 
+          new(name).run(args)
+        rescue Clamp::UsageError => e
+          $stderr.puts "ERROR: #{e.message}"
+          $stderr.puts ""
+          $stderr.puts e.command.help
+          exit(1)
+        rescue Clamp::HelpWanted => e
+          puts e.command.help
+        end
+      end
+
+      private
+      
+      def declare_option_reader(option)
+        reader_name = option.attribute_name
+        reader_name += "?" if option.flag?
+        class_eval <<-RUBY
+        def #{reader_name}
+          @#{option.attribute_name}
+        end
+        RUBY
+      end
+
+      def declare_option_writer(option, &block)
+        define_method("#{option.attribute_name}=") do |value|
+          if block
+            value = instance_exec(value, &block)
+          end
+          instance_variable_set("@#{option.attribute_name}", value)
+        end
+      end
+      
+    end
+        
+  end
+  
+  class Error < StandardError
+    
+    def initialize(message, command)
+      super(message)
+      @command = command
+    end
+
+    attr_reader :command
+    
+  end
+
+  # raise to signal incorrect command usage
+  class UsageError < Error; end
+  
+  # raise to request usage help
+  class HelpWanted < Error
+    
+    def initialize(command)
+      super("I need help", command)
+    end
+    
+  end
+  
+end

data/lib/clamp/option.rb

@@ -0,0 +1,54 @@
+module Clamp
+
+  class Option
+
+    def initialize(switches, argument_type, description, options = {})
+      @switches = Array(switches)
+      @argument_type = argument_type
+      @description = description
+      @attribute_name = options[:attribute_name].to_s if options.has_key?(:attribute_name)
+    end
+
+    attr_reader :switches, :argument_type, :description
+
+    def attribute_name
+      @attribute_name ||= long_switch.sub(/^--(\[no-\])?/, '').tr('-', '_')
+    end
+    
+    def long_switch
+      switches.find { |switch| switch =~ /^--/ }
+    end
+
+    def handles?(switch)
+      recognised_switches.member?(switch)
+    end
+
+    def flag?
+      @argument_type == :flag
+    end
+    
+    def flag_value(switch)
+      !(switch =~ /^--no-(.*)/ && switches.member?("--\[no-\]#{$1}"))
+    end
+    
+    def help
+      lhs = switches.join(", ")
+      lhs += " " + argument_type unless flag?
+      [lhs, description]
+    end
+
+    private
+    
+    def recognised_switches
+      switches.map do |switch|
+        if switch =~ /^--\[no-\](.*)/
+          ["--#{$1}", "--no-#{$1}"]
+        else
+          switch
+        end
+      end.flatten
+    end
+    
+  end
+
+end

data/lib/clamp/version.rb

@@ -0,0 +1,3 @@
+module Clamp
+  VERSION = "0.0.1".freeze
+end

data/spec/clamp/command_spec.rb

@@ -0,0 +1,385 @@
+require 'spec_helper'
+require 'stringio'
+
+describe Clamp::Command do
+
+  before do
+    $stdout = @out = StringIO.new
+    $stderr = @err = StringIO.new
+  end
+
+  after do
+    $stdout = STDOUT
+    $stderr = STDERR
+  end
+
+  def stdout
+    @out.string
+  end
+
+  def stderr
+    @err.string
+  end
+
+  def self.given_command(name, &block)
+    before do
+      @command = Class.new(Clamp::Command, &block).new(name)
+    end
+  end
+
+  given_command("cmd") do
+
+    def execute
+      print arguments.inspect
+    end
+
+  end
+
+  describe "#help" do
+
+    it "describes usage" do
+      @command.help.should include("Usage:\n    cmd\n")
+    end
+
+  end
+
+  describe "#parse" do
+
+    it "sets arguments" do
+      @command.parse(%w(a b c))
+      @command.arguments.should == %w(a b c)
+    end
+
+    describe "with an unrecognised option" do
+
+      it "raises a UsageError" do
+        lambda do
+          @command.parse(%w(--foo bar))
+        end.should raise_error(Clamp::UsageError)
+      end
+
+    end
+
+  end
+
+  describe "#run" do
+
+    before do
+      @abc = %w(a b c)
+      @command.run(@abc)
+    end
+
+    it "executes the #execute method" do
+      stdout.should_not be_empty
+    end
+
+    it "provides access to the argument list" do
+      stdout.should == @abc.inspect
+    end
+
+  end
+
+  describe ".option" do
+
+    before do
+      @command.class.option "--flavour", "FLAVOUR", "Flavour of the month"
+    end
+
+    it "declares option argument accessors" do
+      @command.flavour.should == nil
+      @command.flavour = "chocolate"
+      @command.flavour.should == "chocolate"
+    end
+
+  end
+
+  describe ".option", "with explicit :attribute_name" do
+
+    before do
+      @command.class.option "--foo", "FOO", "A foo", :attribute_name => :bar
+    end
+
+    it "uses the specified attribute_name name to name accessors" do
+      @command.bar = "chocolate"
+      @command.bar.should == "chocolate"
+    end
+
+    it "does not attempt to create the default accessors" do
+      @command.should_not respond_to(:foo)
+      @command.should_not respond_to(:foo=)
+    end
+    
+  end
+
+  describe "with options declared" do
+
+    before do
+      @command.class.option "--flavour", "FLAVOUR", "Flavour of the month"
+      @command.class.option "--color", "COLOR", "Preferred hue"
+    end
+
+    describe "#parse" do
+
+      describe "with options" do
+
+        before do
+          @command.parse(%w(--flavour strawberry --color blue a b c))
+        end
+
+        it "extracts the option values" do
+          @command.flavour.should == "strawberry"
+          @command.color.should == "blue"
+        end
+
+        it "retains unconsumed arguments" do
+          @command.arguments.should == %w(a b c)
+        end
+
+      end
+
+      describe "with option-like things beyond the arguments" do
+
+        it "treats them as positional arguments" do
+          @command.parse(%w(a b c --flavour strawberry))
+          @command.arguments.should == %w(a b c --flavour strawberry)
+        end
+
+      end
+
+      describe "with an option terminator" do
+
+        it "considers everything after the terminator to be an argument" do
+          @command.parse(%w(--color blue -- --flavour strawberry))
+          @command.arguments.should == %w(--flavour strawberry)
+        end
+
+      end
+
+    end
+
+    describe "#help" do
+
+      it "indicates that there are options" do
+        @command.help.should include("cmd [OPTIONS]")
+      end
+
+      it "includes option details" do
+        @command.help.should =~ %r(--flavour FLAVOUR +Flavour of the month)
+        @command.help.should =~ %r(--color COLOR +Preferred hue)
+      end
+
+    end
+
+  end
+
+  describe "with a flag option declared" do
+
+    before do
+      @command.class.option "--verbose", :flag, "Be heartier"
+    end
+
+    it "declares a predicate-style reader" do
+      @command.should respond_to(:verbose?)
+      @command.should_not respond_to(:verbose)
+    end
+
+    describe "#parse" do
+
+      describe "with option" do
+
+        before do
+          @command.parse(%w(--verbose foo))
+        end
+
+        it "sets the flag" do
+          @command.should be_verbose
+        end
+
+        it "does not consume an argument" do
+          @command.arguments.should == %w(foo)
+        end
+
+      end
+
+    end
+
+  end
+
+  describe "with a negatable flag option declared" do
+
+    before do
+      @command.class.option "--[no-]sync", :flag, "Synchronise"
+    end
+
+    describe "#parse" do
+
+      describe "with --flag" do
+
+        before do
+          @command.parse(%w(--sync))
+        end
+
+        it "sets the flag" do
+          @command.sync?.should be_true
+        end
+
+      end
+
+      describe "with --no-flag" do
+
+        before do
+          @command.sync = true
+          @command.parse(%w(--no-sync))
+        end
+
+        it "clears the flag" do
+          @command.sync?.should be_false
+        end
+
+      end
+
+    end
+
+  end
+
+  describe ".option, with a block" do
+
+    before do
+      @command.class.option "--port", "PORT", "Port to listen on" do |port|
+        Integer(port)
+      end
+    end
+
+    it "uses the block to validate and convert the option argument" do
+      lambda do
+        @command.port = "blah"
+      end.should raise_error(ArgumentError)
+      @command.port = "1234"
+      @command.port.should == 1234
+    end
+
+    describe "#parse" do
+
+      describe "with a valid option argument" do
+
+        it "stores the converted value" do
+          @command.parse(%w(--port 4321))
+          @command.port.should == 4321
+        end
+
+      end
+
+      describe "with an invalid option argument" do
+
+        it "raises a UsageError" do
+          lambda do
+            @command.parse(%w(--port blah))
+          end.should raise_error(Clamp::UsageError, /^option '--port': invalid value/)
+        end
+
+      end
+
+    end
+
+  end
+
+  describe "with explicit usage" do
+
+    given_command("blah") do
+
+      usage "FOO BAR ..."
+
+    end
+
+    describe "#help" do
+
+      it "includes the explicit usage" do
+        @command.help.should include("blah FOO BAR ...\n")
+      end
+
+    end
+
+  end
+
+  describe "with multiple usages" do
+
+    given_command("put") do
+
+      usage "THIS HERE"
+      usage "THAT THERE"
+
+    end
+
+    describe "#help" do
+
+      it "includes both potential usages" do
+        @command.help.should include("put THIS HERE\n")
+        @command.help.should include("put THAT THERE\n")
+      end
+
+    end
+
+  end
+
+  describe ".run" do
+
+    it "creates a new Command instance and runs it" do
+      @xyz = %w(x y z)
+      @command.class.run("cmd", @xyz)
+      stdout.should == @xyz.inspect
+    end
+
+    describe "when there's a UsageError" do
+
+      before do
+
+        @command.class.class_eval do
+          def execute
+            signal_usage_error "bad dog!"
+          end
+        end
+
+        begin 
+          @command.class.run("cmd", [])
+        rescue SystemExit => e
+          @system_exit = e
+        end
+
+      end
+
+      it "outputs the error message" do
+        stderr.should include "ERROR: bad dog!"
+      end
+
+      it "outputs help" do
+        stderr.should include "Usage:"
+      end
+
+      it "exits with a non-zero status" do
+        @system_exit.should_not be_nil
+        @system_exit.status.should == 1
+      end
+
+    end
+
+    describe "when help is requested" do
+
+      before do
+
+        @command.class.class_eval do
+          help_option "--help"
+        end
+
+        @command.class.run("cmd", ["--help"])
+
+      end
+
+      it "outputs help" do
+        stdout.should include "Usage:"
+      end
+
+    end
+
+  end
+
+end

data/spec/clamp/option_spec.rb

@@ -0,0 +1,113 @@
+require 'spec_helper'
+
+describe Clamp::Option do
+
+  describe "with String argument" do
+
+    before do
+      @option = Clamp::Option.new("--key-file", "FILE", "SSH identity")
+    end
+
+    it "has a long_switch" do
+      @option.long_switch.should == "--key-file"
+    end
+
+    it "has an argument_type" do
+      @option.argument_type.should == "FILE"
+    end
+
+    it "has a description" do
+      @option.description.should == "SSH identity"
+    end
+
+    describe "#attribute_name" do
+
+      it "is derived from the (long) switch" do
+        @option.attribute_name.should == "key_file"
+      end
+
+      it "can be overridden" do
+        @option = Clamp::Option.new("--key-file", "FILE", "SSH identity", :attribute_name => "ssh_identity")
+        @option.attribute_name.should == "ssh_identity"
+      end
+
+    end
+
+    describe "#help" do
+
+      it "combines switch, argument_type and description" do
+        @option.help.should == ["--key-file FILE", "SSH identity"]
+      end
+
+    end
+
+  end
+
+  describe "flag" do
+    
+    before do
+      @option = Clamp::Option.new("--verbose", :flag, "Blah blah blah")
+    end
+
+    describe "#help" do
+
+      it "excludes option argument" do
+        @option.help.should == ["--verbose", "Blah blah blah"]
+      end
+
+    end
+    
+  end
+
+  describe "negatable flag" do
+    
+    before do
+      @option = Clamp::Option.new("--[no-]force", :flag, "Force installation")
+    end
+
+    it "handles both positive and negative forms" do
+      @option.handles?("--force").should be_true
+      @option.handles?("--no-force").should be_true
+    end
+
+    describe "#flag_value" do
+
+      it "returns true for the positive variant" do
+        @option.flag_value("--force").should be_true
+        @option.flag_value("--no-force").should be_false
+      end
+
+    end
+    
+    describe "#attribute_name" do
+
+      it "is derived from the (long) switch" do
+        @option.attribute_name.should == "force"
+      end
+
+    end
+    
+  end
+
+  describe "with both short and long switches" do
+
+    before do
+      @option = Clamp::Option.new(["-k", "--key-file"], "FILE", "SSH identity")
+    end
+
+    it "handles both switches" do
+      @option.handles?("--key-file").should be_true
+      @option.handles?("-k").should be_true
+    end
+
+    describe "#help" do
+
+      it "includes both switches" do
+        @option.help.should == ["-k, --key-file FILE", "SSH identity"]
+      end
+
+    end
+
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require "rspec"
+require "clamp"
+
+Rspec.configure do |config|
+  
+  config.mock_with :rr
+
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: clamp
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mike Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-02 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: |
+  Clamp makes provides an object-model for command-line utilities.  
+  It handles parsing of command-line options, and generation of usage help.
+
+email: mdub@dogbiscuit.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.markdown
+- Rakefile
+- clamp.gemspec
+- examples/rename
+- lib/clamp.rb
+- lib/clamp/argument.rb
+- lib/clamp/command.rb
+- lib/clamp/option.rb
+- lib/clamp/version.rb
+- spec/clamp/command_spec.rb
+- spec/clamp/option_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/mdub/clamp
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: a minimal framework for command-line utilities
+test_files: 
+- spec/clamp/command_spec.rb
+- spec/clamp/option_spec.rb
+- spec/spec_helper.rb