command_kit 0.1.0.pre1 → 0.2.0

data/lib/command_kit/colors.rb

@@ -26,7 +26,7 @@ module CommandKit
   #
   # ## Alternatives
   #
-  # * [ansi](http://rubyworks.github.io/ansi/)
+  # * [ansi](https://rubyworks.github.io/ansi/)
   # * [colorize](https://github.com/fazibear/colorize#readme)
   #
   # @see https://en.wikipedia.org/wiki/ANSI_escape_code
@@ -67,7 +67,7 @@ module CommandKit
       # ANSI color code for blue
       BLUE = "\e[34m"
 
-      # ANSI color code for megenta
+      # ANSI color code for magenta
       MAGENTA = "\e[35m"
 
       # ANSI color code for cyan
@@ -79,6 +79,51 @@ module CommandKit
       # ANSI color for the default foreground color
       RESET_COLOR = "\e[39m"
 
+      # ANSI color code for background color black
+      #
+      # @since 0.2.0
+      ON_BLACK = "\e[40m"
+
+      # ANSI color code for background color red
+      #
+      # @since 0.2.0
+      ON_RED = "\e[41m"
+
+      # ANSI color code for background color green
+      #
+      # @since 0.2.0
+      ON_GREEN = "\e[42m"
+
+      # ANSI color code for background color yellow
+      #
+      # @since 0.2.0
+      ON_YELLOW = "\e[43m"
+
+      # ANSI color code for background color blue
+      #
+      # @since 0.2.0
+      ON_BLUE = "\e[44m"
+
+      # ANSI color code for background color megenta
+      #
+      # @since 0.2.0
+      ON_MAGENTA = "\e[45m"
+
+      # ANSI color code for background color cyan
+      #
+      # @since 0.2.0
+      ON_CYAN = "\e[46m"
+
+      # ANSI color code for background color white
+      #
+      # @since 0.2.0
+      ON_WHITE = "\e[47m"
+
+      # ANSI color for the default background color
+      #
+      # @since 0.2.0
+      RESET_BG = "\e[49m"
+
       module_function
 
       #
@@ -88,6 +133,8 @@ module CommandKit
       #
       # @see RESET
       #
+      # @api public
+      #
       def reset
         RESET
       end
@@ -95,6 +142,8 @@ module CommandKit
       #
       # @see reset
       #
+      # @api public
+      #
       def clear
         reset
       end
@@ -110,6 +159,8 @@ module CommandKit
       #
       # @see BOLD
       #
+      # @api public
+      #
       def bold(string=nil)
         if string then "#{BOLD}#{string}#{RESET_INTENSITY}"
         else           BOLD
@@ -127,6 +178,8 @@ module CommandKit
       #
       # @see BLACK
       #
+      # @api public
+      #
       def black(string=nil)
         if string then "#{BLACK}#{string}#{RESET_COLOR}"
         else           BLACK
@@ -144,6 +197,8 @@ module CommandKit
       #
       # @see RED
       #
+      # @api public
+      #
       def red(string=nil)
         if string then "#{RED}#{string}#{RESET_COLOR}"
         else           RED
@@ -161,6 +216,8 @@ module CommandKit
       #
       # @see GREEN
       #
+      # @api public
+      #
       def green(string=nil)
         if string then "#{GREEN}#{string}#{RESET_COLOR}"
         else           GREEN
@@ -178,6 +235,8 @@ module CommandKit
       #
       # @see YELLOW
       #
+      # @api public
+      #
       def yellow(string=nil)
         if string then "#{YELLOW}#{string}#{RESET_COLOR}"
         else           YELLOW
@@ -195,6 +254,8 @@ module CommandKit
       #
       # @see BLUE
       #
+      # @api public
+      #
       def blue(string=nil)
         if string then "#{BLUE}#{string}#{RESET_COLOR}"
         else           BLUE
@@ -212,6 +273,8 @@ module CommandKit
       #
       # @see MAGENTA
       #
