command_kit 0.2.2 → 0.4.0

data/lib/command_kit/file_utils.rb

@@ -0,0 +1,46 @@
+require 'fileutils'
+require 'erb'
+
+module CommandKit
+  #
+  # File manipulation related methods.
+  #
+  # @since 0.3.0
+  #
+  # @api public
+  #
+  module FileUtils
+    include ::FileUtils
+
+    #
+    # Renders an erb file and optionally writes it out to a destination file.
+    #
+    # @param [String] source
+    #   The path to the erb template file.
+    #
+    # @param [String, nil] dest
+    #   The path to the destination file.
+    #
+    # @return [String, nil]
+    #   If no destination path argument is given, the rendered erb template
+    #   String will be returned.
+    #
+    # @example Rendering a ERB template and saving it's output:
+    #   erb File.join(template_dir,'README.md.erb'), 'README.md'
+    #
+    # @example Rendering a ERB template and capturing it's output:
+    #   output = erb(File.join(template_dir,'_partial.erb'))
+    #
+    def erb(source,dest=nil)
+      erb    = ERB.new(File.read(source), trim_mode: '-')
+      result = erb.result(binding)
+
+      if dest
+        File.write(dest,result)
+        return
+      else
+        return result
+      end
+    end
+  end
+end

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
 
       #
@@ -142,7 +154,11 @@ module CommandKit
       #   The usage strings.
       #
       def usage
-        [*@short, "#{@long}#{separator}#{@value && @value.usage}"]
+        if equals? && (@value && @value.optional?)
+          [*@short, "#{@long}[#{separator}#{@value && @value.usage}]"]
+        else
+          [*@short, "#{@long}#{separator}#{@value && @value.usage}"]
+        end
       end
 
       #
@@ -179,7 +195,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 +203,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/option_value.rb

@@ -19,7 +19,7 @@ module CommandKit
     class OptionValue < Arguments::ArgumentValue
 
       # Maps OptionParser types to USAGE strings.
