command_kit 0.3.0 → 0.4.1

data/lib/command_kit/bug_report.rb

@@ -0,0 +1,105 @@
+require 'command_kit/exception_handler'
+require 'command_kit/printing'
+
+module CommandKit
+  #
+  # Adds an exception handler to print a bug report when an unhandled exception
+  # is raised by `run`.
+  #
+  # @since 0.4.0
+  #
+  module BugReport
+    include ExceptionHandler
+    include Printing
+
+    #
+    # @api private
+    #
+    module ModuleMethods
+      #
+      # Extends {ClassMethods} or {ModuleMethods}, depending on whether
+      # {Options} is being included into a class or a module.
+      #
+      # @param [Class, Module] context
+      #   The class or module which is including {Options}.
+      #
+      def included(context)
+        super(context)
+
+        if context.class == Module
+          context.extend ModuleMethods
+        else
+          context.extend ClassMethods
+        end
+      end
+    end
+
+    extend ModuleMethods
+
+    #
+    # Defines class-level methods.
+    #
+    module ClassMethods
+      #
+      # Gets or sets the bug report URL.
+      #
+      # @param [String, nil] new_url
+      #   The new bug report URL.
+      #
+      # @return [String, nil]
+      #   The bug report URL.
+      #
+      # @example
+      #   bug_report_url 'https://github.com/user/repo/issues/new'
+      #
+      def bug_report_url(new_url=nil)
+        if new_url
+          @bug_report_url = new_url
+        else
+          @bug_report_url || if superclass.kind_of?(ClassMethods)
+                               superclass.bug_report_url
+                             end
+        end
+      end
+    end
+
+    #
+    # The bug report URL.
+    #
+    # @return [String, nil]
+    #
+    def bug_report_url
+      self.class.bug_report_url
+    end
+
+    #
+    # Overrides {#on_exception} to print a bug report for unhandled exceptions
+    # and then exit with `-1`.
+    #
+    # @param [Exception] error
+    #   The unhandled exception.
+    #
+    def on_exception(error)
+      print_bug_report(error)
+      exit(-1)
+    end
+
+    #
+    # Prints a bug report for the unhandled exception.
+    #
+    # @param [Exception] error
+    #   The unhandled exception.
+    #
+    def print_bug_report(error)
+      url = bug_report_url
+
+      stderr.puts
+      stderr.puts "Oops! Looks like you have found a bug. Please report it!"
+      stderr.puts url if url
+      stderr.puts
+      stderr.puts '```'
+      print_exception(error)
+      stderr.puts '```'
+    end
+  end
+end

data/lib/command_kit/colors.rb

@@ -998,14 +998,14 @@ module CommandKit
     # @return [Boolean]
     #
     # @note
-    #   When the env variable `TERM` is set to `dumb`, it will disable color
-    #   output. Color output will also be disabled if the given stream is not
-    #   a TTY.
+    #   When the env variable `TERM` is set to `dumb` or when the `NO_COLOR`
+    #   env variable is set, it will disable color output. Color output will
+    #   also be disabled if the given stream is not a TTY.
     #
     # @api public
     #
     def ansi?(stream=stdout)
-      env['TERM'] != 'dumb' && stream.tty?
+      env['TERM'] != 'dumb' && !env['NO_COLOR'] && stream.tty?
     end
 
     #

data/lib/command_kit/edit.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'command_kit/env'
+
+module CommandKit
+  #
+  # Allows invoking the `EDITOR` environment variable.
+  #
+  # ## Environment Variables
+  #
+  # * `EDITOR` - The preferred editor command.
+  #
+  # ## Example
+  #
+  #     if options[:edit]
+  #       edit CONFIG_FILE
+  #     end
+  #
+  # @since 0.4.0
+  #
+  module Edit
+    include Env
+
+    #
+    # The `EDITOR` environment variable.
+    #
+    # @return [String]
+    #   The `EDITOR` environment variable, or `"nano"` if `EDITOR` was not set.
+    #
+    # @api semipublic
+    #
+    def editor
+      env['EDITOR'] || 'nano'
+    end
+
+    #
+    # Invokes the preferred editor with the additional arguments.
+    #
+    # @param [Array] arguments
+    #   The additional arguments to pass to the editor command.
+    #
+    # @return [Boolean, nil]
+    #   Indicates whether the editor successfully launched and exited.
+    #   If the {#editor} command was not installed, `nil` will be returned.
+    #
+    # @api public
+    #
+    def edit(*arguments)
+      if editor
+        system(editor,*arguments.map(&:to_s))
+      end
+    end
+  end
+end

data/lib/command_kit/env/home.rb

@@ -20,7 +20,7 @@ module CommandKit
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
-        # {Env::Home} is being included into a class or a module..
+        # {Env::Home} is being included into a class or a module.
         #
         # @param [Class, Module] context
         #   The class or module which is including {Home}.

data/lib/command_kit/env.rb

@@ -7,7 +7,7 @@ module CommandKit
   #     class MyCmd
   #       include CommandKit::Env
   #
-  #       def main
+  #       def run
   #         home = env['HOME']
   #         # ...
   #       end

data/lib/command_kit/inflector.rb

@@ -103,7 +103,7 @@ module CommandKit
           new_string << word
         elsif scanner.scan(/[_-]+/)
           # skip
