mixlib-cli 1.2.2 → 1.3.0.rc.0

data/Rakefile

@@ -1,5 +1,5 @@
 require 'rubygems'
-require 'rake/gempackagetask'
+require 'rubygems/package_task'
 require 'rspec/core/rake_task'
 require 'rdoc/task'
 
@@ -12,7 +12,7 @@ end
 
 gem_spec = eval(File.read("mixlib-cli.gemspec"))
 
-Rake::GemPackageTask.new(gem_spec) do |pkg|
+Gem::PackageTask.new(gem_spec) do |pkg|
   pkg.gem_spec = gem_spec
 end
 

data/lib/mixlib/cli.rb

@@ -6,9 +6,9 @@
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
-# 
+#
 #     http://www.apache.org/licenses/LICENSE-2.0
-# 
+#
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -19,8 +19,37 @@
 require 'optparse'
 
 module Mixlib
+
+  # == Mixlib::CLI
+  # Adds a DSL for defining command line options and methods for parsing those
+  # options to the including class.
+  #
+  # Mixlib::CLI does some setup in #initialize, so the including class must
+  # call `super()` if it defines a custom initializer.
+  #
+  # === DSL
+  # When included, Mixlib::CLI also extends the including class with its
+  # ClassMethods, which define the DSL. The primary methods of the DSL are
+  # ClassMethods#option, which defines a command line option, and
+  # ClassMethods#banner, which defines the "usage" banner.
+  #
+  # === Parsing
+  # Command line options are parsed by calling the instance method
+  # #parse_options. After calling this method, the attribute #config will
+  # contain a hash of `:option_name => value` pairs.
   module CLI
-    module ClassMethods       
+    module ClassMethods
+
+      # When this setting is set to +true+, default values supplied to the
+      # mixlib-cli DSL will be stored in a separate Hash
+      def use_separate_default_options(true_or_false)
+        @separate_default_options = true_or_false
+      end
+
+      def use_separate_defaults?
+        @separate_default_options || false
+      end
+
       # Add a command line option.
       #
       # === Parameters
@@ -33,7 +62,7 @@ module Mixlib
         raise(ArgumentError, "Option name must be a symbol") unless name.kind_of?(Symbol)
         @options[name.to_sym] = args
       end
-      
+
       # Get the hash of current options.
       #
       # === Returns
@@ -42,7 +71,7 @@ module Mixlib
         @options ||= {}
         @options
       end
-      
+
       # Set the current options hash
       #
       # === Parameters
@@ -54,13 +83,13 @@ module Mixlib
         raise(ArgumentError, "Options must recieve a hash") unless val.kind_of?(Hash)
         @options = val
       end
-      
+
       # Change the banner.  Defaults to:
       #   Usage: #{0} (options)
       #
       # === Parameters
       # bstring<String>:: The string to set the banner to
-      # 
+      #
       # === Returns
       # @banner<String>:: The current banner
       def banner(bstring=nil)
@@ -72,9 +101,43 @@ module Mixlib
         end
       end
     end
-    
-    attr_accessor :options, :config, :banner, :opt_parser
-    
+
+    # Gives the command line options definition as configured in the DSL. These
+    # are used by #parse_options to generate the option parsing code. To get
+    # the values supplied by the user, see #config.
+    attr_accessor :options
+
+    # A Hash containing the values supplied by command line options.
+    #
+    # The behavior and contents of this Hash vary depending on whether
+    # ClassMethods#use_separate_default_options is enabled.
+    # ==== use_separate_default_options *disabled*
+    # After initialization, +config+ will contain any default values defined
+    # via the mixlib-config DSL. When #parse_options is called, user-supplied
+    # values (from ARGV) will be merged in.
+    # ==== use_separate_default_options *enabled*
+    # After initialization, this will be an empty hash. When #parse_options is
+    # called, +config+ is populated *only* with user-supplied values.
+    attr_accessor :config
+
+    # If ClassMethods#use_separate_default_options is enabled, this will be a
+    # Hash containing key value pairs of `:option_name => default_value`
+    # (populated during object initialization).
+    #
+    # If use_separate_default_options is disabled, it will always be an empty
+    # hash.
+    attr_accessor :default_config
+
+    # Banner for the option parser. If the option parser is printed, e.g., by
+    # `puts opt_parser`, this string will be used as the first line.
+    attr_accessor :banner
+
+    # The option parser generated from the mixlib-cli DSL. Set to nil on
+    # initialize; when #parse_options is called +opt_parser+ is set to an
+    # instance of OptionParser. +opt_parser+ can be used to print a help
+    # message including the banner and any CLI options via `puts opt_parser`.
+    attr_accessor :opt_parser
+
     # Create a new Mixlib::CLI class.  If you override this, make sure you call super!
     #
     # === Parameters