-      USAGES = {
+      DEFAULT_USAGES = {
         # NOTE: NilClass and Object are intentionally omitted
         Date       => 'DATE',
         DateTime   => 'DATE_TIME',
@@ -90,7 +90,7 @@ module CommandKit
       #   The given type was not a Class, Hash, Array, or Regexp.
       #
       def self.default_usage(type)
-        USAGES.fetch(type) do
+        DEFAULT_USAGES.fetch(type) do
           case type
           when Hash   then type.keys.join('|')
           when Array  then type.join('|')

data/lib/command_kit/options/parser.rb

@@ -22,7 +22,7 @@ module CommandKit
     #       end
     #     end
     #     
-    #     def main(*argv)
+    #     def run(*argv)
     #       if @custom
     #         puts "Custom mode enabled"
     #       end
@@ -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/quiet.rb

@@ -9,7 +9,7 @@ module CommandKit
     #
     #     include CommandKit::Options::Quiet
     #     
-    #     def main(*argv)
+    #     def run(*argv)
     #       # ...
     #       puts "verbose output" unless quiet?
     #       # ...

data/lib/command_kit/options/verbose.rb

@@ -7,9 +7,9 @@ module CommandKit
     #
     # ## Examples
     #
-    #     include Options::Verbose
+    #     include CommandKit::Options::Verbose
     #
-    #     def main(*argv)
+    #     def run(*argv)
     #       # ...
     #       puts "verbose output" if verbose?
     #       # ...

data/lib/command_kit/options/version.rb

@@ -5,6 +5,16 @@ module CommandKit
     #
     # Defines a version option.
     #
+    # ## Examples
+    #
+    #     include CommandKit::Options::Version
+    #     
+    #     version '0.1.0'
+    #     
+    #     def run(*argv)
+    #       # ...
+    #     end
+    #
     module Version
       #
       # Includes {Options}, extends {Version::ClassMethods}, and defines a

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/os.rb

@@ -11,7 +11,7 @@ module CommandKit
   #     
   #       include CommandKit::OS
   #     
-  #       def main(*argv)
+  #       def run(*argv)
   #         if linux?
   #           # ...
   #         elsif macos?

data/lib/command_kit/printing/fields.rb

@@ -0,0 +1,56 @@
+require 'command_kit/printing/indent'
+
+module CommandKit
+  module Printing
+    #
+    # Supports printing aligned key/value fields.
+    #
+    # @since 0.4.0
+    #
+    module Fields
+      include Indent
+
+      #
+      # Prints a Hash as left-justified `:` separated fields.
+      #
+      # @param [Hash, Array<(Object, Object)>] fields
+      #   The fields to print.
+      #
+      # @example
+      #   print_fields('Name' => 'foo', 'Version' => '0.1.0')
+      #   # Name:    foo
+      #   # Version: 0.1.0
+      #
+      # @api public
+      #
+      def print_fields(fields)
+        max_length = 0
+
+        fields = fields.map { |name,value|
+          name       = name.to_s
+          value      = value.to_s
+          max_length = name.length if name.length > max_length
+
+          [name, value]
+        }
+
+        fields.each do |name,value|
+          first_line, *rest = value.to_s.lines(chomp: true)
+
+          # print the first line with the header
+          header = "#{name}:".ljust(max_length + 1)
+          puts "#{header} #{first_line}"
+
+          # indent and print the rest of the lines
+          indent(max_length + 2) do
+            rest.each do |line|
+              puts line
+            end
+          end
+        end
+
+        return nil
+      end
+    end
+  end
+end

data/lib/command_kit/printing/indent.rb

@@ -7,7 +7,7 @@ module CommandKit
     #
     #     include Printing::Indent
     #     
-    #     def main
+    #     def run
     #       puts "regular output:"
     #     
     #       indent(4) do

data/lib/command_kit/printing/lists.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'command_kit/printing/indent'
+
+module CommandKit
+  module Printing
+    #
+    # Methods for printing lists.
+    #
+    # ## Examples
+    #
+    #     include Printing::Lists
+    #     
+    #     def main
+    #       print_list %w[foo bar baz]
+    #       # * foo
+    #       # * bar
+    #       # * baz
+    #
+    #       list = ['item 1', 'item 2', ['sub-item 1', 'sub-item 2']]
+    #       print_list(list)
+    #       # * item 1
+    #       # * item 2
+    #       #   * sub-item 1
+    #       #   * sub-item 2
+    #
+    #       print_list %w[foo bar baz], bullet: '-'
+    #       # - foo
+    #       # - bar
+    #       # - baz
+    #     end
+    #
+    # @since 0.4.0
+    #
+    module Lists
+      include Indent
+
+      #
+      # Prints a bulleted list of items.
+      #
+      # @param [Array<#to_s, Array>] list
+      #   The list of items to print.
+      #
+      # @param [String] bullet
+      #   The bullet character to use for line item.
+      #
+      # @example
+      #   print_list %w[foo bar baz]
+      #   # * foo
+      #   # * bar
+      #   # * baz
+      #
+      # @example print a nested list:
+      #   list = ['item 1', 'item 2', ['sub-item 1', 'sub-item 2']]
+      #   print_list(list)
+      #   # * item 1
+      #   # * item 2
+      #   #   * sub-item 1
+      #   #   * sub-item 2
+      #
+      # @example with a custom bullet character:
+      #   print_list %w[foo bar baz], bullet: '-'
+      #   # - foo
+      #   # - bar
+      #   # - baz
+      #
+      # @since 0.4.0
+      #
+      def print_list(list, bullet: '*')
+        list.each do |item|
+          case item
+          when Array
+            indent { print_list(item, bullet: bullet) }
+          else
+            first_line, *rest = item.to_s.lines(chomp: true)
+
+            # print the bullet only on the first list
+            puts "#{bullet} #{first_line}"
+
+            # indent the remaining lines
+            indent(bullet.length + 1) do
+              rest.each do |line|
+                puts line
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end