clamp 0.5.1 → 0.6.0

data/lib/clamp/option/parsing.rb

@@ -1,26 +1,8 @@
 module Clamp
-  class Option
+  module Option
 
     module Parsing
 
-      # For :flag options with environment variables attached, this is a list
-      # of possible values that are accepted as 'true'
-      #
-      # Example:
-      #
-      #   option "--foo", :flag, "Use foo", :environment_variable => "FOO"
-      #
-      # All of these will set 'foo' to true:
-      #
-      #   FOO=1 ./myprogram
-      #   FOO=true ./myprogram
-      #   FOO=yes ./myprogram
-      #   FOO=on ./myprogram
-      #   FOO=enable ./myprogram
-      #
-      # See {Clamp::Command.option} for more information.
-      TRUTHY_ENVIRONMENT_VALUES = %w(1 yes enable on true)
-
       protected
 
       def parse_options
@@ -46,7 +28,7 @@ module Clamp
           value = option.extract_value(switch, remaining_arguments)
 
           begin
-            send("#{option.attribute_name}=", value)
+            send(option.write_method, value)
           rescue ArgumentError => e
             signal_usage_error "option '#{switch}': #{e.message}"
           end
@@ -72,12 +54,7 @@ module Clamp
           next if option.environment_variable.nil?
           next unless ENV.has_key?(option.environment_variable)
           value = ENV[option.environment_variable]
-          if option.flag?
-            # Set true if the environment value is truthy.
-            send("#{option.attribute_name}=", TRUTHY_ENVIRONMENT_VALUES.include?(value))
-          else
-            send("#{option.attribute_name}=", value)
-          end
+          send(option.write_method, value)
         end
       end
 

data/lib/clamp/parameter/declaration.rb

@@ -1,12 +1,12 @@
-require 'clamp/attribute_declaration'
-require 'clamp/parameter'
+require 'clamp/attribute/declaration'
+require 'clamp/parameter/definition'
 
 module Clamp
-  class Parameter
+  module Parameter
 
     module Declaration
 
-      include Clamp::AttributeDeclaration
+      include Clamp::Attribute::Declaration
 
       def parameters
         @parameters ||= []
@@ -17,9 +17,10 @@ module Clamp
       end
 
       def parameter(name, description, options = {}, &block)
-        parameter = Parameter.new(name, description, options)
-        parameters << parameter
-        define_accessors_for(parameter, &block)
+        Parameter::Definition.new(name, description, options).tap do |parameter|
+          parameters << parameter
+          define_accessors_for(parameter, &block)
+        end
       end
 
     end

data/lib/clamp/parameter/definition.rb

@@ -0,0 +1,48 @@
+require 'clamp/attribute/definition'
+
+module Clamp
+  module Parameter
+
+    class Definition < Attribute::Definition
+
+      def initialize(name, description, options = {})
+        @name = name
+        @description = description
+        super(options)
+        @multivalued = (@name =~ ELLIPSIS_SUFFIX)
+        @required = options.fetch(:required) do
+          (@name !~ OPTIONAL)
+        end
+      end
+
+      attr_reader :name
+
+      def help_lhs
+        name
+      end
+
+      def consume(arguments)
+        raise ArgumentError, "no value provided" if required? && arguments.empty?
+        arguments.shift(multivalued? ? arguments.length : 1)
+      end
+
+      private
+
+      ELLIPSIS_SUFFIX = / \.\.\.$/
+      OPTIONAL = /^\[(.*)\]/
+
+      VALID_ATTRIBUTE_NAME = /^[a-z0-9_]+$/
+
+      def infer_attribute_name
+        inferred_name = name.downcase.tr('-', '_').sub(ELLIPSIS_SUFFIX, '').sub(OPTIONAL) { $1 }
+        unless inferred_name =~ VALID_ATTRIBUTE_NAME
+          raise "cannot infer attribute_name from #{name.inspect}"
+        end
+        inferred_name += "_list" if multivalued?
+        inferred_name
+      end
+
+    end
+
+  end
+end

data/lib/clamp/parameter/parsing.rb

@@ -1,5 +1,5 @@
 module Clamp
-  class Parameter
+  module Parameter
 
     module Parsing
 
@@ -9,8 +9,9 @@ module Clamp
 
         self.class.parameters.each do |parameter|
           begin
-            value = parameter.consume(remaining_arguments)
-            send("#{parameter.attribute_name}=", value) unless value.nil?
+            parameter.consume(remaining_arguments).each do |value|
+              send(parameter.write_method, value)
+            end
           rescue ArgumentError => e
             signal_usage_error "parameter '#{parameter.name}': #{e.message}"
           end
@@ -25,7 +26,7 @@ module Clamp
           next unless ENV.has_key?(parameter.environment_variable)
           # Set the parameter value if it's environment variable is present
           value = ENV[parameter.environment_variable]