+      # @api public
+      #
       def magenta(string=nil)
         if string then "#{MAGENTA}#{string}#{RESET_COLOR}"
         else           MAGENTA
@@ -229,6 +292,8 @@ module CommandKit
       #
       # @see CYAN
       #
+      # @api public
+      #
       def cyan(string=nil)
         if string then "#{CYAN}#{string}#{RESET_COLOR}"
         else           CYAN
@@ -246,76 +311,209 @@ module CommandKit
       #
       # @see WHITE
       #
+      # @api public
+      #
       def white(string=nil)
         if string then "#{WHITE}#{string}#{RESET_COLOR}"
         else           WHITE
         end
       end
-    end
 
-    #
-    # Dummy module with the same interface as {ANSI}, but for when ANSI is not
-    # supported.
-    #
-    module PlainText
-      RESET = \
-        CLEAR = \
-        BOLD = \
-        RESET_INTENSITY = \
-        BLACK = \
-        RED = \
-        GREEN = \
-        YELLOW = \
-        BLUE = \
-        MAGENTA = \
-        CYAN = \
-        WHITE = \
-        RESET_COLOR = ''
-
-      module_function
+      #
+      # Sets the background color to black.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_BLACK]
+      #   The colorized string or just {ON_BLACK} if no arguments were given.
+      #
+      # @see ON_BLACK
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_black(string=nil)
+        if string then "#{ON_BLACK}#{string}#{RESET_BG}"
+        else           ON_BLACK
+        end
+      end
 
-      def reset
-        RESET
+      #
+      # Sets the background color to red.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_RED]
+      #   The colorized string or just {ON_RED} if no arguments were given.
+      #
+      # @see ON_RED
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_red(string=nil)
+        if string then "#{ON_RED}#{string}#{RESET_BG}"
+        else           ON_RED
+        end
       end
 
-      def clear
-        reset
+      #
+      # Sets the background color to green.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_GREEN]
+      #   The colorized string or just {ON_GREEN} if no arguments were given.
+      #
+      # @see ON_GREEN
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_green(string=nil)
+        if string then "#{ON_GREEN}#{string}#{RESET_BG}"
+        else           ON_GREEN
+        end
       end
 
-      def bold(string=nil)
-        string || ''
+      #
+      # Sets the background color to yellow.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_YELLOW]
+      #   The colorized string or just {ON_YELLOW} if no arguments were given.
+      #
+      # @see ON_YELLOW
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_yellow(string=nil)
+        if string then "#{ON_YELLOW}#{string}#{RESET_BG}"
+        else           ON_YELLOW
+        end
       end
 
-      def black(string=nil)
-        string || ''
+      #
+      # Sets the background color to blue.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_BLUE]
+      #   The colorized string or just {ON_BLUE} if no arguments were given.
+      #
+      # @see ON_BLUE
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_blue(string=nil)
+        if string then "#{ON_BLUE}#{string}#{RESET_BG}"
+        else           ON_BLUE
+        end
       end
 
-      def red(string=nil)
-        string || ''
+      #
+      # Sets the background color to magenta.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_MAGENTA]
+      #   The colorized string or just {ON_MAGENTA} if no arguments were given.
+      #
+      # @see ON_MAGENTA
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_magenta(string=nil)
+        if string then "#{ON_MAGENTA}#{string}#{RESET_BG}"
+        else           ON_MAGENTA
+        end
       end
 
-      def green(string=nil)
-        string || ''
+      #
+      # Sets the background color to cyan.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_CYAN]
+      #   The colorized string or just {ON_CYAN} if no arguments were given.
+      #
+      # @see ON_CYAN
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_cyan(string=nil)
+        if string then "#{ON_CYAN}#{string}#{RESET_BG}"
+        else           ON_CYAN
+        end
       end
 