@@ -85,14 +148,23 @@ module Mixlib
     def initialize(*args)
       @options = Hash.new
       @config  = Hash.new
-      
+      @default_config = Hash.new
+      @opt_parser = nil
+
       # Set the banner
       @banner  = self.class.banner
-      
+
       # Dupe the class options for this instance
       klass_options = self.class.options
       klass_options.keys.inject(@options) { |memo, key| memo[key] = klass_options[key].dup; memo }
-      
+
+      # If use_separate_defaults? is on, default values go in @default_config
+      defaults_container = if self.class.use_separate_defaults?
+                             @default_config
+                           else
+                             @config
+                           end
+
       # Set the default configuration values for this instance
       @options.each do |config_key, config_opts|
         config_opts[:on] ||= :on
@@ -101,16 +173,16 @@ module Mixlib
         config_opts[:proc] ||= nil
         config_opts[:show_options] ||= false
         config_opts[:exit] ||= nil
-        
+
         if config_opts.has_key?(:default)
-          @config[config_key] = config_opts[:default]
+          defaults_container[config_key] = config_opts[:default]
         end
       end
-      
+
       super(*args)
     end
-    
-    # Parses an array, by default ARGV, for command line options (as configured at 
+
+    # Parses an array, by default ARGV, for command line options (as configured at
     # the class level).
     # === Parameters
     # argv<Array>:: The array of arguments to parse; defaults to ARGV
@@ -119,14 +191,14 @@ module Mixlib
     # argv<Array>:: Returns any un-parsed elements.
     def parse_options(argv=ARGV)
       argv = argv.dup
-      @opt_parser = OptionParser.new do |opts|  
+      @opt_parser = OptionParser.new do |opts|
         # Set the banner
-        opts.banner = banner        
-        
+        opts.banner = banner
+
         # Create new options
-        options.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |opt_key, opt_val|          
+        options.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |opt_key, opt_val|
           opt_args = build_option_arguments(opt_val)
-          
+
           opt_method = case opt_val[:on]
             when :on
               :on
@@ -137,14 +209,14 @@ module Mixlib
             else
               raise ArgumentError, "You must pass :on, :tail, or :head to :on"
             end
-                      
+
           parse_block =
             Proc.new() do |c|
               config[opt_key] = (opt_val[:proc] && opt_val[:proc].call(c)) || c
               puts opts if opt_val[:show_options]
               exit opt_val[:exit] if opt_val[:exit]
             end
-                    
+
           full_opt = [ opt_method ]
           opt_args.inject(full_opt) { |memo, arg| memo << arg; memo }
           full_opt << parse_block
@@ -152,7 +224,7 @@ module Mixlib
         end
       end
       @opt_parser.parse!(argv)
-      
+
       # Deal with any required values
       options.each do |opt_key, opt_value|
         if opt_value[:required] && !config.has_key?(opt_key)
@@ -162,28 +234,28 @@ module Mixlib
           exit 2
         end
       end
-      
+
       argv
     end
-    
-    def build_option_arguments(opt_setting)      
+
+    def build_option_arguments(opt_setting)
       arguments = Array.new
-      
+
       arguments << opt_setting[:short] if opt_setting.has_key?(:short)
       arguments << opt_setting[:long] if opt_setting.has_key?(:long)
-      
+
       if opt_setting.has_key?(:description)
         description = opt_setting[:description]
         description << " (required)" if opt_setting[:required]
         arguments << description
       end
