clamp 0.3.1 → 0.4.0

data/README.markdown

@@ -1,7 +1,7 @@
 Clamp
 =====
 
-"Clamp" is a minimal framework for command-line utilities.  
+"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.
 
@@ -42,7 +42,7 @@ Calling `run` on a command class creates an instance of it, then invokes it usin
 
     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.  
+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.
 
 Declaring options
 -----------------
@@ -82,12 +82,20 @@ Some options are just boolean flags.  Pass "`:flag`" as the second parameter to
 
 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: 
+Negatable flags are easy to generate, too:
 
     option "--[no-]force", :flag, "be forceful (or not)"
 
 Clamp will handle both "`--force`" and "`--no-force`" options, setting the value of "`#force?`" appropriately.
 
+### Required options
+
+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
+
+Note that it makes no sense to mark a `:flag` option, or one with a `:default`, as `:required`.
+
 Declaring parameters
 --------------------
 
@@ -125,8 +133,8 @@ Clamp will verify that all required (ie. non-optional) parameters are present, a
 
 ### Validation block
 
-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 
+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.
 
     option "--port", "PORT", "port to listen on" do |s|
@@ -143,19 +151,17 @@ If the block raises an ArgumentError, Clamp will catch it, and report that the v
 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"
-    
+
     def server=(server)
       @server_address, @server_port = server.split(":")
     end
 
 ### Default values
 
-Default values can be specified for options:
+Default values can be specified for options, and optional parameters:
 
     option "--flavour", "FLAVOUR", "ice-cream flavour", :default => "chocolate"
 
-and also for optional parameters
-
     parameter "[HOST]", "server host", :default => "localhost"
 
 For more advanced cases, you can also specify default values by defining a method called "`default_#{attribute_name}`":
@@ -168,6 +174,18 @@ For more advanced cases, you can also specify default values by defining a metho
        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
+
+    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.
+
 Declaring Subcommands
 ---------------------
 
@@ -184,15 +202,15 @@ Unsuprisingly, subcommands are declared using the `subcommand` method. e.g.
         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
 
       subcommand "init", "Initialize the repository", InitCommand
-      
+
     end
 
     class InitCommand < Clamp::Command
@@ -210,7 +228,7 @@ You can set a default subcommand, at the class level, as follows:
     class MainCommand < Clamp::Command
 
       self.default_subcommand = "status"
-      
+
       subcommand "status", "Display current status" do
 
         def execute
@@ -218,7 +236,7 @@ You can set a default subcommand, at the class level, as follows:
         end
 
       end
-      
+
     end
 
 Then, if when no SUBCOMMAND argument is provided, the default will be selected.
@@ -227,7 +245,7 @@ Then, if when no SUBCOMMAND argument is provided, the default will be selected.
 
 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.
 
-Note that, if a subcommand accepts options, they must be specified on the command-line _after_ the subcommand name.  
+Note that, if a subcommand accepts options, they must be specified on the command-line _after_ the subcommand name.
 
 Getting help
 ------------
@@ -271,4 +289,4 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 Contributing to Clamp
 ---------------------
 
