mixlib-cli 2.0.6 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68387a8a44b1950e412ec9223768a222b4c1660aa020612acab1469d30ffb329
-  data.tar.gz: 5aca34f4245d223175b88531c14950652211defd8fbe39ebdbac73d79e33f59d
+  metadata.gz: fe2f048e8780700eefac7a4cdf7f7208e5026e46fccd8ba1d174d0ac2392c789
+  data.tar.gz: f16971b7985e2ed441ae186f1aecb8decf8b3e230912fd3690e00b2c3d5ff42b
 SHA512:
-  metadata.gz: aaf246f2fbcadda3e6ad29cdd9b2e0b6bc5b68b4471dbad56828ef499f2cfbbee9c00ffe7ca9543ef7c38d8f260711766a759bd7117885f758edd387fa9fe8ef
-  data.tar.gz: 944784207d6b274ec01b87bec93c23a98cfd1357a6a3f5cdf2c38de6fb3e71caf8c7f9c020ad7fc5aa539c459622003529e8c964461ba11f12d35c07c5d07d8f
+  metadata.gz: ae94cbf04f14035a78a90ed4a76b2682cc3a59c794c2b7df3148d38946a7fead9cb5bb65d95599b34fdcc215b513441393b4f3b382606d9675088a418b7f6e16
+  data.tar.gz: 6b922bc226625b74d7a2ad3b998a388a0347ac8e0438a6e7c563b98e43d9fb7cc22589c2eca3a398dad99567d8573c2a2725de37edde5f942a505c8b834878a0

data/lib/mixlib/cli.rb

@@ -17,7 +17,7 @@
 #
 
 require "optparse"
-
+require "mixlib/cli/formatter"
 module Mixlib
 
   # == Mixlib::CLI
@@ -30,8 +30,9 @@ module Mixlib
   # === 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.
+  # ClassMethods#option, which defines a command line option;
+  # ClassMethods#banner, which defines the "usage" banner;
+  # and ClassMethods#deprecated_option, which defines a deprecated command-line option.
   #
   # === Parsing
   # Command line options are parsed by calling the instance method
@@ -93,14 +94,88 @@ module Mixlib
       # === Parameters
       # name<Symbol>:: The name of the option to add
       # args<Hash>:: A hash of arguments for the option, specifying how it should be parsed.
-      # === Returns
-      # true:: Always returns true.
+      #   Supported arguments:
+      #     :short   - The short option, just like from optparse. Example: "-l LEVEL"
+      #     :long    - The long option, just like from optparse. Example: "--level LEVEL"
+      #     :description - The description for this item, just like from optparse.
+      #     :default - A default value for this option.  Default values will be populated
+      #     on parse into `config` or `default_default`, depending `use_separate_defaults`
+      #     :boolean - indicates the flag is a boolean. You can use this if the flag takes no arguments
+      #                The config value will be set to 'true' if the flag is provided on the CLI and this
+      #                argument is set to true. The config value will be set to false only
+      #                if it has a default value of false
+      #     :required - When set, the option is required.  If the command is run without this option,
+      #                it will print a message informing the user of the missing requirement, and exit. Default is false.
+      #     :proc     - Proc that will be invoked if the human has specified this option.
+      #                 Two forms are supported:
+      #                 Proc/1 - provided value is passed in.
+      #                 Proc/2 - first argument is provided value. Second is the cli flag option hash.
+      #                 Both versions return the value to be assigned to the option.
+      #     :show_options - this option is designated as one that shows all supported options/help when invoked.
+      #     :exit     - exit your program with the exit code when this option is given. Example: 0
+      #     :in       - array containing a list of valid values. The value provided at run-time for the option is
+      #                 validated against this. If it is not in the list, it will print a message and exit.
+      #     :on :head OR :tail - force this option to display at the beginning or end of the
+      #                          option list, respectively
+      # =
+      # @return <Hash> :: the config hash for the created option
+      # i
       def option(name, args)
         @options ||= {}
         raise(ArgumentError, "Option name must be a symbol") unless name.kind_of?(Symbol)
         @options[name.to_sym] = args
       end
 
