clamp 0.6.1 → 0.6.2

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NGJhZjcxZjg4MjljZTZhODNlM2M0NzFhNGRmODFlMGQ1ZDdjYzFhNQ==
+    OTYzZmZkOGE1NTY4M2EyMjdlY2YzNGJmZjQzYTE4MDZiNzRiNGM2Nw==
   data.tar.gz: !binary |-
-    NGVhZDMyYzU2ODk5MjY0NjY0YWZhYjRlODhkYzZhZGQ5MzlhZTUzMA==
+    YzYxZjkyZjUxNmFkYWNiNjk2NDJhYmZiZGVkYmExNDY2MDY4YzUzYQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    ZTJhZjg3NWJmYmNmNjE2ODZmMmRhOWFmNWUwNWVhNmFlMmMwZGFhMjZlZjU4
-    NmM5ODRmNjIxNjU3MzRhNjAwY2YyZDk1YzcyNTU1OGUwMGQ1M2YxZGYwMmZl
-    MWI3OTc0MWRlYjkxZjA2N2ZkNmEyNmE1OWNjMjRjN2QwNjczNDU=
+    NWVhZTIwZDkxNDg4ZDc4NGRkYTFiODc3ZWJlNjU2MGUzMzlkZTBhNjVmNGFl
+    ZWQ2OTY1NjgxODdmZDliZjhlYzBhNDVlNTQyZTkwYjk3ZThmMTVmZDg2ZWEw
+    MWI4NTYzZWQyZmQyOGFkMDUyNzJkM2Q0MGZhYmIyYWYxMDc0Mjk=
   data.tar.gz: !binary |-
-    OTE5Y2Y0YWIyMzJmZmY5MGJjYzJiNTYyOGQ4NjQ4MjljNjRkM2M5YWE4NzU0
-    OTE0NzY0MzkzNzBiNGY4YmMwYWFmNzhkZmZmOWJkZjEwMzExYzVlMzFjZmI5
-    M2I2Y2MxM2Y5YzhiYmY4YjczMjVmY2Q5MzgxMmI0ZjQwNWQzN2I=
+    Yzk5NGY5OGMwNTY0MjMxNGM0ZGI1NzllYTE0NmRkMjZjYzE5OTlmMjMwYjZm
+    MWIyMjA3ODQxZDU0ODU3MTg2Y2ZkMjAwNjhiYzU2ZjJjNzFlZjk1Yjc3MTI3
+    NWYyYmM2NGRhYTZlMGI2NTgwYzc1MmFjOWE2YzMxMjY1Y2E4OWI=

data/CHANGES.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.2 (2013-11-06)
+
+* Refactoring around multi-valued attributes.
+* Allow injection of a custom help-builder.
+
+## 0.6.1 (2013-05-07)
+
+* Signal a usage error when an environment_variable fails validation.
+* Refactor setting, defaulting and inheritance of attributes.
+
 ## 0.6.0 (2013-04-28)
 
 * Introduce "banner" to describe a command (replacing "self.description=").

data/README.md

