clamp 0.6.0 → 0.6.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YzQ1YTM1YTRmM2Q2ZDRiMDEzY2M1YzBmM2Y5YjM4ZDlhZTYzNWFmZA==
+    NGJhZjcxZjg4MjljZTZhODNlM2M0NzFhNGRmODFlMGQ1ZDdjYzFhNQ==
   data.tar.gz: !binary |-
-    MDMzN2JhYTAxYjYwNmZhZjhlMzEwZDJmMTM0MTBhOWVhZjFkMjIxYQ==
+    NGVhZDMyYzU2ODk5MjY0NjY0YWZhYjRlODhkYzZhZGQ5MzlhZTUzMA==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NzA4ZmI2ZmNjMmE4YzZlZDY4ZjUwZTVlMDIyYTJjZmQ5NDkxNDZkMjI0NDhi
-    M2E3NmUwZDE3NTUxNWViM2FmMDc5ZDc3NzRiNjQ2YjY1NjlkMzgwMjM0NTgy
-    NWM0ODJmODdkYTY2MTc3ZDBiZDdhZTU5N2Q1OTRjYTcyYzNlYWM=
+    ZTJhZjg3NWJmYmNmNjE2ODZmMmRhOWFmNWUwNWVhNmFlMmMwZGFhMjZlZjU4
+    NmM5ODRmNjIxNjU3MzRhNjAwY2YyZDk1YzcyNTU1OGUwMGQ1M2YxZGYwMmZl
+    MWI3OTc0MWRlYjkxZjA2N2ZkNmEyNmE1OWNjMjRjN2QwNjczNDU=
   data.tar.gz: !binary |-
-    ZDU4Yzg2ODViNjBlOWRmY2Y3OTZjNGEyYzZhMmFjZDZiYjc4MWI5ZjY5NTZl
-    OWZjN2I4YTEwYjE0ZTZiMTFkMmRmYjk3OTE3ODMyNzhjYWY4MDc1NjZiYTE4
-    OGNkZmYxODFiYjlhMzM5ZThiOTQ0M2U0NDllZDcyNWQyMjA0ZDk=
+    OTE5Y2Y0YWIyMzJmZmY5MGJjYzJiNTYyOGQ4NjQ4MjljNjRkM2M5YWE4NzU0
+    OTE0NzY0MzkzNzBiNGY4YmMwYWFmNzhkZmZmOWJkZjEwMzExYzVlMzFjZmI5
+    M2I2Y2MxM2Y5YzhiYmY4YjczMjVmY2Q5MzgxMmI0ZjQwNWQzN2I=

data/CHANGES.md

@@ -1,10 +1,11 @@
 # Changelog
 
-## 0.6.0 (2013-04-??)
+## 0.6.0 (2013-04-28)
 
 * Introduce "banner" to describe a command (replacing "self.description=").
+* Introduce "Clamp do ... end" syntax sugar.
 * 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=".
-
+* default_subcommand must be specified before any subcommands.

data/README.md

@@ -17,7 +17,30 @@ Yeah, sorry.  There are a bunch of existing command-line parsing libraries out t
 Quick Start
 -----------
 
-Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They look something like this:
+A typical Clamp script looks like this:
+
+    require 'clamp'
+
+    Clamp do
+
+      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
+
+Internally, Clamp models a command as a Ruby class (a subclass of `Clamp::Command`), and a command execution as an instance of that class.  The example above is really just syntax-sugar for:
 
     require 'clamp'
 
@@ -42,9 +65,7 @@ Clamp models a command as a Ruby class; a subclass of `Clamp::Command`.  They lo
 
     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`).
+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.
 
 There are more examples demonstrating various features of Clamp [on Github][examples].
 
@@ -63,7 +84,7 @@ 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.
+It works a little like `attr_accessor`, defining reader and writer methods on the command class.  The attribute name is inferred 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!"
@@ -102,6 +123,14 @@ Although 'required option' is a an oxymoron, Clamp lets you mark an option as re
 
 Note that it makes no sense to mark a `:flag` option, or one with a `:default`, as `:required`.
 
+### Multivalued options
+
+Declaring an option "`:multivalued`" allows it to be specified multiple times on the command line.
+
+    option "--format", "FORMAT", "output format", :multivalued => true
+
+The underlying attribute becomes an Array, and the suffix "`_list`" is appended to the default attribute name.  In this case, an attribute called "`format_list`" would be generated (unless you override the default by specifying an `:attribute_name`).
+
 Declaring parameters
 --------------------
 
@@ -122,13 +151,14 @@ Wrapping a parameter name in square brackets indicates that it's optional, e.g.
 
     parameter "[TARGET_DIR]", "target directory"
 
-### Greedy parameters
+### Multivalued (aka "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"
+    parameter "FILE ...", "input files", :attribute_name => :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.
+
+Like multivalued options, greedy parameters are backed by an Array attribute (named with a "`_list`" suffix, by default).
 
 Parsing and validation of options and parameters
 ------------------------------------------------
@@ -137,11 +167,12 @@ When you `#run` a command, it will first attempt to `#parse` command-line argume
 
 Clamp will verify that all required (ie. non-optional) parameters are present, and signal a error if they aren't.
 
