jls-clamp 0.3.1 → 0.3.1.2

data/README.markdown

@@ -88,6 +88,32 @@ Negatable flags are easy to generate, too:
 
 Clamp will handle both "`--force`" and "`--no-force`" options, setting the value of "`#force?`" appropriately.
 
+### Values from the environment
+
+Sometimes you'll want to pass in option values from the environment:
+
+    option "--port", "PORT", "the port to listen on", :env => "PORT" do |val|
+      val.to_i
+    end
+
+The above means that in the absence of '--port' on the command line, Clamp will
+check for `PORT` in the environment. This lets you do:
+
+    % export PORT=8080 
+    % ./mycommand
+
+### Required options
+
+While a 'required option' is a bit of an oxymoron, it is common to use options
+as named parameters to your program. Clamp lets you make an option required:
+
+    option "--password", "PASSWORD", "the secret password", :required => true
+
+Special notes about required options:
+
+* You may not use :required and :default values in the same option ('require' doesn't make sense if you provide a default)
+* You may not use :required on :flag options. Since :flag options are boolean, a 'required flag' would mean "always true" ;)
+
 Declaring parameters
 --------------------
 
@@ -116,6 +142,18 @@ Three dots at the end of a parameter name makes it "greedy" - it will consume al
 
 The suffix "`_list`" is appended to the default attribute name for greedy parameters; in this case, an attribute called "`file_list`" would be generated.
 
+### Parameters from the environment
+
+Optional parameters can have values given from the environment the same way options can.
+
+    parameter "[EXAMPLE]", "This is an example", :env => "EXAMPLE"
+
+The above means that in the absence of a value on the command line, Clamp will
+check for `EXAMPLE` in the environment. This lets you do:
+
+    % export EXAMPLE="hello" 
+    % ./mycommand
+
 Parsing and validation of options and parameters
 ------------------------------------------------
 

data/lib/clamp/attribute.rb

@@ -2,15 +2,15 @@ module Clamp
 
   class Attribute
 
-    attr_reader :description, :attribute_name, :default_value, :env_var
+    attr_reader :description, :attribute_name, :default_value, :environment_variable
 
     def help_rhs
       rhs = description
       if defined?(@default_value)
         rhs += " (default: #{@default_value.inspect})"
       end
-      if defined?(@env_var)
-        rhs += " (env: #{@env_var.inspect})"
+      if defined?(@environment_variable)
+        rhs += " (env: #{@environment_variable.inspect})"
       end
       rhs
     end

data/lib/clamp/command.rb

@@ -46,8 +46,9 @@ module Clamp
     #
     def parse(arguments)
       @remaining_arguments = arguments.dup
-      parse_environment
+      parse_environment_options
       parse_options
+      parse_environment_parameters
       parse_parameters
       parse_subcommand
       handle_remaining_arguments

data/lib/clamp/option.rb

@@ -15,7 +15,17 @@ module Clamp
         @default_value = options[:default]
       end
       if options.has_key?(:env)
-        @env_var = options[:env]
+        @environment_variable = options[:env]
+      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
 
@@ -33,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,6 +3,24 @@ 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", :env => "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
@@ -30,16 +48,29 @@ 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
+      def parse_environment_options
         self.class.recognised_options.each do |option|
-          next if option.env_var.nil?
-          next unless ENV.has_key?(option.env_var)
-          value = ENV[option.env_var]
+          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 env var is "1" false otherwise.
-            send("#{option.attribute_name}=", value == "1")
+            # Set true if the environment value is truthy.
+            send("#{option.attribute_name}=", TRUTHY_ENVIRONMENT_VALUES.include?(value))
           else
             send("#{option.attribute_name}=", value)
           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?(:env)
+        @environment_variable = options[:env]
+      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.3.1.2".freeze
 end

data/spec/clamp/command_spec.rb

@@ -119,6 +119,7 @@ describe Clamp::Command do
       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
@@ -156,16 +157,27 @@ describe Clamp::Command do
         @command.enable?.should == false
       end
 
-      it "should use an env value of '1' to mean truth" do
-        ENV["ENABLE"] = "1"
-        @command.parse([])
-        @command.enable?.should == true
+      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
 
-      it "should use an env value other than '1' to mean false" do
-        ENV["ENABLE"] = "0"
-        @command.parse([])
-        @command.enable?.should == false
+      # 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
@@ -184,6 +196,46 @@ describe Clamp::Command do
 
     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, :env => "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
@@ -512,6 +564,40 @@ describe Clamp::Command do
 
     end
 
+    describe "with :env value" do
+
+      before do
+        @command.class.parameter "[FILE]", "a file", :env => "FILE",
+          :default => "default"
+      end
+
+      it "should use the default if neither flag nor env var are present" do
+        @command.parse([])
+        @command.file.should == "default"
+      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("a file (default: \"default\") (env: \"FILE\")")
+        end
+
+      end
+
+    end
+
   end
 
   describe "with no parameters declared" do

data/spec/clamp/option_spec.rb

@@ -145,5 +145,20 @@ 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: jls-clamp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-25 00:00:00.000000000 Z
+date: 2012-04-30 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"