+      # Declare a deprecated option
+      #
+      # Add a deprecated command line option.
+      #
+      # name<Symbol> :: The name of the deprecated option
+      # replacement<Symbol> :: The name of the option that replaces this option.
+      # long<String> :: The original long flag name, or flag name with argument, eg "--user USER"
+      # short<String>  :: The original short-form flag name, eg "-u USER"
+      # boolean<String> :: true if this is a boolean flag, eg "--[no-]option".
+      # value_mapper<Proc/1> :: a block that accepts the original value from the deprecated option,
+      #                   and converts it to a value suitable for the new option.
+      #                   If not provided, the value provided to the deprecated option will be
+      #                   assigned directly to the converted option.
+      # keep<Boolean> :: Defaults to true, this ensure sthat `options[:deprecated_flag]` is
+      #                  populated when the deprecated flag is used. If set to false,
+      #                  only the value in `replacement` will be set.  Results undefined
+      #                  if no replacement is provided. You can use this to enforce the transition
+      #                  to non-deprecated keys in your code.
+      #
+      # === Returns
+      # <Hash> :: The config hash for the created option.
+      def deprecated_option(name,
+                            replacement: nil,
+                            long: nil,
+                            short: nil,
+                            boolean: false,
+                            value_mapper: nil,
+                            keep: true)
+
+        description = if replacement
+                        replacement_cfg = options[replacement]
+                        display_name = CLI::Formatter.combined_option_display_name(replacement_cfg[:short], replacement_cfg[:long])
+                        "This flag is deprecated. Use #{display_name} instead."
+                      else
+                        "This flag is deprecated and will be removed in a future release."
+                      end
+        value_mapper ||= Proc.new { |v| v }
+
+        option(name,
+               long: long,
+               short: short,
+               boolean: boolean,
+               description: description,
+               on: :tail,
+               deprecated: true,
+               keep: keep,
+               replacement: replacement,
+               value_mapper: value_mapper)
+      end
+
       # Get the hash of current options.
       #
       # === Returns
@@ -209,7 +284,6 @@ module Mixlib
         config_opts[:show_options] ||= false
         config_opts[:exit] ||= nil
         config_opts[:in] ||= nil
-
         if config_opts.key?(:default)
           defaults_container[config_key] = config_opts[:default]
         end
@@ -225,25 +299,30 @@ module Mixlib
     #
     # === Returns
     # argv<Array>:: Returns any un-parsed elements.
-    def parse_options(argv = ARGV)
+    def parse_options(argv = ARGV, show_deprecations: true)
       argv = argv.dup
       opt_parser.parse!(argv)
+      # Do this before our custom validations, so that custom
+      # validations apply to any converted deprecation values;
+      # but after parse! so that everything is populated.
+      handle_deprecated_options(show_deprecations)
 
       # Deal with any required values
-      options.each do |opt_key, opt_value|
-        if opt_value[:required] && !config.key?(opt_key)
-          reqarg = opt_value[:short] || opt_value[:long]
+      options.each do |opt_key, opt_config|
+        if opt_config[:required] && !config.key?(opt_key)
+          reqarg = opt_config[:short] || opt_config[:long]
           puts "You must supply #{reqarg}!"
           puts @opt_parser
           exit 2
         end
-        if opt_value[:in]
-          unless opt_value[:in].kind_of?(Array)
+        if opt_config[:in]
+          unless opt_config[:in].kind_of?(Array)
             raise(ArgumentError, "Options config key :in must receive an Array")
           end
-          if config[opt_key] && !opt_value[:in].include?(config[opt_key])
-            reqarg = opt_value[:short] || opt_value[:long]
-            puts "#{reqarg}: #{config[opt_key]} is not one of the allowed values: #{friendly_opt_list(opt_value[:in])}"
+          if config[opt_key] && !opt_config[:in].include?(config[opt_key])
+            reqarg = Formatter.combined_option_display_name(opt_config[:short], opt_config[:long])
+            puts "#{reqarg}: #{config[opt_key]} is not one of the allowed values: #{Formatter.friendly_opt_list(opt_config[:in])}"
+            # TODO - get rid of this. nobody wants to be spammed with a  ton of information, particularly since we just told them the exact problem and how to fix it.
             puts @opt_parser
             exit 2
           end
@@ -267,7 +346,6 @@ module Mixlib
         # Create new options
         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
@@ -305,15 +383,53 @@ module Mixlib
       end
     end
 