-          send("#{parameter.attribute_name}=", value)
+          send(parameter.write_method, value)
         end
 
       end

data/lib/clamp/subcommand/declaration.rb

@@ -1,7 +1,8 @@
-require 'clamp/subcommand'
+require 'clamp/errors'
+require 'clamp/subcommand/definition'
 
 module Clamp
-  class Subcommand
+  module Subcommand
 
     module Declaration
 
@@ -10,11 +11,20 @@ module Clamp
       end
 
       def subcommand(name, description, subcommand_class = self, &block)
+        unless has_subcommands?
+          @subcommand_parameter = if @default_subcommand
+            parameter "[SUBCOMMAND]", "subcommand", :attribute_name => :subcommand_name, :default => @default_subcommand
+          else
+            parameter "SUBCOMMAND", "subcommand", :attribute_name => :subcommand_name, :required => false
+          end
+          remove_method :default_subcommand_name
+          parameter "[ARG] ...", "subcommand arguments", :attribute_name => :subcommand_arguments
+        end
         if block
           # generate a anonymous sub-class
           subcommand_class = Class.new(subcommand_class, &block)
         end
-        recognised_subcommands << Subcommand.new(name, description, subcommand_class)
+        recognised_subcommands << Subcommand::Definition.new(name, description, subcommand_class)
       end
 
       def has_subcommands?
@@ -25,16 +35,25 @@ module Clamp
         recognised_subcommands.find { |sc| sc.is_called?(name) }
       end
 
-      attr_writer :default_subcommand
+      def parameters_before_subcommand
+        parameters.take_while { |p| p != @subcommand_parameter }
+      end
+
+      def default_subcommand=(name)
+        if has_subcommands?
+          raise Clamp::DeclarationError, "default_subcommand must be defined before subcommands"
+        end
+        @default_subcommand = name
+      end
 
       def default_subcommand(*args, &block)
         if args.empty?
-          @default_subcommand ||= nil
+          @default_subcommand
         else
           $stderr.puts "WARNING: Clamp default_subcommand syntax has changed; check the README."
           $stderr.puts "  (from #{caller.first})"
-          subcommand(*args, &block)
           self.default_subcommand = args.first
+          subcommand(*args, &block)
         end
       end
 

data/lib/clamp/subcommand/definition.rb

@@ -0,0 +1,25 @@
+module Clamp
+  module Subcommand
+
+    class Definition < Struct.new(:name, :description, :subcommand_class)
+
+      def initialize(names, description, subcommand_class)
+        @names = Array(names)
+        @description = description
+        @subcommand_class = subcommand_class
+      end
+
+      attr_reader :names, :description, :subcommand_class
+
+      def is_called?(name)
+        names.member?(name)
+      end
+
+      def help
+        [names.join(", "), description]
+      end
+
+    end
+
+  end
+end

data/lib/clamp/subcommand/execution.rb

@@ -1,5 +1,5 @@
 module Clamp
-  class Subcommand
+  module Subcommand
 
     module Execution
 
@@ -7,11 +7,30 @@ module Clamp
 
       def execute
         # delegate to subcommand
-        @subcommand.run(remaining_arguments)
+        subcommand = instatiate_subcommand(subcommand_name)
+        subcommand.run(subcommand_arguments)
       end
 
-      def handle_remaining_arguments
-        # no-op, because subcommand will handle them
+      private
+
+      def instatiate_subcommand(name)
+        subcommand_class = find_subcommand_class(name)
+        parent_attribute_values = {}
+        inheritable_attributes.each do |option|
+          if instance_variable_defined?(option.ivar_name)
+            parent_attribute_values[option] = instance_variable_get(option.ivar_name)
+          end
+        end
+        subcommand_class.new("#{invocation_path} #{name}", context, parent_attribute_values)
+      end
+
+      def inheritable_attributes
+        self.class.recognised_options + self.class.parameters_before_subcommand
+      end
+
+      def find_subcommand_class(name)
+        subcommand_def = self.class.find_subcommand(name) || signal_usage_error("No such sub-command '#{name}'")
+        subcommand_def.subcommand_class
       end
 
     end

data/lib/clamp/subcommand/parsing.rb

@@ -1,7 +1,7 @@
 require 'clamp/subcommand/execution'
 
 module Clamp
-  class Subcommand
+  module Subcommand
 
     module Parsing
 
@@ -9,31 +9,13 @@ module Clamp
 
       def parse_subcommand
         return false unless self.class.has_subcommands?
-        subcommand_name = parse_subcommand_name
-        @subcommand = instatiate_subcommand(subcommand_name)
         self.extend(Subcommand::Execution)
       end
 
       private
 
