command_kit 0.2.2 → 0.3.0

data/lib/command_kit/options/option.rb

@@ -40,6 +40,13 @@ module CommandKit
       # @return [Proc, nil]
       attr_reader :block
 
+      # The optional category to group the option under.
+      #
+      # @return [String, nil]
+      #
+      # @since 0.3.0
+      attr_reader :category
+
       #
       # Initializes the option.
       #
@@ -65,9 +72,12 @@ module CommandKit
       # @option value [String, nil] usage
       #   The usage string for the option's value.
       #
-      # @param [String] desc
+      # @param [String, Array<String>] desc
       #   The description for the option.
       #
+      # @param [String, nil] category
+      #   The optional category to group the option under.
+      #
       # @yield [(value)]
       #   If a block is given, it will be called when the option is parsed.
       #
@@ -78,25 +88,27 @@ module CommandKit
       #   The `value` keyword argument was not a `Hash`, `true`, `false`, or
       #   `nil`.
       #
-      def initialize(name, short:   nil,
-                           long:    self.class.default_long_opt(name),
-                           equals:  false,
-                           value:   nil,
-                           desc:    ,
+      def initialize(name, short:    nil,
+                           long:     self.class.default_long_opt(name),
+                           equals:   false,
+                           value:    nil,
+                           desc:     ,
+                           category: nil,
                            &block)
-        @name    = name
-        @short   = short
-        @long    = long
-        @equals  = equals
-        @value   = case value
-                   when Hash       then OptionValue.new(**value)
-                   when true       then OptionValue.new()
-                   when false, nil then nil
-                   else
-                     raise(TypeError,"value: keyword must be Hash, true, false, or nil")
-                   end
-        @desc    = desc
-        @block   = block
+        @name     = name
+        @short    = short
+        @long     = long
+        @equals   = equals
+        @value    = case value
+                    when Hash       then OptionValue.new(**value)
+                    when true       then OptionValue.new()
+                    when false, nil then nil
+                    else
+                      raise(TypeError,"value: keyword must be Hash, true, false, or nil")
+                    end
+        @desc     = desc
+        @category = category
+        @block    = block
       end
 
       #
@@ -179,7 +191,7 @@ module CommandKit
       #
       # The option description.
       #
-      # @return [String]
+      # @return [String, Array<String>]
       #
       # @note
       #   If {#default_value} returns a value, the description will contain the
@@ -187,7 +199,14 @@ module CommandKit
       #
       def desc
         if (value = default_value)
-          "#{@desc} (Default: #{value})"
+          default_text = "(Default: #{value})"
+
+          case @desc
+          when Array
+            @desc + [default_text]
+          else
+            "#{@desc} #{default_text}"
+          end
         else
           @desc
         end

data/lib/command_kit/options/parser.rb

@@ -78,9 +78,6 @@ module CommandKit
         @option_parser = OptionParser.new do |opts|
           opts.banner = "Usage: #{usage}"
 
-          opts.separator ''
-          opts.separator 'Options:'
-
           opts.on_tail('-h','--help','Print help information') do
             help
             exit(0)

data/lib/command_kit/options.rb

@@ -23,6 +23,25 @@ module CommandKit
   #       @bar = arg.split(':')
   #     end
   #
+  # ### Multi-line Descriptions
+  #
+  #     option :opt, value: {type: String},
+  #                  desc: [
+  #                          'line1',
+  #                          'line2',
+  #                          '...'
+  #                        ]
+  #
+  # ### Option Categories
+  #
+  #     option :opt1, value: {type: String},
+  #                   category: 'Foo Category',
+  #                   desc: 'Option 1'
+  #
+  #     option :opt2, value: {type: String},
+  #                   category: 'Foo Category',
+  #                   desc: 'Option 2'
+  #
   # ### initialize and using instance variables
   #     
   #     option :number, value: {type: Integer},
@@ -111,9 +130,12 @@ module CommandKit
       # @option value [String, nil] usage
       #   The usage string for the option's value.
       #
-      # @option kwargs [String] desc
+      # @option kwargs [String, Array<String>] desc
       #   The description for the option.
       #
+      # @option kwargs [String, nil] category
+      #   The optional category to group the option under.
+      #
       # @yield [(value)]
       #   If a block is given, it will be passed the parsed option value.
       #
@@ -129,6 +151,19 @@ module CommandKit
       # @example Define an option:
       #     option :foo, desc: "Foo option"
       #
+      # @example Define an option with a multi-line description:
+      #     option :foo, desc: [
+      #                          "Line 1",
+      #                          "Line 2"
+      #                        ]
+      #
+      # @example Defines multiple options within a category:
+      #     option :foo, desc: "Foo option",
+      #                  category: 'Other Options'
+      #     
+      #     option :bar, desc: "Bar option",
+      #                  category: 'Other Options'
+      #
       # @example With a custom short option:
       #     option :foo, short: '-f',
       #                  desc: "Foo option"
@@ -212,19 +247,7 @@ module CommandKit
 
       super(**kwargs)
 
-      self.class.options.each_value do |option|
-        default_value = option.default_value
-
-        @options[option.name] = default_value unless default_value.nil?
-
-        option_parser.on(*option.usage,option.type,option.desc) do |arg,*captures|
-          @options[option.name] = arg
-
-          if option.block
-            instance_exec(*arg,*captures,&option.block)
-          end
-        end
-      end
+      define_option_categories
     end
 
     #
@@ -237,5 +260,57 @@ module CommandKit
       help_options
       help_arguments
     end
+
+    private
+
+    #
+    # Defines all of the options, grouped by category.
+    #
+    def define_option_categories
+      categories = self.class.options.values.group_by(&:category)
+
+      categories.each do |category,options|
+        if category
+          define_options_category(category,options)
+        end
+      end
+
+      define_options_category('Options',categories.fetch(nil,[]))
+    end
+
+    #
+    # Defines a new category of options with a header.
+    #
+    # @param [String] category
+    #   The category name.
+    #
+    # @param [Array<Option>, nil] options
+    #   The options to define.
+    #
+    def define_options_category(category,options)
+      option_parser.separator ''
+      option_parser.separator "#{category}:"
+
+      options.each(&method(:define_option))
+    end
+
+    #
+    # Defines an individual option.
+    #
+    # @param [Option] option
+    #
+    def define_option(option)
+      default_value = option.default_value
+
+      @options[option.name] = default_value unless default_value.nil?
+
+      option_parser.on(*option.usage,option.type,option.desc) do |arg,*captures|
+        @options[option.name] = arg
+
+        if option.block
+          instance_exec(*arg,*captures,&option.block)
+        end
+      end
+    end
   end
 end

data/lib/command_kit/program_name.rb

@@ -60,5 +60,14 @@ module CommandKit
     def program_name
       self.class.program_name
     end
+
+    #
+    # @see #program_name
+    #
+    # @since 0.3.0
+    #
+    def command_name
+      program_name
+    end
   end
 end

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/spec/arguments_spec.rb

@@ -233,6 +233,39 @@ describe CommandKit::Arguments do
           ].join($/)
         ).to_stdout
       end
+
+      context "when one the argument has an Array for a description" do
+        module TestArguments
+          class MultiLineArgumentDescription
+            include CommandKit::Arguments
+
+            argument :foo, desc: "Foo option"
+            argument :bar, desc: [
+                                   "Bar option", 
+                                   "Line 2",
+                                   "Line 3"
+                                 ]
+            argument :baz, desc: "Baz option"
+          end
+        end
+
+        let(:command_class) { TestArguments::MultiLineArgumentDescription }
+
+        it "must print out each line of a multi-line argument description" do
+          expect { subject.help_arguments }.to output(
+            [
+              '',
+              "Arguments:",
+              "    #{foo_argument.usage.ljust(33)}#{foo_argument.desc}",
+              "    #{bar_argument.usage.ljust(33)}#{bar_argument.desc[0]}",
+              "    #{' '.ljust(33)}#{bar_argument.desc[1]}",
+              "    #{' '.ljust(33)}#{bar_argument.desc[2]}",
+              "    #{baz_argument.usage.ljust(33)}#{baz_argument.desc}",
+              ''
+            ].join($/)
+          ).to_stdout
+        end
+      end
     end
   end