-        elsif scanner.scan(/\//)
+        elsif scanner.scan(%r{/})
           new_string << '::'
         else
           raise(ArgumentError,"cannot convert string to CamelCase: #{scanner.string.inspect}")

data/lib/command_kit/options/option.rb

@@ -154,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
 
       #

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
@@ -50,7 +50,7 @@ module CommandKit
 
           if context.class == Module
             context.extend ModuleMethods
-          else
+          elsif context.usage.nil?
             context.usage '[options]'
           end
         end

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

@@ -247,7 +247,7 @@ module CommandKit
 
       super(**kwargs)
 
-      define_option_categories
+      define_option_categories()
     end
 
     #

data/lib/command_kit/os/linux.rb

@@ -36,7 +36,7 @@ module CommandKit
       module ModuleMethods
         #
         # Extends {ClassMethods} or {ModuleMethods}, depending on whether
-        # {OS} is being included into a class or a module..
+        # {OS} is being included into a class or a module.
         #
         # @param [Class, Module] context
         #   The class or module which is including {OS}.

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?
@@ -32,7 +32,7 @@ module CommandKit
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
-      # {OS} is being included into a class or a module..
+      # {OS} is being included into a class or a module.
       #
       # @param [Class, Module] context
       #   The class or module which is including {OS}.

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

data/lib/command_kit/printing/tables/border_style.rb

@@ -0,0 +1,169 @@
+module CommandKit
+  module Printing
+    module Tables
+      #
+      # Represents the table's border style.
+      #
+      # @api private
+      #
+      class BorderStyle
+
+        # The top-left-corner border character.
+        #
+        # @return [String]
+        attr_reader :top_left_corner
+
+        # The top-border character.
+        #
+        # @return [String]
+        attr_reader :top_border
+
+        # The top-joined-border character.
+        #
+        # @return [String]
+        attr_reader :top_joined_border
+
+        # The top-right-corner border character.
+        #
+        # @return [String]
+        attr_reader :top_right_corner
+
+        # The left-hand-side border character.
+        #
+        # @return [String]
+        attr_reader :left_border
+
+        # The left-hand-side-joined-border character.
+        #
+        # @return [String]
+        attr_reader :left_joined_border
+
+        # The horizontal-separator character.
+        #
+        # @return [String]
+        attr_reader :horizontal_separator
+
+        # The vertical-separator character.
+        #
+        # @return [String]
+        attr_reader :vertical_separator
+
+        # The inner-joined border character.
+        #
+        # @return [String]
+        attr_reader :inner_joined_border
+
+        # The right-hand-side border character.
+        #
+        # @return [String]
+        attr_reader :right_border
+
+        # The right-hand-side joined border character.
+        #
+        # @return [String]
+        attr_reader :right_joined_border
+
+        # The bottom border character.
+        #
+        # @return [String]
+        attr_reader :bottom_border
+
+        # The bottom-left-corner border character.
+        #
+        # @return [String]
+        attr_reader :bottom_left_corner
+
+        # The bottom-joined border character.
+        #
+        # @return [String]
+        attr_reader :bottom_joined_border
+
+        # The bottom-right-corner border character.
+        #
+        # @return [String]
+        attr_reader :bottom_right_corner
+
+        #
+        # Initializes the border style.
+        #
+        # @param [String] top_left_corner
+        #   The top-left-corner border character.
+        #
+        # @param [String] top_border
+        # The top-border character.
+        #
+        # @param [String] top_joined_border
+        #   The top-joined-border character.
+        #
+        # @param [String] top_right_corner
+        #   The top-right-corner border character.
+        #
+        # @param [String] left_border
+        #   The left-hand-side border character.
+        #
+        # @param [String] left_joined_border
+        #   The left-hand-side-joined-border character.
+        #
+        # @param [String] horizontal_separator
+        #   The horizontal-separator character.
+        #
+        # @param [String] vertical_separator
+        #   The vertical-separator character.
+        #
+        # @param [String] inner_joined_border
+        #   The inner-joined border character.
+        #
+        # @param [String] right_border
+        #   The right-hand-side border character.
+        #
+        # @param [String] right_joined_border
+        #   The right-hand-side joined border character.
+        #
+        # @param [String] bottom_border
+        #   The bottom border character.
+        #
+        # @param [String] bottom_left_corner
+        #   The bottom-left-corner border character.
+        #
+        # @param [String] bottom_joined_border
+        #   The bottom-joined border character.
+        #
+        # @param [String] bottom_right_corner
+        #   The bottom-right-corner border character.
+        #
+        def initialize(top_left_corner:      ' ',
+                       top_border:           ' ',
+                       top_joined_border:    ' ',
+                       top_right_corner:     ' ',
+                       left_border:          ' ',
+                       left_joined_border:   ' ',
+                       horizontal_separator: ' ',
+                       vertical_separator:   ' ',
+                       inner_joined_border:  ' ',
+                       right_border:         ' ',
+                       right_joined_border:  ' ',
+                       bottom_border:        ' ',
+                       bottom_left_corner:   ' ',
+                       bottom_joined_border: ' ',
+                       bottom_right_corner:  ' ')
+          @top_left_corner      = top_left_corner
+          @top_border           = top_border
+          @top_joined_border    = top_joined_border
+          @top_right_corner     = top_right_corner
+          @left_border          = left_border
+          @left_joined_border   = left_joined_border
+          @horizontal_separator = horizontal_separator
+          @vertical_separator   = vertical_separator
+          @inner_joined_border  = inner_joined_border
+          @right_border         = right_border
+          @right_joined_border  = right_joined_border
+          @bottom_border        = bottom_border
+          @bottom_left_corner   = bottom_left_corner
+          @bottom_joined_border = bottom_joined_border
+          @bottom_right_corner  = bottom_right_corner
+        end
+
+      end
+    end
+  end
+end