-      def parse_subcommand_name
-        remaining_arguments.shift || self.class.default_subcommand || request_help
-      end
-
-      def find_subcommand(name)
-        self.class.find_subcommand(name) ||
-        signal_usage_error("No such sub-command '#{name}'")
-      end
-
-      def instatiate_subcommand(name)
-        subcommand_class = find_subcommand(name).subcommand_class
-        subcommand = subcommand_class.new("#{invocation_path} #{name}", context)
-        self.class.recognised_options.each do |option|
-          if instance_variable_defined?(option.ivar_name)
-            subcommand.instance_variable_set(option.ivar_name, instance_variable_get(option.ivar_name))
-          end
-        end
-        subcommand
+      def default_subcommand_name
+        self.class.default_subcommand || request_help
       end
 
     end

data/lib/clamp/truthy.rb

@@ -0,0 +1,9 @@
+module Clamp
+
+  TRUTHY_VALUES = %w(1 yes enable on true)
+
+  def self.truthy?(arg)
+    TRUTHY_VALUES.include?(arg.to_s.downcase)
+  end
+
+end

data/lib/clamp/version.rb

@@ -1,3 +1,3 @@
 module Clamp
-  VERSION = "0.5.1".freeze
+  VERSION = "0.6.0".freeze
 end

data/spec/clamp/command_group_spec.rb

@@ -50,7 +50,7 @@ describe Clamp::Command do
     describe "#help" do
 
       it "shows subcommand parameters in usage" do
-        command.help.should include("flipflop [OPTIONS] SUBCOMMAND [ARGS] ...")
+        command.help.should include("flipflop [OPTIONS] SUBCOMMAND [ARG] ...")
       end
 
       it "lists subcommands" do
@@ -132,6 +132,8 @@ describe Clamp::Command do
 
     given_command "admin" do
 
+      self.default_subcommand = "status"
+
       subcommand "status", "Show status" do
 
         def execute
@@ -140,8 +142,6 @@ describe Clamp::Command do
 
       end
 
-      self.default_subcommand = "status"
-
     end
 
     context "executed with no subcommand" do
@@ -180,6 +180,53 @@ describe Clamp::Command do
 
   end
 
+  describe "declaring a default subcommand after subcommands" do
+
+    it "is not supported" do
+
+      lambda do
+        Class.new(Clamp::Command) do
+
+          subcommand "status", "Show status" do
+
+            def execute
+              puts "All good!"
+            end
+
+          end
+
+          self.default_subcommand = "status"
+
+        end
+      end.should raise_error(/default_subcommand must be defined before subcommands/)
+
+    end
+
+  end
+
+  describe "with subcommands, declared after a parameter" do
+
+    given_command "with" do
+
+      parameter "THING", "the thing"
+
+      subcommand "spit", "spit it" do
+        def execute
+          puts "spat the #{thing}"
+        end
+      end
+
+    end
+
+    it "allows the parameter to be specified first" do
+
+      command.run(["dummy", "spit"])
+      stdout.strip.should == "spat the dummy"
+
+    end
+
+  end
+
   describe "each subcommand" do
 
     let(:command_class) do

data/spec/clamp/command_spec.rb

@@ -111,7 +111,24 @@ describe Clamp::Command do
 
     end
 
-    describe "with :environment_variable value" do
+    describe "with :multivalued" do
+
+      before do
+        command.class.option "--flavour", "FLAVOUR", "flavour(s)", :multivalued => true, :attribute_name => :flavours
+      end
+
+      it "defaults to empty array" do
+        command.flavours.should == []
+      end
+
+      it "supports multiple values" do
+        command.parse(%w(--flavour chocolate --flavour vanilla))
+        command.flavours.should == %w(chocolate vanilla)
+      end
+
+    end
+
+    describe "with :environment_variable" do
 
       before do
         command.class.option "--port", "PORT", "port to listen on", :default => 4321, :environment_variable => "PORT" do |value|
@@ -119,22 +136,39 @@ describe Clamp::Command do
         end
       end
 
-      it "should use the default if neither flag nor env var are present" do
-        ENV.delete("PORT")
-        command.parse([])
-        command.port.should == 4321
-      end
+      context "when no environment variable is present" do
+
+        before do
+          ENV.delete("PORT")
+        end
+
+        it "uses the default" do
+          command.parse([])
+          command.port.should == 4321
+        end
 
-      it "should use the env value if present (instead of default)" do
-        ENV["PORT"] = rand(10000).to_s
-        command.parse([])
-        command.port.should == ENV["PORT"].to_i
       end
 
