clamp 0.5.1 → 0.6.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDFlNTQ5ZTA5ODJmZjI4NjU3OTE0YzEwYzJjMzcwNTAzNzlhMGJjMA==
+    YzQ1YTM1YTRmM2Q2ZDRiMDEzY2M1YzBmM2Y5YjM4ZDlhZTYzNWFmZA==
   data.tar.gz: !binary |-
-    MjhlMDdmNGYzY2E2ZDVmYTQxMzA2OTcwYmY1NDBmZjM1ZGJlMTczNA==
+    MDMzN2JhYTAxYjYwNmZhZjhlMzEwZDJmMTM0MTBhOWVhZjFkMjIxYQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    YjNlMjQ0OTdiMzZlYzYzOGJiNGI3YmI0NGIwODA4NmRhYTVlMWMxMTE0NzVl
-    NDRiYjIxN2JhNjMzMDliZDdjODgxMmJmOTU0MWY5NTUwYTg2YjY3MzBkZTU0
-    MGExZmI3NzRkMWM1NWEyY2ZlODIxOTFkZDYyMGMxYjFhYTJkN2E=
+    NzA4ZmI2ZmNjMmE4YzZlZDY4ZjUwZTVlMDIyYTJjZmQ5NDkxNDZkMjI0NDhi
+    M2E3NmUwZDE3NTUxNWViM2FmMDc5ZDc3NzRiNjQ2YjY1NjlkMzgwMjM0NTgy
+    NWM0ODJmODdkYTY2MTc3ZDBiZDdhZTU5N2Q1OTRjYTcyYzNlYWM=
   data.tar.gz: !binary |-
-    ZDc0NzQ1YTYyNzIzZTY2ODZlYzk4ZjVmYmE1OGU5OGYxODI2MzMzMDk5YzEx
-    ZTBkMzM3ZjNhZGNkYTNlODhjZWFhMjI1ZTA4NmRlMGJhNmVkNmFjNGIxZDc4
-    ZmY4ZGJhYWZhMWJlNzlkZWM1YzBjMGUzZGI2YWUxNzk3MmQyMzk=
+    ZDU4Yzg2ODViNjBlOWRmY2Y3OTZjNGEyYzZhMmFjZDZiYjc4MWI5ZjY5NTZl
+    OWZjN2I4YTEwYjE0ZTZiMTFkMmRmYjk3OTE3ODMyNzhjYWY4MDc1NjZiYTE4
+    OGNkZmYxODFiYjlhMzM5ZThiOTQ0M2U0NDllZDcyNWQyMjA0ZDk=

data/.autotest

@@ -0,0 +1,9 @@
+Autotest.add_hook :initialize do |at|
+
+  at.add_exception ".git"
+
+  at.add_mapping(%r{^lib/(.*)\.rb$}, :prepend) do |_, match|
+    ["spec/unit/#{match[1]}_spec.rb"] + Dir['spec/clamp/command*_spec.rb']
+  end
+
+end

data/.travis.yml

@@ -3,3 +3,4 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - 2.0.0

data/CHANGES.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.6.0 (2013-04-??)
+
+* Introduce "banner" to describe a command (replacing "self.description=").
+* Allow parameters to be specified before a subcommand.
+* Add support for :multivalued options.
+* Multi valued options and parameters get an "#append_to_foo_list" method, rather than
+  "#foo_list=".
+

data/{README.markdown → README.md}