-      def yellow(string=nil)
-        string || ''
+      #
+      # Sets the background color to white.
+      #
+      # @param [String, nil] string
+      #   An optional string.
+      #
+      # @return [String, ON_WHITE]
+      #   The colorized string or just {ON_WHITE} if no arguments were given.
+      #
+      # @see ON_WHITE
+      #
+      # @api public
+      #
+      # @since 0.2.0
+      #
+      def on_white(string=nil)
+        if string then "#{ON_WHITE}#{string}#{RESET_BG}"
+        else           ON_WHITE
+        end
       end
+    end
 
-      def blue(string=nil)
-        string || ''
+    #
+    # Dummy module with the same interface as {ANSI}, but for when ANSI is not
+    # supported.
+    #
+    module PlainText
+      ANSI.constants(false).each do |name|
+        const_set(name,'')
       end
 
-      def magenta(string=nil)
-        string || ''
+      module_function
+
+      def reset
+        RESET
       end
 
-      def cyan(string=nil)
-        string || ''
+      def clear
+        reset
       end
 
-      def white(string=nil)
-        string || ''
+      [
+        :bold, :black, :red, :green, :yellow, :blue, :magenta, :cyan, :white,
+        :on_black, :on_red, :on_green, :on_yellow, :on_blue, :on_magenta, :on_cyan, :on_white
+      ].each do |name|
+        define_method(name) do |string=nil|
+          string || ''
+        end
       end
     end
 
@@ -331,6 +529,8 @@ module CommandKit
     #   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?
     end
@@ -343,6 +543,14 @@ module CommandKit
     # @return [ANSI, PlainText]
     #   The ANSI module or PlainText dummy module.
     #
+    # @example
+    #   puts colors.green("Hello world")
+    #
+    # @example Using colors with stderr output:
+    #   stderr.puts colors(stderr).green("Hello world")
+    #
+    # @api public
+    #
     def colors(stream=stdout)
       color = if ansi?(stream) then ANSI
               else                  PlainText

data/lib/command_kit/command.rb

@@ -9,20 +9,66 @@ require 'command_kit/examples'
 require 'command_kit/description'
 require 'command_kit/exception_handler'
 
+require 'fileutils'
+
 module CommandKit
   #
   # The command class base-class.
   #
+  # @note
+  #   Command classes are not required to inherit from {Command}. If you do not
+  #   wish to inherit from the {Command} base class, you can instead include
+  #   the individual modules. This class only exists as a convenience.
+  #
   # ## Examples
   #
   #     class MyCmd < CommandKit::Command
   #     
-  #       # ...
+  #       usage '[OPTIONS] [-o OUTPUT] FILE'
+  #     
+  #       option :count, short: '-c',
+  #                      value: {
+  #                        type: Integer,
+  #                        default: 1
+  #                      },
+  #                      desc: "Number of times"
+  #     
+  #       option :output, short: '-o',
+  #                       value: {
+  #                         type: String,
+  #                         usage: 'FILE'
+  #                       },
+  #                       desc: "Optional output file"
+  #     
+  #       argument :file, required: true,
+  #                       usage: 'FILE',
+  #                       desc: "Input file"
+  #     
+  #       examples [
+  #         '-o path/to/output.txt path/to/input.txt',
+  #         '-v -c 2 -o path/to/output.txt path/to/input.txt',
+  #       ]
+  #     
+  #       description 'Example command'
+  #     
+  #       def run(*files)
+  #         # ...
+  #       end
+  #     end
+  #
+  # ### initialize and using instance variables
+  #
+  #     option :verbose, short: '-v', desc: "Increase verbose level" do
+  #       @verbose += 1
+  #     end
+  # 
+  #     def initialize(**kwargs)
+  #       super(**kwargs)
   #     
+  #       @verbose = 0
   #     end
   #
-  # @note Command classes are not required to inherit from {Command}. This class
-  # only exists as a convenience.
+  # @api public
   #
   class Command
 
@@ -37,6 +83,7 @@ module CommandKit
     include Examples
     include Description
     include ExceptionHandler
+    include FileUtils
 
   end
 end