+    # Iterates through options declared as deprecated,
+    # maps values to their replacement options,
+    # and prints deprecation warnings.
+    #
+    # @return NilClass
+    def handle_deprecated_options(show_deprecations)
+      merge_in_values = {}
+      config.each_key do |opt_key|
+        opt_cfg = options[opt_key]
+        # Deprecated entries do not have defaults so no matter what
+        # separate_default_options are set, if we see a 'config'
+        # entry that contains a deprecated indicator, then the option was
+        # explicitly provided by the caller.
+        next unless opt_cfg[:deprecated]
+        replacement_key = opt_cfg[:replacement]
+        if replacement_key
+          # This is the value passed into the deprecated flag. We'll use
+          # the declared value mapper (defaults to return the same value if caller hasn't
+          # provided a mapper).
+          deprecated_val = config[opt_key]
+
+          # We can't modify 'config' since we're iterating it, apply updates
+          # at the end.
+          merge_in_values[replacement_key] = opt_cfg[:value_mapper].call(deprecated_val)
+          config.delete(opt_key) unless opt_cfg[:keep]
+        end
+
+        # Warn about the deprecation.
+        if show_deprecations
+          # Description is also the deprecation message.
+          display_name = CLI::Formatter.combined_option_display_name(opt_cfg[:short], opt_cfg[:long])
+          puts "#{display_name}: #{opt_cfg[:description]}"
+        end
+      end
+      config.merge!(merge_in_values)
+      nil
+    end
+
     def build_option_arguments(opt_setting)
       arguments = Array.new
 
-      arguments << opt_setting[:short] if opt_setting.key?(:short)
-      arguments << opt_setting[:long] if opt_setting.key?(:long)
+      arguments << opt_setting[:short] if opt_setting[:short]
+      arguments << opt_setting[:long] if opt_setting[:long]
       if opt_setting.key?(:description)
         description = opt_setting[:description].dup
         description << " (required)" if opt_setting[:required]
-        description << " (valid options: #{friendly_opt_list(opt_setting[:in])})" if opt_setting[:in]
+        description << " (valid options: #{Formatter.friendly_opt_list(opt_setting[:in])})" if opt_setting[:in]
         opt_setting[:description] = description
         arguments << description
       end
@@ -321,20 +437,9 @@ module Mixlib
       arguments
     end
 
-    # @private
-    # @param opt_arry [Array]
-    #
-    # @return [String] a friendly quoted list of items complete with "or"
-    def friendly_opt_list(opt_array)
-      opts = opt_array.map { |x| "'#{x}'" }
-      return opts.join(" or ") if opts.size < 3
-      opts[0..-2].join(", ") + ", or " + opts[-1]
-    end
-
     def self.included(receiver)
       receiver.extend(Mixlib::CLI::ClassMethods)
       receiver.extend(Mixlib::CLI::InheritMethods)
     end
-
   end
 end

data/lib/mixlib/cli/formatter.rb

@@ -0,0 +1,32 @@
+
+module Mixlib
+  module CLI
+    class Formatter
+      # Create a string that includes both versions (short/long) of a flag name
+      # based on on whether short/long/both/neither are provided
+      #
+      # @param short [String] the short name of the option. Can be nil.
+      # @param long [String] the long name of the option. Can be nil.
+      # @return [String] the formatted flag name as described above
+      def self.combined_option_display_name(short, long)
+        usage = ""
+        # short/long may have an argument (--long ARG)
+        # splitting on " " and taking first ensures that we get just
+        # the flag name without the argument if one is present.
+        usage << short.split(" ").first if short
+        usage << "/" if long && short
+        usage << long.split(" ").first if long
+        usage
+      end
+
+      # @param opt_arry [Array]
+      #
+      # @return [String] a friendly quoted list of items complete with "or"
+      def self.friendly_opt_list(opt_array)
+        opts = opt_array.map { |x| "'#{x}'" }
+        return opts.join(" or ") if opts.size < 3
+        opts[0..-2].join(", ") + ", or " + opts[-1]
+      end
+    end
+  end
+end

data/lib/mixlib/cli/version.rb

@@ -1,5 +1,5 @@
 module Mixlib
   module CLI
-    VERSION = "2.0.6".freeze
+    VERSION = "2.1.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixlib-cli
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.1.0
 platform: ruby
 authors:
 - Chef Software, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-14 00:00:00.000000000 Z
+date: 2019-06-07 00:00:00.000000000 Z
 dependencies: []
 description: A simple mixin for CLI interfaces, including option parsing
 email: info@chef.io
@@ -19,8 +19,9 @@ files:
 - LICENSE
 - NOTICE
 - lib/mixlib/cli.rb
+- lib/mixlib/cli/formatter.rb
 - lib/mixlib/cli/version.rb
-homepage: https://www.github.com/mixlib-cli
+homepage: https://github.com/chef/mixlib-cli
 licenses:
 - Apache-2.0
 metadata: {}