-Source-code for Clamp is [on Github](https://github.com/mdub/clamp).  
+Source-code for Clamp is [on Github](https://github.com/mdub/clamp).

data/examples/admin

@@ -0,0 +1,22 @@
+#! /usr/bin/env ruby
+
+# An example of subcommands
+
+require "clamp"
+
+class AdminCommand < Clamp::Command
+
+  option "--timeout", "SECONDS", "connection timeout", :default => 5, :environment_variable => "MYAPP_TIMEOUT" do |x|
+    Integer(x)
+  end
+
+  parameter "HOST", "server address"
+  parameter "[PORT]", "server port", :default => 80, :environment_variable => "MYAPP_PORT"
+
+  def execute
+    puts "trying to connect to #{host} on port #{port} (waiting up to #{timeout} seconds)"
+  end
+
+end
+
+AdminCommand.run

data/examples/gitdown

@@ -15,17 +15,22 @@ module GitDown
       exit(0)
     end
 
+    def say(message)
+      message = message.upcase if verbose?
+      puts message
+    end
+
   end
 
   class CloneCommand < AbstractCommand
-    
+
     parameter "REPOSITORY", "repository to clone"
     parameter "[DIR]", "working directory", :default => "."
 
     def execute
-      raise NotImplementedError
+      say "cloning to #{dir}"
     end
-    
+
   end
 
   class PullCommand < AbstractCommand
@@ -33,23 +38,27 @@ module GitDown
     option "--[no-]commit", :flag, "Perform the merge and commit the result."
 
     def execute
-      raise NotImplementedError
+      say "pulling"
     end
-    
+
   end
 
   class StatusCommand < AbstractCommand
-    
+
     option ["-s", "--short"], :flag, "Give the output in the short-format."
 
     def execute
-      raise NotImplementedError
+      if short?
+        say "good"
+      else
+        say "it's all good ..."
+      end
     end
-    
+
   end
 
   class MainCommand < AbstractCommand
-    
+
     subcommand "clone", "Clone a remote repository.", CloneCommand
     subcommand "pull", "Fetch and merge updates.", PullCommand
     subcommand "status", "Display status of local repository.", StatusCommand

data/lib/clamp/attribute.rb

@@ -2,14 +2,10 @@ module Clamp
 
   class Attribute
 
-    attr_reader :description, :attribute_name, :default_value
+    attr_reader :description, :attribute_name, :default_value, :environment_variable
 
     def help_rhs
-      rhs = description
-      if defined?(@default_value)
-        rhs += " (default: #{@default_value.inspect})"
-      end
-      rhs
+      description + default_description
     end
 
     def help
@@ -32,6 +28,17 @@ module Clamp
       "#{attribute_name}="
     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

@@ -46,7 +46,9 @@ 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.rb

@@ -14,6 +14,19 @@ module Clamp
       if options.has_key?(:default)
         @default_value = options[:default]
       end
+      if options.has_key?(:environment_variable)
+        @environment_variable = options[:environment_variable]
+      end
+      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
@@ -30,6 +43,10 @@ module Clamp
       recognised_switches.member?(switch)
     end
 
+    def required?
+      @required
+    end
+
     def flag?
       @type == :flag
     end

data/lib/clamp/option/parsing.rb

@@ -3,23 +3,45 @@ module Clamp
 
     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
-        while remaining_arguments.first =~ /^-/
+        while remaining_arguments.first =~ /\A-/
 
           switch = remaining_arguments.shift
           break if switch == "--"
 
           case switch
-          when /^(-\w)(.+)$/ # combined short options
+          when /\A(-\w)(.+)\z/m # combined short options
             switch = $1
-            remaining_arguments.unshift("-#{$2}")
-          when /^(--[^=]+)=(.*)/
+            if find_option(switch).flag?
+              remaining_arguments.unshift("-" + $2)
+            else
+              remaining_arguments.unshift($2)
+            end
+          when /\A(--[^=]+)=(.*)\z/m
             switch = $1
             remaining_arguments.unshift($2)
           end
-            
+
           option = find_option(switch)
           value = option.extract_value(switch, remaining_arguments)
 
@@ -30,16 +52,43 @@ module Clamp
           end
 
         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.
+          if option.required? and send(option.attribute_name).nil?
+            message = "option '#{option.switches.first}'"
+            if option.environment_variable
+              message += " (or env #{option.environment_variable})"
+            end
+            message += " is required"
+            signal_usage_error message
+          end
+        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]
+          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
+        end
       end
 
       private
 
       def find_option(switch)
-        self.class.find_option(switch) || 
+        self.class.find_option(switch) ||
         signal_usage_error("Unrecognised option '#{switch}'")
       end
 
     end
 
   end
-end
+end

data/lib/clamp/parameter.rb

@@ -14,6 +14,9 @@ module Clamp
       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 :name, :attribute_name

data/lib/clamp/parameter/parsing.rb

@@ -18,6 +18,18 @@ module Clamp
 
       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.attribute_name}=", value)
+        end
+
+      end
+
     end
 
   end

data/lib/clamp/version.rb

@@ -1,3 +1,3 @@
 module Clamp
-  VERSION = "0.3.1".freeze
+  VERSION = "0.4.0".freeze
 end

data/spec/clamp/command_spec.rb

@@ -1,3 +1,4 @@
+
 require 'spec_helper'
 
 describe Clamp::Command do
@@ -110,6 +111,124 @@ describe Clamp::Command do
 
     end
 
+    describe "with :environment_variable value" do
+
+      before do
+        @command.class.option "--port", "PORT", "port to listen on", :default => 4321, :environment_variable => "PORT" do |value|
+          value.to_i
+        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
+
+      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
+      end
+
+      describe "#help" do
+
+        it "describes the default value and env usage" do
+          @command.help.should include("port to listen on (default: $PORT, or 4321)")
+        end
+
+      end
+
+    end
+
+    describe "with :environment_variable value on a :flag option" 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
+
+      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
+        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
+          @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
+
+    describe "with :required value" do
+
+      before do
+        @command.class.option "--port", "PORT", "port to listen on", :required => true
+      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"])
+      end
+
+    end
+
+    describe "with :required value with :env" do
+
+      before do
+        @command.class.option "--port", "PORT", "port to listen on", :required => true, :environment_variable => "PORT"
+      end
+
+      it "should fail if a required option is not provided" do
+        ENV.delete("PORT")
+        expect { @command.parse([]) }.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([])
+      end
+
+    end
+
+
     describe "with a block" do
 
       before do
@@ -178,6 +297,18 @@ describe Clamp::Command do
 
       end
 
+      describe "with a value appended to a short option" do
+
+        before do
+          @command.parse(%w(-fstrawberry))
+        end
+
+        it "works as though the value were separated" do
+          @command.flavour.should == "strawberry"
+        end
+
+      end
+
       describe "with combined short options" do
 
         before do