@@ -1,4 +1,4 @@
-Clamp
+Clamp  [![Build Status](https://secure.travis-ci.org/mdub/clamp.png?branch=master)](http://travis-ci.org/mdub/clamp)
 =====
 
 "Clamp" is a minimal framework for command-line utilities.
@@ -19,6 +19,8 @@ Quick Start
 
 Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They look something like this:
 
+    require 'clamp'
+
     class SpeakCommand < Clamp::Command
 
       option "--loud", :flag, "say it loud"
@@ -38,12 +40,16 @@ Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They lo
 
     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.
 
+The call to `run` creates an instance of the command class, then invokes it with command-line arguments (from `ARGV`).
+
+There are more examples demonstrating various features of Clamp [on Github][examples].
+
+[examples]: https://github.com/mdub/clamp/tree/master/examples
+
 Declaring options
 -----------------
 
@@ -243,7 +249,7 @@ 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.
+Options are inheritable, so any options declared for a command are supported by it's sub-classes (e.g. those created using the block form of `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.
 

data/examples/admin

@@ -4,7 +4,7 @@
 
 require "clamp"
 
-class AdminCommand < Clamp::Command
+Clamp do
 
   option "--timeout", "SECONDS", "connection timeout", :default => 5, :environment_variable => "MYAPP_TIMEOUT" do |x|
     Integer(x)
@@ -18,5 +18,3 @@ class AdminCommand < Clamp::Command
   end
 
 end
-
-AdminCommand.run

data/examples/flipflop

@@ -5,7 +5,7 @@
 require "clamp"
 require "clamp/version"
 
-class FlipFlop < Clamp::Command
+Clamp do
 
   option ["--version", "-v"], :flag, "Show version" do
     puts "Powered by Clamp-#{Clamp::VERSION}"
@@ -27,5 +27,3 @@ class FlipFlop < Clamp::Command
   end
 
 end
-
-FlipFlop.run

data/examples/fubar

@@ -4,7 +4,7 @@
 
 require "clamp"
 
-class Fubar < Clamp::Command
+Clamp do
 
   subcommand "foo", "Foo!" do
 
@@ -19,5 +19,3 @@ class Fubar < Clamp::Command
   end
 
 end
-
-Fubar.run

data/examples/scoop

@@ -0,0 +1,17 @@
+#! /usr/bin/env ruby
+
+# An example of multi-valued options
+
+require "clamp"
+
+Clamp do
+
+  option ["-f", "--flavour"], "FLAVOUR", "flavour",
+    :multivalued => true, :default => ['chocolate'],
+    :attribute_name => :flavours
+
+  def execute
+    puts "one #{flavours.join(' and ')} ice-cream"
+  end
+
+end

data/examples/speak

@@ -4,9 +4,9 @@
 
 require "clamp"
 
-class SpeakCommand < Clamp::Command
+Clamp do
 
-  self.description = %{
+  banner %{
     Say something.
   }
 
@@ -29,5 +29,3 @@ class SpeakCommand < Clamp::Command
   end
 
 end
-
-SpeakCommand.run

data/lib/clamp.rb

@@ -1,3 +1,7 @@
 require 'clamp/version'
 
 require 'clamp/command'
+
+def Clamp(&block)
+  Class.new(Clamp::Command, &block).run
+end

data/lib/clamp/attribute/declaration.rb

@@ -0,0 +1,49 @@
+module Clamp
+  module Attribute
+
+    module Declaration
+
+      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
+          if attribute.multivalued?
+            unless instance_variable_defined?(attribute.ivar_name)
+              instance_variable_set(attribute.ivar_name, [])
+            end
+            instance_variable_get(attribute.ivar_name) << value
+          else
+            instance_variable_set(attribute.ivar_name, value)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/clamp/attribute/definition.rb

@@ -0,0 +1,82 @@
+module Clamp
+  module Attribute
+
+    class Definition
+
+      def initialize(options)
+        if options.has_key?(:attribute_name)
+          @attribute_name = options[:attribute_name].to_s
+        end
+        if options.has_key?(:default)
+          @default_value = options[:default]
+        end
+        if options.has_key?(:environment_variable)
+          @environment_variable = options[:environment_variable]
+        end
+      end
+
+      attr_reader :description, :environment_variable
+
+      def help_rhs
+        description + default_description
+      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
+        if multivalued?
+          "append_to_#{attribute_name}"
+        else
+          "#{attribute_name}="
+        end
+      end
+
+      def multivalued?
+        @multivalued
+      end
+
+      def required?
+        @required
+      end
+
+      def attribute_name
+        @attribute_name ||= infer_attribute_name
+      end
+
+      def default_value
+        if defined?(@default_value)
+          @default_value
+        elsif multivalued?
+          []
+        end
+      end
+
+      private
+
+      def default_description
+        default_sources = [
+          ("$#{@environment_variable}" if defined?(@environment_variable)),
+          (@default_value.inspect if defined?(@default_value))
+        ].compact
+        return "" if default_sources.empty?
+        " (default: " + default_sources.join(", or ") + ")"
+      end
+
+    end
+
+  end
+end

data/lib/clamp/command.rb

@@ -24,9 +24,12 @@ module Clamp
     # @param [String] invocation_path the path used to invoke the command
     # @param [Hash] context additional data the command may need
     #
-    def initialize(invocation_path, context = {})
+    def initialize(invocation_path, context = {}, parent_attribute_values = {})
       @invocation_path = invocation_path
       @context = context
+      parent_attribute_values.each do |attribute, value|
+        instance_variable_set(attribute.ivar_name, value)
+      end
     end
 
     # @return [String] the path used to invoke this command

data/lib/clamp/errors.rb

@@ -1,6 +1,9 @@
 module Clamp
-  
-  class Error < StandardError
+
+  class DeclarationError < StandardError
+  end
+
+  class RuntimeError < StandardError
 
     def initialize(message, command)
       super(message)
@@ -12,10 +15,10 @@ module Clamp
   end
 
   # raise to signal incorrect command usage
-  class UsageError < Error; end
+  class UsageError < RuntimeError; end
 
   # raise to request usage help
-  class HelpWanted < Error
+  class HelpWanted < RuntimeError
 
     def initialize(command)
       super("I need help", command)

data/lib/clamp/help.rb

@@ -20,15 +20,15 @@ module Clamp
       @description.strip!
     end
 
+    def banner(description)
+      self.description = description
+    end
+
     attr_reader :description
 
     def derived_usage_description
       parts = ["[OPTIONS]"]
       parts += parameters.map { |a| a.name }
-      if has_subcommands?
-        parts << "SUBCOMMAND"
-        parts << "[ARGS] ..."
-      end
       parts.join(" ")
     end
 

data/lib/clamp/option/declaration.rb

@@ -1,17 +1,19 @@
-require 'clamp/attribute_declaration'
-require 'clamp/option'
+require 'clamp/attribute/declaration'
+require 'clamp/option/definition'
 
 module Clamp
-  class Option
+  module Option
 
     module Declaration
 
-      include Clamp::AttributeDeclaration
+      include Clamp::Attribute::Declaration
 
       def option(switches, type, description, opts = {}, &block)
-        option = Clamp::Option.new(switches, type, description, opts)
-        declared_options << option
-        define_accessors_for(option, &block)
+        Option::Definition.new(switches, type, description, opts).tap do |option|
+          declared_options << option
+          block ||= option.default_conversion_block
+          define_accessors_for(option, &block)
+        end
       end
 
       def find_option(switch)

data/lib/clamp/option/definition.rb

@@ -0,0 +1,94 @@
+require 'clamp/attribute/definition'
+require 'clamp/truthy'
+
+module Clamp
+  module Option
+
+    class Definition < Attribute::Definition
+
+      def initialize(switches, type, description, options = {})
+        @switches = Array(switches)
+        @type = type
+        @description = description
+        super(options)
+        @multivalued = options[:multivalued]
+        if options.has_key?(:required)
+          @required = options[:required]
+          # Do some light validation for conflicting settings.
+          if options.has_key?(:default)
+            raise ArgumentError, "Specifying a :default value also :required doesn't make sense"
+          end
+          if type == :flag
+            raise ArgumentError, "A required flag (boolean) doesn't make sense."
+          end
+        end
+      end
+
+      attr_reader :switches, :type
+
+      def long_switch
+        switches.find { |switch| switch =~ /^--/ }
+      end
+
+      def handles?(switch)
+        recognised_switches.member?(switch)
+      end
+
+      def flag?
+        @type == :flag
+      end
+
+      def flag_value(switch)
+        !(switch =~ /^--no-(.*)/ && switches.member?("--\[no-\]#{$1}"))
+      end
+
+      def read_method
+        if flag?
+          super + "?"
+        else
+          super
+        end
+      end
+
+      def extract_value(switch, arguments)
+        if flag?
+          flag_value(switch)
+        else
+          arguments.shift
+        end
+      end
+
+      def default_conversion_block
+        if flag?
+          Clamp.method(:truthy?)
+        end
+      end
+
+      def help_lhs
+        lhs = switches.join(", ")
+        lhs += " " + type unless flag?
+        lhs
+      end
+
+      private
+
+      def recognised_switches
+        switches.map do |switch|
+          if switch =~ /^--\[no-\](.*)/
+            ["--#{$1}", "--no-#{$1}"]
+          else
+            switch
+          end
+        end.flatten
+      end
+
+      def infer_attribute_name
+        inferred_name = long_switch.sub(/^--(\[no-\])?/, '').tr('-', '_')
+        inferred_name += "_list" if multivalued?
+        inferred_name
+      end
+
+    end
+
+  end
+end