[MIXLIB-CLI-63] Add deprecated_option supportexperiment

This commit adds deprecated option support by exposing a
new ClassMethod, `deprecated_option`. It will generate a
corresponding deprecated option, and if that option is used it will
handle mapping of the old option to the new and issue a warning.

`deprecated_option` accepts a subset of the parameters that `option` accepts.

Most importantly, a deprecated option can't have a default value.
There's a practical reason for this and a philosophical one.

Practically, it makes it easy to track the situation where someone has
set `use_separate_defaults` to `false`.  In that case, we currently
can't tell whether the user provided the flag, or it was set as a default.
This could have been addressed, but:

Philosophically it makes more sense to not have a default value on a
deprecated item. If it's deprecated, you want people to stop using it.
If it has a default, it's effectively forced in-use at all times.

See function docs for further accepted parameters.

To allow deprecated options without warnings, use parse_options as
`parse_options(ARGV, show_deprecations: false)`. By default, warnings
will be shown.

This also moves some formatting code into its own class -
it was causing methods to get mixed in that client classes didn't
need; and I reached the point where I needed to access the formatting
functions across methods in both Mixlib::CLI and
Mixlib::CLI::ClassMethods. It made more sense to move them outside of
the mixed-in bits, since it wasn't a concern of the caller that would be
inheriting those methods.

Signed-off-by: Marc A. Paradise <marc.paradise@gmail.com>

1 files changed, 29 insertions, 0 deletions

diff --git a/lib/mixlib/cli/formatter.rb b/lib/mixlib/cli/formatter.rb
new file mode 100644
index 0000000..b89090d
--- /dev/null
+++ b/lib/mixlib/cli/formatter.rb
@@ -0,0 +1,29 @@
+
+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 = ""
+        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