@@ -213,6 +344,20 @@ describe Clamp::Command do
 
       end
 
+      describe "with multi-line arguments that look like options" do
+
+        before do
+          @command.parse(["foo\n--flavour=strawberry", "bar\n-cblue"])
+        end
+
+        it "treats them as positional arguments" do
+          @command.arguments.should == ["foo\n--flavour=strawberry", "bar\n-cblue"]
+          @command.flavour.should be_nil
+          @command.color.should be_nil
+        end
+
+      end
+
       describe "with an option terminator" do
 
         it "considers everything after the terminator to be an argument" do
@@ -438,6 +583,40 @@ describe Clamp::Command do
 
     end
 
+    describe "with :environment_variable value" do
+
+      before do
+        @command.class.parameter "[FILE]", "a file", :environment_variable => "FILE",
+          :default => "/dev/null"
+      end
+
+      it "should use the default if neither flag nor env var are present" do
+        @command.parse([])
+        @command.file.should == "/dev/null"
+      end
+
+      it "should use the env value if present (instead of default)" do
+        ENV["FILE"] = "/etc/motd"
+        @command.parse([])
+        @command.file.should == ENV["FILE"]
+      end
+
+      it "should use the the flag value if present (instead of env)" do
+        ENV["FILE"] = "/etc/motd"
+        @command.parse(%w(/bin/sh))
+        @command.file.should == "/bin/sh"
+      end
+
+      describe "#help" do
+
+        it "describes the default value and env usage" do
+          @command.help.should include(%{ (default: $FILE, or "/dev/null")})
+        end
+
+      end
+
+    end
+
   end
 
   describe "with no parameters declared" do
@@ -503,6 +682,17 @@ describe Clamp::Command do
 
       end
 
+      describe "with multi-line arguments" do
+
+        it "parses them correctly" do
+          @command.parse(["foo\nhi", "bar", "baz"])
+          @command.x.should == "foo\nhi"
+          @command.y.should == "bar"
+          @command.z.should == "baz"
+        end
+
+      end
+
       describe "with too many arguments" do
 
         it "raises a UsageError" do

data/spec/clamp/option_spec.rb

@@ -57,7 +57,7 @@ describe Clamp::Option do
   end
 
   describe "flag" do
-    
+
     before do
       @option = Clamp::Option.new("--verbose", :flag, "Blah blah blah")
     end
@@ -69,11 +69,11 @@ describe Clamp::Option do
       end
 
     end
-    
+
   end
 
   describe "negatable flag" do
-    
+
     before do
       @option = Clamp::Option.new("--[no-]force", :flag, "Force installation")
     end
@@ -91,7 +91,7 @@ describe Clamp::Option do
       end
 
     end
-    
+
     describe "#attribute_name" do
 
       it "is derived from the (long) switch" do
@@ -99,7 +99,7 @@ describe Clamp::Option do
       end
 
     end
-    
+
   end
 
   describe "with both short and long switches" do
@@ -123,7 +123,40 @@ describe Clamp::Option do
 
   end
 
+  describe "with an associated environment variable" do
+
+    before do
+      @option = Clamp::Option.new("-x", "X", "mystery option", :environment_variable => "APP_X")
+    end
+
+    describe "#help" do
+
+      it "describes environment variable" do
+        @option.help.should == ["-x X", "mystery option (default: $APP_X)"]
+      end
+
+    end
+
+    describe "and a default value" do
+
+      before do
+        @option = Clamp::Option.new("-x", "X", "mystery option", :environment_variable => "APP_X", :default => "xyz")
+      end
+
+      describe "#help" do
+
+        it "describes both environment variable and default" do
+          @option.help.should == ["-x X", %{mystery option (default: $APP_X, or "xyz")}]
+        end
+
+      end
+
+    end
+
+  end
+
   describe "in subcommand" do
+
     before do
 
       @command = Class.new(Clamp::Command) do
@@ -145,5 +178,19 @@ describe Clamp::Option do
     end
 
   end
-  
+
+  describe "a required option" do
+    it "rejects :default" do
+      expect do
+        Clamp::Option.new("--key-file", "FILE", "SSH identity",
+                          :required => true, :default => "hello")
+      end.to raise_error(ArgumentError)
+    end
+
+    it "rejects :flag options" do
+      expect do
+        Clamp::Option.new("--awesome", :flag, "Be awesome?", :required => true)
+      end.to raise_error(ArgumentError)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-03 00:00:00.000000000 Z
+date: 2012-05-13 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"
@@ -24,6 +24,7 @@ files:
 - README.markdown
 - Rakefile
 - clamp.gemspec
+- examples/admin
 - examples/flipflop
 - examples/fubar
 - examples/gitdown
@@ -64,7 +65,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1856448867096069066
+      hash: -1903818616036317857
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -73,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1856448867096069066
+      hash: -1903818616036317857
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.21