-          
+
       arguments
     end
-    
+
     def self.included(receiver)
       receiver.extend(Mixlib::CLI::ClassMethods)
     end
-    
+
   end
 end

data/lib/mixlib/cli/version.rb

@@ -1,6 +1,6 @@
 module Mixlib
   module CLI
-    VERSION = "1.2.2"
+    VERSION = "1.3.0.rc.0"
   end
 end
 

data/spec/mixlib/cli_spec.rb

@@ -6,9 +6,9 @@
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
-# 
+#
 #     http://www.apache.org/licenses/LICENSE-2.0
-# 
+#
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -18,56 +18,56 @@
 
 require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
 
-describe Mixlib::CLI do  
+describe Mixlib::CLI do
   after(:each) do
     TestCLI.options = {}
     TestCLI.banner("Usage: #{$0} (options)")
   end
-  
+
   describe "class method" do
     describe "option" do
       it "should allow you to set a config option with a hash" do
         TestCLI.option(:config_file, :short => '-c CONFIG').should == { :short => '-c CONFIG' }
       end
     end
-    
+
     describe "options" do
       it "should return the current options hash" do
         TestCLI.option(:config_file, :short => '-c CONFIG')
         TestCLI.options.should == { :config_file => { :short => '-c CONFIG' } }
       end
     end
-    
+
     describe "options=" do
       it "should allow you to set the full options with a single hash" do
         TestCLI.options = { :config_file => { :short => '-c CONFIG' } }
         TestCLI.options.should == { :config_file => { :short => '-c CONFIG' } }
       end
     end
-    
+
     describe "banner" do
       it "should have a default value" do
         TestCLI.banner.should =~ /^Usage: (.+) \(options\)$/
       end
-      
+
       it "should allow you to set the banner" do
         TestCLI.banner("Usage: foo")
         TestCLI.banner.should == "Usage: foo"
       end
     end
   end
-  
-  describe "instance methods" do
-    
+
+  context "when configured with default single-config-hash behavior" do
+
     before(:each) do
       @cli = TestCLI.new
     end
-    
+
     describe "initialize" do
       it "should set the banner to the class defined banner" do
         @cli.banner.should == TestCLI.banner
       end
-      
+
       it "should set the options to the class defined options, plus defaults" do
         TestCLI.option(:config_file, :short => "-l LOG")
         cli = TestCLI.new
@@ -83,27 +83,27 @@ describe Mixlib::CLI do
           }
         }
       end
-      
+
       it "should set the default config value for any options that include it" do
         TestCLI.option(:config_file, :short => "-l LOG", :default => :debug)
         @cli = TestCLI.new
         @cli.config[:config_file].should == :debug
       end
     end
-    
+
     describe "parse_options" do
       it "should set the banner in opt_parse" do
         @cli.parse_options([])
         @cli.opt_parser.banner.should == @cli.banner
       end
-      
+
       it "should present the arguments in the banner" do
         TestCLI.option(:config_file, :short => "-l LOG")
         @cli = TestCLI.new
         @cli.parse_options([])
         @cli.opt_parser.to_s.should =~ /-l LOG/
       end
-      
+
       it "should honor :on => :tail options in the banner" do
         TestCLI.option(:config_file, :short => "-l LOG")
         TestCLI.option(:help, :short => "-h", :boolean => true, :on => :tail)
@@ -111,7 +111,7 @@ describe Mixlib::CLI do
         @cli.parse_options([])
         @cli.opt_parser.to_s.split("\n").last.should =~ /-h/
       end
-      
+
       it "should honor :on => :head options in the banner" do
         TestCLI.option(:config_file, :short => "-l LOG")
         TestCLI.option(:help, :short => "-h", :boolean => true, :on => :head)
@@ -119,11 +119,11 @@ describe Mixlib::CLI do
         @cli.parse_options([])
         @cli.opt_parser.to_s.split("\n")[1].should =~ /-h/
       end
-      
+
       it "should present the arguments in alphabetical order in the banner" do
         TestCLI.option(:alpha, :short => "-a ALPHA")
         TestCLI.option(:beta, :short => "-b BETA")