-      it "should use the the flag value if present (instead of env)" do
-        ENV["PORT"] = "12345"
-        command.parse(%w(--port 1500))
-        command.port.should == 1500
+      context "when environment variable is present" do
+
+        before do
+          ENV["PORT"] = "12345"
+        end
+
+        it "uses the environment variable" do
+          command.parse([])
+          command.port.should == 12345
+        end
+
+        context "and a value is specified on the command-line" do
+
+          it "uses command-line value" do
+            command.parse(%w(--port 1500))
+            command.port.should == 1500
+          end
+
+        end
+
       end
 
       describe "#help" do
@@ -147,88 +181,83 @@ describe Clamp::Command do
 
     end
 
-    describe "with :environment_variable value on a :flag option" do
+    describe "with :environment_variable and type :flag" do
 
       before do
         command.class.option "--[no-]enable", :flag, "enable?", :default => false, :environment_variable => "ENABLE"
       end
 
-      it "should use the default if neither flag nor env var are present" do
-        command.parse([])
-        command.enable?.should == false
-      end
+      context "when no environment variable is present" do
 
-      Clamp::Option::Parsing::TRUTHY_ENVIRONMENT_VALUES.each do |value|
-        it "should use environment value '#{value}' to mean true" do
-          ENV["ENABLE"] = value
-          command.parse([])
-          command.enable?.should == true
+        before do
+          ENV.delete("ENABLE")
         end
-      end
-
-      # Make sure tests fail if ever the TRUTHY_ENVIRONMENT_VALUES loses a
-      # value. This is just a safety check to make sure maintainers update
-      # any relevant docs and aware that they could be breaking compatibility.
-      it "should accept only these values as 'truthy' environment values: 1, yes, enable, on, true" do
-        Clamp::Option::Parsing::TRUTHY_ENVIRONMENT_VALUES.should == %w(1 yes enable on true)
-      end
 
-      it "should use an env value other than truthy ones to mean false" do
-        [nil, "0", "no", "whatever"].each do |val|
-          ENV["ENABLE"] = val
+        it "uses the default" do
           command.parse([])
           command.enable?.should == false
         end
-      end
 
-      it "should use the the flag value if present (instead of env)" do
-        ENV["ENABLE"] = "1"
-        command.parse(%w(--no-enable))
-        command.enable?.should == false
       end
 
-    end
+      %w(1 yes enable on true).each do |truthy_value|
 
-    describe "with :required value" do
+        context "when environment variable is #{truthy_value.inspect}" do
 
-      before do
-        command.class.option "--port", "PORT", "port to listen on", :required => true
-      end
+          it "sets the flag" do
+            ENV["ENABLE"] = truthy_value
+            command.parse([])
+            command.enable?.should == true
+          end
+
+        end
 
-      it "should fail if a required option is not provided" do
-        expect { command.parse([]) }.to raise_error(Clamp::UsageError)
       end
 
-      it "should succeed if a required option is provided" do
-        command.parse(["--port", "12345"])
+      %w(0 no disable off false).each do |falsey_value|
+
+        context "when environment variable is #{falsey_value.inspect}" do
+
+          it "clears the flag" do
+            ENV["ENABLE"] = falsey_value
+            command.parse([])
+            command.enable?.should == false
+          end
+
+        end
+
       end
 
     end
 
-    describe "with :required value with :env" do
+    describe "with :required" do
 
       before do
-        command.class.option "--port", "PORT", "port to listen on", :required => true, :environment_variable => "PORT"
+        command.class.option "--port", "PORT", "port to listen on", :required => true
       end
 
-      it "should fail if a required option is not provided" do
-        ENV.delete("PORT")
-        expect { command.parse([]) }.to raise_error(Clamp::UsageError)
-      end
+      context "when no value is provided" do
+
+        it "raises a UsageError" do
+          expect do
+            command.parse([])
+          end.to raise_error(Clamp::UsageError)
+        end
 
-      it "should succeed if a required option is provided via arguments" do
-        ENV.delete("PORT")
-        command.parse(["--port", "12345"])
       end
 
-      it "should succeed if a required option is provided via env" do
-        ENV["PORT"] = "12345"
-        command.parse([])
+      context "when a value is provided" do
+
+        it "does not raise an error" do
+          expect do
+            command.parse(["--port", "12345"])
+          end.not_to raise_error
+        end
+
       end
 
     end
 
-
     describe "with a block" do
 
       before do
@@ -764,11 +793,11 @@ describe Clamp::Command do
 
   end
 
-  describe "with a description" do
+  describe "with a banner" do
 
     given_command("punt") do
 
-      self.description = <<-EOF
+      banner <<-EOF
         Punt is an example command.  It doesn't do much, really.
 
         The prefix at the beginning of this description should be normalised
@@ -779,7 +808,7 @@ describe Clamp::Command do
 
     describe "#help" do
 
-      it "includes the description" do
+      it "includes the banner" do
         command.help.should =~ /^  Punt is an example command/
         command.help.should =~ /^  The prefix/
       end