-### Validation block
+### Validation
 
 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.
+called with the raw string argument, and is expected to validate it.  The value returned by the block will be assigned to the underlying attribute, so it's also a good place to coerce the String to a different type, if appropriate.  
+
+For example:
 
     option "--port", "PORT", "port to listen on" do |s|
       Integer(s)
@@ -152,6 +183,17 @@ If the block raises an ArgumentError, Clamp will catch it, and report that the v
     !!!plain
     ERROR: option '--port': invalid value for Integer: "blah"
 
+For multivalued options and parameters, the validation block will be called for each value specified.
+
+More complex validation, e.g. those involving multiple options/parameters, should be performed within the `#execute` method.  Use `#signal_usage_error` to tell the user what they did wrong, e.g.
+
+    def execute
+      if port < 1024 && user != 'root'
+        signal_usage_error "port restricted for non-root users"
+      end
+      # ... carry on ...
+    end
+
 ### 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.
@@ -199,7 +241,7 @@ Subcommand support helps you wrap a number of related commands into a single scr
 
 Unsuprisingly, subcommands are declared using the `subcommand` method. e.g.
 
-    class MainCommand < Clamp::Command
+    Clamp do
 
       subcommand "init", "Initialize the repository" do
 
@@ -231,7 +273,7 @@ Clamp generates an anonymous subclass of the current class, to represent the sub
 
 You can set a default subcommand, at the class level, as follows:
 
-    class MainCommand < Clamp::Command
+    Clamp do
 
       self.default_subcommand = "status"
 

data/lib/clamp/attribute/declaration.rb

@@ -13,11 +13,7 @@ module Clamp
 
       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
+          attribute.of(self)._read
         end
       end
 
@@ -32,14 +28,7 @@ module Clamp
           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
+          attribute.of(self)._write(value)
         end
       end
 

data/lib/clamp/attribute/definition.rb

@@ -1,3 +1,5 @@
+require 'clamp/attribute/instance'
+
 module Clamp
   module Attribute
 
@@ -65,6 +67,10 @@ module Clamp
         end
       end
 
+      def of(command)
+        Attribute::Instance.new(self, command)
+      end
+
       private
 
       def default_description

data/lib/clamp/attribute/instance.rb

@@ -0,0 +1,76 @@
+module Clamp
+  module Attribute
+
+    # Represents an option/parameter of a Clamp::Command instance.
+    #
+    class Instance
+
+      def initialize(attribute, command)
+        @attribute = attribute
+        @command = command
+      end
+
+      attr_reader :attribute, :command
+
+      def defined?
+        command.instance_variable_defined?(attribute.ivar_name)
+      end
+
+      # get value directly
+      def get
+        command.instance_variable_get(attribute.ivar_name)
+      end
+
+      # set value directly
+      def set(value)
+        command.instance_variable_set(attribute.ivar_name, value)
+      end
+
+      def default
+        command.send(attribute.default_method)
+      end
+
+      # default implementation of read_method
+      def _read
+        if self.defined?
+          get
+        else
+          default
+        end
+      end
+
+      # default implementation of write_method
+      def _write(value)
+        if attribute.multivalued?
+          current_values = get || []
+          set(current_values + [value])
+        else
+          set(value)
+        end
+      end
+
+      def read
+        command.send(attribute.read_method)
+      end
+
+      def write(value)
+        command.send(attribute.write_method, value)
+      end
+
+      def default_from_environment
+        return if self.defined?
+        return if attribute.environment_variable.nil?
+        return unless ENV.has_key?(attribute.environment_variable)
+        # Set the parameter value if it's environment variable is present
+        value = ENV[attribute.environment_variable]
+        begin
+          write(value)
+        rescue ArgumentError => e
+          command.send(:signal_usage_error, "$#{attribute.environment_variable}: #{e.message}")
+        end
+      end
+
+    end
+
+  end
+end

data/lib/clamp/command.rb

@@ -28,7 +28,7 @@ module Clamp
       @invocation_path = invocation_path
       @context = context
       parent_attribute_values.each do |attribute, value|
-        instance_variable_set(attribute.ivar_name, value)
+        attribute.of(self).set(value)
       end
     end
 
@@ -49,9 +49,7 @@ module Clamp
     #
     def parse(arguments)
       @remaining_arguments = arguments.dup
-      parse_environment_options
       parse_options
-      parse_environment_parameters
       parse_parameters
       parse_subcommand
       handle_remaining_arguments

data/lib/clamp/option/parsing.rb

@@ -6,6 +6,7 @@ module Clamp
       protected
 
       def parse_options