-        TestCLI.option(:zeta, :short => "-z ZETA")        
+        TestCLI.option(:zeta, :short => "-z ZETA")
         @cli = TestCLI.new
         @cli.parse_options([])
         output_lines = @cli.opt_parser.to_s.split("\n")
@@ -131,31 +131,31 @@ describe Mixlib::CLI do
         output_lines[2].should =~ /-b BETA/
         output_lines[3].should =~ /-z ZETA/
       end
-      
+
       it "should set the corresponding config value for non-boolean arguments" do
         TestCLI.option(:config_file, :short => "-c CONFIG")
         @cli = TestCLI.new
         @cli.parse_options([ '-c', 'foo.rb' ])
         @cli.config[:config_file].should == 'foo.rb'
-      end   
-      
+      end
+
       it "should set the corresponding config value according to a supplied proc" do
-        TestCLI.option(:number, 
-          :short => "-n NUMBER", 
+        TestCLI.option(:number,
+          :short => "-n NUMBER",
           :proc => Proc.new { |config| config.to_i + 2 }
         )
         @cli = TestCLI.new
         @cli.parse_options([ "-n", "2" ])
         @cli.config[:number].should == 4
       end
-      
+
       it "should set the corresponding config value to true for boolean arguments" do
         TestCLI.option(:i_am_boolean, :short => "-i", :boolean => true)
         @cli = TestCLI.new
         @cli.parse_options([ '-i' ])
         @cli.config[:i_am_boolean].should == true
       end
-      
+
       it "should set the corresponding config value to false when a boolean is prefixed with --no" do
         TestCLI.option(:i_am_boolean, :long => "--[no-]bool", :boolean => true)
         @cli = TestCLI.new
@@ -213,23 +213,44 @@ describe Mixlib::CLI do
       end
     end
   end
-  
+
+  context "when configured to separate default options" do
+    before do
+      TestCLI.use_separate_default_options true
+      TestCLI.option(:defaulter, :short => "-D SOMETHING", :default => "this is the default")
+      @cli = TestCLI.new
+    end
+
+    it "sets default values on the `default` hash" do
+      @cli.parse_options([])
+      @cli.default_config[:defaulter].should == "this is the default"
+      @cli.config[:defaulter].should be_nil
+    end
+
+    it "sets parsed values on the `config` hash" do
+      @cli.parse_options(%w[-D not-default])
+      @cli.default_config[:defaulter].should == "this is the default"
+      @cli.config[:defaulter].should == "not-default"
+    end
+
+  end
+
 end
 
 
-#  option :config_file, 
+#  option :config_file,
 #    :short => "-c CONFIG",
 #    :long  => "--config CONFIG",
 #    :default => 'config.rb',
 #    :description => "The configuration file to use"
-#    
-#  option :log_level, 
+#
+#  option :log_level,
 #    :short => "-l LEVEL",
 #    :long  => "--log_level LEVEL",
 #    :description => "Set the log level (debug, info, warn, error, fatal)",
 #    :required => true,
 #    :proc => nil
-#    
+#
 #  option :help,
 #    :short => "-h",
 #    :long => "--help",

metadata

@@ -1,35 +1,25 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: mixlib-cli
-version: !ruby/object:Gem::Version 
-  hash: 27
-  prerelease: 
-  segments: 
-  - 1
-  - 2
-  - 2
-  version: 1.2.2
+version: !ruby/object:Gem::Version
+  version: 1.3.0.rc.0
+  prerelease: 6
 platform: ruby
-authors: 
+authors:
 - Opscode, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-08 00:00:00 -07:00
-default_executable: 
+date: 2013-01-10 00:00:00.000000000 Z
 dependencies: []
-
 description: A simple mixin for CLI interfaces, including option parsing
 email: info@opscode.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.rdoc
 - LICENSE
 - NOTICE
-files: 
+files:
 - LICENSE
 - README.rdoc
 - Rakefile
@@ -38,39 +28,28 @@ files:
 - lib/mixlib/cli.rb
 - spec/mixlib/cli_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://www.opscode.com
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: A simple mixin for CLI interfaces, including option parsing
 test_files: []
-