@@ -1,3 +1,4 @@
+
 Clamp  [![Build Status](https://secure.travis-ci.org/mdub/clamp.png?branch=master)](http://travis-ci.org/mdub/clamp)
 =====
 
@@ -8,62 +9,67 @@ It handles boring stuff like parsing the command-line, and generating help, so y
 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.
+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.  (Although, Clamp has a _lot_ in common with Ara T. Howard's [main.rb]. Had I been aware of that project at the time, I might not have written Clamp.)
 
 [optparse]: http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html
 [Thor]: http://github.com/wycats/thor
 [Clip]: http://clip.rubyforge.org/
+[main.rb]: https://github.com/ahoward/main
 
 Quick Start
 -----------
 
 A typical Clamp script looks like this:
 
-    require 'clamp'
-
-    Clamp do
+```ruby
+require 'clamp'
 
-      option "--loud", :flag, "say it loud"
-      option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
-        Integer(s)
-      end
+Clamp do
 
-      parameter "WORDS ...", "the thing to say", :attribute_name => :words
+  option "--loud", :flag, "say it loud"
+  option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
+    Integer(s)
+  end
 
-      def execute
-        the_truth = words.join(" ")
-        the_truth.upcase! if loud?
-        iterations.times do
-          puts the_truth
-        end
-      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
 
-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:
+end
+```
 
-    require 'clamp'
+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:
 
-    class SpeakCommand < Clamp::Command
+```ruby
+require 'clamp'
 
-      option "--loud", :flag, "say it loud"
-      option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
-        Integer(s)
-      end
+class SpeakCommand < Clamp::Command
 
-      parameter "WORDS ...", "the thing to say", :attribute_name => :words
+  option "--loud", :flag, "say it loud"
+  option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
+    Integer(s)
+  end
 
-      def execute
-        the_truth = words.join(" ")
-        the_truth.upcase! if loud?
-        iterations.times do
-          puts the_truth
-        end
-      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
+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.
 
@@ -82,36 +88,48 @@ Options are declared using the `option` method.  The three required arguments ar
 
 For example:
 
-    option "--flavour", "FLAVOUR", "ice-cream flavour"
+```ruby
+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 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!"
-    end
+```ruby
+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
+```ruby
+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"
+```ruby
+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"
+```ruby
+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)"
+```ruby
+option "--[no-]force", :flag, "be forceful (or not)"
+```
 
 Clamp will handle both "`--force`" and "`--no-force`" options, setting the value of "`#force?`" appropriately.
 
@@ -119,7 +137,9 @@ Clamp will handle both "`--force`" and "`--no-force`" options, setting the value
 
 Although 'required option' is a an oxymoron, Clamp lets you mark an option as required, and will verify that a value is provided:
 
-    option "--password", "PASSWORD", "the secret password", :required => true
+```ruby
+option "--password", "PASSWORD", "the secret password", :required => true
+```
 
 Note that it makes no sense to mark a `:flag` option, or one with a `:default`, as `:required`.
 
@@ -127,7 +147,9 @@ Note that it makes no sense to mark a `:flag` option, or one with a `:default`,
 
 Declaring an option "`:multivalued`" allows it to be specified multiple times on the command line.
 
-    option "--format", "FORMAT", "output format", :multivalued => true
+```ruby
+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`).
 
@@ -141,7 +163,9 @@ Positional parameters can be declared using `parameter`, specifying
 
 For example:
 
-    parameter "SRC", "source file"
+```ruby
+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.
 
@@ -149,14 +173,17 @@ Like options, parameters are implemented as attributes of the command, with the
 
 Wrapping a parameter name in square brackets indicates that it's optional, e.g.
 
-    parameter "[TARGET_DIR]", "target directory"
+```ruby
+parameter "[TARGET_DIR]", "target directory"
+```
 
 ### 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", :attribute_name => :files
-
+```ruby
+parameter "FILE ...", "input files", :attribute_name => :files
+```
 
 Like multivalued options, greedy parameters are backed by an Array attribute (named with a "`_list`" suffix, by default).
 
@@ -174,63 +201,77 @@ called with the raw string argument, and is expected to validate it.  The value
 
 For example:
 
-    option "--port", "PORT", "port to listen on" do |s|
-      Integer(s)
-    end
+```ruby
+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"
+```ruby
+!!!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
+```ruby
+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.
 
-    parameter "SERVER", "location of server"
+```ruby
+parameter "SERVER", "location of server"
 
-    def server=(server)
-      @server_address, @server_port = server.split(":")
-    end
+def server=(server)
+  @server_address, @server_port = server.split(":")
+end
+```
 
 ### Default values
 
 Default values can be specified for options, and optional parameters:
 
-    option "--flavour", "FLAVOUR", "ice-cream flavour", :default => "chocolate"
+```ruby
+option "--flavour", "FLAVOUR", "ice-cream flavour", :default => "chocolate"
 
-    parameter "[HOST]", "server host", :default => "localhost"
+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
+```ruby
+option "--http-port", "PORT", "web-server port", :default => 9000
 
-    option "--admin-port", "PORT", "admin port"
+option "--admin-port", "PORT", "admin port"
 
-    def default_admin_port
-       http_port + 1
-    end
+def default_admin_port
+   http_port + 1
+end
+```
 
 ### Environment variable support
 
 Options (and optional parameters) can also be associated with environment variables:
 
-    option "--port", "PORT", "the port to listen on", :environment_variable => "MYAPP_PORT" do |val|
-      val.to_i
-    end
+```ruby
+option "--port", "PORT", "the port to listen on", :environment_variable => "MYAPP_PORT" do |val|
+  val.to_i
+end
 
-    parameter "[HOST]", "server address", :environment_variable => "MYAPP_HOST"
+parameter "[HOST]", "server address", :environment_variable => "MYAPP_HOST"
+```
 
 Clamp will check the specified envariables in the absence of values supplied on the command line, before looking for a default value.
 
@@ -241,51 +282,57 @@ Subcommand support helps you wrap a number of related commands into a single scr
 
 Unsuprisingly, subcommands are declared using the `subcommand` method. e.g.
 
-    Clamp do
+```ruby
+Clamp do
 
-      subcommand "init", "Initialize the repository" do
+  subcommand "init", "Initialize the repository" do
 
-        def execute
-          # ...
-        end
+    def execute
+      # ...
+    end
 
-      end
+  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
+```ruby
+class MainCommand < Clamp::Command
 
-      subcommand "init", "Initialize the repository", InitCommand
+  subcommand "init", "Initialize the repository", InitCommand
 
-    end
+end
 
-    class InitCommand < Clamp::Command
+class InitCommand < Clamp::Command
 
-      def execute
-        # ...
-      end
+  def execute
+    # ...
+  end
 
-    end
+end
+```
 
 ### Default subcommand
 
 You can set a default subcommand, at the class level, as follows:
 
-    Clamp do
+```ruby
+Clamp do
 
-      self.default_subcommand = "status"
+  self.default_subcommand = "status"
 
-      subcommand "status", "Display current status" do
+  subcommand "status", "Display current status" do
 
-        def execute
-          # ...
-        end
+    def execute
+      # ...
+    end
 
-      end
+  end
 
-    end
+end
+```
 
 Then, if when no SUBCOMMAND argument is provided, the default will be selected.
 
@@ -300,17 +347,19 @@ 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 ...
+```sh
+$ speak --help
+Usage:
+    speak [OPTIONS] WORDS ...
 
-    Arguments:
-        WORDS ...                     the thing to say
+Arguments:
+    WORDS ...                     the thing to say
 
-    Options:
-        --loud                        say it loud
-        -n, --iterations N            say it N times (default: 1)
-        -h, --help                    print help
+Options:
+    --loud                        say it loud
+    -n, --iterations N            say it N times (default: 1)
+    -h, --help                    print help
+```
 
 License
 -------

data/lib/clamp/attribute/declaration.rb

@@ -8,7 +8,12 @@ module Clamp
       def define_accessors_for(attribute, &block)
         define_reader_for(attribute)
         define_default_for(attribute)
-        define_writer_for(attribute, &block)
+        if attribute.multivalued?
+          define_appender_for(attribute, &block)
+          define_multi_writer_for(attribute)
+        else
+          define_simple_writer_for(attribute, &block)
+        end
       end
 
       def define_reader_for(attribute)
@@ -23,12 +28,23 @@ module Clamp
         end
       end
 
-      def define_writer_for(attribute, &block)
+      def define_simple_writer_for(attribute, &block)
         define_method(attribute.write_method) do |value|
-          if block
-            value = instance_exec(value, &block)
-          end
-          attribute.of(self)._write(value)
+          value = instance_exec(value, &block) if block
+          attribute.of(self).set(value)
+        end
+      end
+
+      def define_appender_for(attribute, &block)
+        define_method(attribute.append_method) do |value|
+          value = instance_exec(value, &block) if block
+          attribute.of(self)._append(value)
+        end
+      end
+
+      def define_multi_writer_for(attribute)
+        define_method(attribute.write_method) do |values|
+          attribute.of(self)._replace(values)
         end
       end
 

data/lib/clamp/attribute/definition.rb

@@ -40,10 +40,12 @@ module Clamp
       end
 
       def write_method
+        "#{attribute_name}="
+      end
+
+      def append_method
         if multivalued?
           "append_to_#{attribute_name}"
-        else
-          "#{attribute_name}="
         end
       end
 

data/lib/clamp/attribute/instance.rb

@@ -39,22 +39,28 @@ module Clamp
         end
       end
 
-      # default implementation of write_method
-      def _write(value)
-        if attribute.multivalued?
-          current_values = get || []
-          set(current_values + [value])
-        else
-          set(value)
-        end
+      # default implementation of append_method
+      def _append(value)
+        current_values = get || []
+        set(current_values + [value])
+      end
+
+      # default implementation of write_method for multi-valued attributes
+      def _replace(values)
+        set([])
+        Array(values).each { |value| take(value) }
       end
 
       def read
         command.send(attribute.read_method)
       end
 
-      def write(value)
-        command.send(attribute.write_method, value)
+      def take(value)
+        if attribute.multivalued?
+          command.send(attribute.append_method, value)
+        else
+          command.send(attribute.write_method, value)
+        end
       end
 
       def default_from_environment
@@ -64,7 +70,7 @@ module Clamp
         # Set the parameter value if it's environment variable is present
         value = ENV[attribute.environment_variable]
         begin
-          write(value)
+          take(value)
         rescue ArgumentError => e
           command.send(:signal_usage_error, "$#{attribute.environment_variable}: #{e.message}")
         end

data/lib/clamp/help.rb

@@ -36,8 +36,8 @@ module Clamp
       declared_usage_descriptions || [derived_usage_description]
     end
 
-    def help(invocation_path)
-      help = Builder.new
+    def help(invocation_path, builder = Builder.new)
+      help = builder
       help.add_usage(invocation_path, usage_descriptions)
       help.add_description(description)
       if has_parameters?

data/lib/clamp/option/parsing.rb

@@ -29,7 +29,7 @@ module Clamp
           value = option.extract_value(switch, remaining_arguments)
 
           begin
-            option.of(self).write(value)
+            option.of(self).take(value)
           rescue ArgumentError => e
             signal_usage_error "option '#{switch}': #{e.message}"
           end

data/lib/clamp/parameter/parsing.rb

@@ -10,7 +10,7 @@ module Clamp
         self.class.parameters.each do |parameter|
           begin
             parameter.consume(remaining_arguments).each do |value|
-              parameter.of(self).write(value)
+              parameter.of(self).take(value)
             end
           rescue ArgumentError => e
             signal_usage_error "parameter '#{parameter.name}': #{e.message}"

data/lib/clamp/version.rb

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

data/spec/clamp/command_spec.rb

@@ -126,6 +126,18 @@ describe Clamp::Command do
         command.flavours.should == %w(chocolate vanilla)
       end
 
+      it "generates a single-value appender method" do
+        command.append_to_flavours("mud")
+        command.append_to_flavours("pie")
+        command.flavours.should == %w(mud pie)
+      end
+
+      it "generates a multi-value setter method" do
+        command.append_to_flavours("replaceme")
+        command.flavours = %w(mud pie)
+        command.flavours.should == %w(mud pie)
+      end
+
     end
 
     describe "with :environment_variable" do

data/spec/clamp/option/definition_spec.rb

@@ -209,10 +209,10 @@ describe Clamp::Option::Definition do
 
     end
 
-    describe "#write_method" do
+    describe "#append_method" do
 
       it "is derived from the attribute_name" do
-        option.write_method.should == "append_to_header_list"
+        option.append_method.should == "append_to_header_list"
       end
 
     end

data/spec/clamp/parameter/definition_spec.rb

@@ -113,10 +113,10 @@ describe Clamp::Parameter::Definition do
 
     end
 
-    describe "#write_method" do
+    describe "#append_method" do
 
       it "is derived from the attribute_name" do
-        parameter.write_method.should == "append_to_file_list"
+        parameter.append_method.should == "append_to_file_list"
       end
 
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-07 00:00:00.000000000 Z
+date: 2013-11-06 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"
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 2.0.7
 signing_key: 
 specification_version: 4
 summary: a minimal framework for command-line utilities