+
         while remaining_arguments.first =~ /\A-/
 
           switch = remaining_arguments.shift
@@ -28,13 +29,18 @@ module Clamp
           value = option.extract_value(switch, remaining_arguments)
 
           begin
-            send(option.write_method, value)
+            option.of(self).write(value)
           rescue ArgumentError => e
             signal_usage_error "option '#{switch}': #{e.message}"
           end
 
         end
 
+        # Fill in gap from environment
+        self.class.recognised_options.each do |option|
+          option.of(self).default_from_environment
+        end
+
         # Verify that all required options are present
         self.class.recognised_options.each do |option|
           # If this option is required and the value is nil, there's an error.
@@ -49,15 +55,6 @@ module Clamp
         end
       end
 
-      def parse_environment_options
-        self.class.recognised_options.each do |option|
-          next if option.environment_variable.nil?
-          next unless ENV.has_key?(option.environment_variable)
-          value = ENV[option.environment_variable]
-          send(option.write_method, value)
-        end
-      end
-
       private
 
       def find_option(switch)

data/lib/clamp/parameter/parsing.rb

@@ -10,23 +10,15 @@ module Clamp
         self.class.parameters.each do |parameter|
           begin
             parameter.consume(remaining_arguments).each do |value|
-              send(parameter.write_method, value)
+              parameter.of(self).write(value)
             end
           rescue ArgumentError => e
             signal_usage_error "parameter '#{parameter.name}': #{e.message}"
           end
         end
 
-      end
-
-      def parse_environment_parameters
-
         self.class.parameters.each do |parameter|
-          next if parameter.environment_variable.nil?
-          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.write_method, value)
+          parameter.of(self).default_from_environment
         end
 
       end

data/lib/clamp/subcommand/declaration.rb

@@ -39,6 +39,10 @@ module Clamp
         parameters.take_while { |p| p != @subcommand_parameter }
       end
 
+      def inheritable_attributes
+        recognised_options + parameters_before_subcommand
+      end
+
       def default_subcommand=(name)
         if has_subcommands?
           raise Clamp::DeclarationError, "default_subcommand must be defined before subcommands"

data/lib/clamp/subcommand/execution.rb

@@ -16,18 +16,14 @@ module Clamp
       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)
+        self.class.inheritable_attributes.each do |attribute|
+          if attribute.of(self).defined?
+            parent_attribute_values[attribute] = attribute.of(self).get
           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

data/lib/clamp/version.rb

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

data/spec/clamp/command_spec.rb

@@ -283,6 +283,11 @@ describe Clamp::Command do
     before do
       command.class.option ["-f", "--flavour"], "FLAVOUR", "Flavour of the month"
       command.class.option ["-c", "--color"], "COLOR", "Preferred hue"
+      command.class.option ["--scoops"], "N", "Number of scoops",
+          :default => 1,
+          :environment_variable => "DEFAULT_SCOOPS" do |arg|
+        Integer(arg)
+      end
       command.class.option ["-n", "--[no-]nuts"], :flag, "Nuts (or not)\nMay include nuts"
       command.class.parameter "[ARG] ...", "extra arguments", :attribute_name => :arguments
     end
@@ -441,24 +446,23 @@ describe Clamp::Command do
 
       end
 
-      describe "when option-writer raises an ArgumentError" do
+      describe "when a bad option value is specified on the command-line" do
 
-        before do
-          command.class.class_eval do
+        it "signals a UsageError" do
+          lambda do
+            command.parse(%w(--scoops reginald))
+          end.should raise_error(Clamp::UsageError, /^option '--scoops': invalid value for Integer/)
+        end
 
-            def color=(c)
-              unless c == "black"
-                raise ArgumentError, "sorry, we're out of #{c}"
-              end
-            end
+      end
 
-          end
-        end
+      describe "when a bad option value is specified in the environment" do
 
-        it "re-raises it as a UsageError" do
+        it "signals a UsageError" do
+          ENV["DEFAULT_SCOOPS"] = "marjorie"
           lambda do
-            command.parse(%w(--color red))
-          end.should raise_error(Clamp::UsageError, /^option '--color': sorry, we're out of red/)
+            command.parse([])
+          end.should raise_error(Clamp::UsageError, /^\$DEFAULT_SCOOPS: invalid value for Integer/)
         end
 
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-28 00:00:00.000000000 Z
+date: 2013-05-07 00:00:00.000000000 Z
 dependencies: []
 description: ! "Clamp provides an object-model for command-line utilities.  \nIt handles
   parsing of command-line options, and generation of usage help.\n"
@@ -35,6 +35,7 @@ files:
 - lib/clamp.rb
 - lib/clamp/attribute/declaration.rb
 - lib/clamp/attribute/definition.rb
+- lib/clamp/attribute/instance.rb
 - lib/clamp/command.rb
 - lib/clamp/errors.rb
 - lib/clamp/help.rb