claide 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c48ac46a6dd1a3d4b6e9b31d6e7e0a9b4697ecc7
-  data.tar.gz: aafaf22c16450580a41154a005103b321654fddf
+  metadata.gz: cc7d7f59268bec92fc656c3999c983c819b16b74
+  data.tar.gz: c1b9b2bce23334941e832dee7aa7f19a7ebb85c0
 SHA512:
-  metadata.gz: 9f2a2db1a5e9632761d90bd3486376fe856b6f4012f69391ea093b810c3883cd1f8b9b1b271f42bec2b3b105ba2ef3a14adf1a07ec2fa45f97edb6785f0dedaf
-  data.tar.gz: ee607530bb899f4a376bcb6a262a9dbf8bd7790cf85a568f99234ad156249f23e38f5f2cd9f364da6c626ef9fba0501c0c8277b9508cce99cc34f835462288cc
+  metadata.gz: 171f3513817794fea26279c20f65a9d8cf71ab03edce821e428b86e363ebb75f69de418097c8a67a3415cd755b26f867e7c0b626944cc9c7a590e07a69b944ce
+  data.tar.gz: 1949a384b568d4fa1722696827dc66059b3641dc932bdff88ec57721ca48434c15ad7920efbbd632eb8df74f09b1d7373a72b95fce5570aff52f20c0910def64

data/README.markdown

@@ -1,12 +1,13 @@
 # Hi, I’m Claide, your command-line tool aide.
 
+[![Build Status](https://img.shields.io/travis/CocoaPods/CLAide/master.svg?style=flat)](https://travis-ci.org/CocoaPods/CLAide)
+[![Code Climate](https://img.shields.io/codeclimate/github/CocoaPods/CLAide.svg?style=flat)](https://codeclimate.com/github/CocoaPods/CLAide)
+[![Coverage](https://img.shields.io/codeclimate/coverage/github/CocoaPods/CLAide.svg?style=flat)](https://codeclimate.com/github/CocoaPods/CLAide)
+
 I was born out of a need for a _simple_ option and command parser, while still
 providing an API that allows you to quickly create a full featured command-line
 interface.
 
-[![Build Status][travis-status]][travis]
-
-
 ## Install
 
 ```

data/lib/claide.rb

@@ -4,16 +4,17 @@
 # {CLAide::InformativeError}
 #
 module CLAide
-
   # @return [String]
   #
   #   CLAide’s version, following [semver](http://semver.org).
   #
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 
+  require 'claide/ansi'
   require 'claide/argv'
   require 'claide/command'
   require 'claide/help'
+  require 'claide/helper'
   require 'claide/informative_error'
-
+  require 'claide/mixins'
 end

data/lib/claide/ansi.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+
+require 'claide/ansi/cursor'
+require 'claide/ansi/graphics'
+
+module CLAide
+  # Provides support for ANSI Escape sequences
+  #
+  # For more information see:
+  #
+  # - http://ascii-table.com/ansi-escape-sequences.php
+  # - http://en.wikipedia.org/wiki/ANSI_escape_code
+  #
+  # This functionality has been inspired and derived from the following gems:
+  #
+  # - colored
+  # - colorize
+  #
+  class ANSI
+    extend Cursor
+    extend Graphics
+
+    class << self
+      # @return [Bool] Wether the string mixin should be disabled to return the
+      # original string. This method is intended to offer a central location
+      # where to disable ANSI logic without needed to implement conditionals
+      # across the code base of clients.
+      #
+      # @example
+      #
+      #   "example".ansi.yellow #=> "\e[33mexample\e[39m"
+      #   ANSI.disabled = true
+      #   "example".ansi.yellow #=> "example"
+      #
+      attr_accessor :disabled
+    end
+
+    # @return [Hash{Symbol => Fixnum}] The text attributes codes by their
+    #         English name.
+    #
+    TEXT_ATTRIBUTES = {
+      :bold       => 1,
+      :underline  => 4,
+      :blink      => 5,
+      :reverse    => 7,
+      :hidden     => 8
+    }
+
+    # @return [Hash{Symbol => Fixnum}] The codes to disable a text attribute by
+    #         their name.
+    #
+    TEXT_DISABLE_ATTRIBUTES = {
+      :bold       => 21,
+      :underline  => 24,
+      :blink      => 25,
+      :reverse    => 27,
+      :hidden     => 28
+    }
+
+    # Return [String] The escape sequence to reset the graphics.
+    #
+    RESET_SEQUENCE = "\e[0m"
+
+    # @return [Hash{Symbol => Fixnum}] The colors codes by their English name.
+    #
+    COLORS = {
+      :black      => 0,
+      :red        => 1,
+      :green      => 2,
+      :yellow     => 3,
+      :blue       => 4,
+      :magenta    => 5,
+      :cyan       => 6,
+      :white      => 7
+    }
+
+    # Return [String] The escape sequence for the default foreground color.
+    #
+    DEFAULT_FOREGROUND_COLOR = "\e[39m"
+
+    # Return [String] The escape sequence for the default background color.
+    #
+    DEFAULT_BACKGROUND_COLOR = "\e[49m"
+
+    # @return [Fixnum] The code of a key given the map.
+    #
+    # @param  [Symbol] key
+    #         The key for which the code is needed.
+    #
+    # @param  [Hash{Symbol => Fixnum}] map
+    #         A hash which associates each code to each key.
+    #
+    # @raise  If the key is not provided.
+    # @raise  If the key is not present in the map.
+    #
+    def self.code_for_key(key, map)
+      unless key
+        raise ArgumentError, 'A key must be provided'
+      end
+      code = map[key]
+      unless code
+        raise ArgumentError, "Unsupported key: `#{key}`"
+      end
+      code
+    end
+  end
+end
+
+#-- String mixin -------------------------------------------------------------#
+
+require 'claide/ansi/string_escaper'
+
+class String
+  # @return [StringEscaper] An object which provides convenience methods to
+  #         wrap the receiver in ANSI sequences.
+  #
+  # @example
+  #
+  #   "example".ansi.yellow #=> "\e[33mexample\e[39m"
+  #   "example".ansi.on_red #=> "\e[41mexample\e[49m"
+  #   "example".ansi.bold   #=> "\e[1mexample\e[21m"
+  #
+  def ansi
+    CLAide::ANSI::StringEscaper.new(self)
+  end
+end

data/lib/claide/ansi/cursor.rb

@@ -0,0 +1,69 @@
+# encoding: utf-8
+
+module CLAide
+  class ANSI
+    # Provides support for generating escape sequences relative to the position
+    # of the cursor and to erase parts of text.
+    #
+    module Cursor
+      # @return [String] The escape sequence to set the cursor at the
+      #         given line.
+      #
+      # @param  [Fixnum] line
+      #         The line where to place the cursor.
+      #
+      # @param  [Fixnum] column
+      #         The column where to place the cursor.
+      #
+      def self.set_cursor_position(line = 0, column = 0)
+        "\e[#{line};#{column}H"
+      end
+
+      # @return [String] The escape sequence to set the cursor at the
+      #         given line.
+      #
+      # @param  [Fixnum] lines
+      #         The amount of lines the cursor should be moved to.
+      #         Negative values indicate up direction and positive ones
+      #         down direction.
+      #
+      # @param  [Fixnum] columns
+      #         The amount of columns the cursor should be moved to.
+      #         Negative values indicate left direction and positive ones
+      #         right direction.
+      #
+      def self.move_cursor(lines, columns = 0)
+        lines_code = lines < 0 ? 'A' : 'B'
+        columns_code = columns > 0 ? 'C' : 'D'
+        "\e[#{lines.abs}#{lines_code};#{columns.abs}#{columns_code}"
+      end
+
+      # @return [String] The escape sequence to save the cursor position.
+      #
+      def self.save_cursor_position
+        "\e[s"
+      end
+
+      # @return [String] The escape sequence to restore the cursor to the
+      #         previously saved position. This sequence also clears all the
+      #         output after the position.
+      #
+      def self.restore_cursor_position
+        "\e[u"
+      end
+
+      # @return [String] The escape sequence to erase the display.
+      #
+      def self.erase_display
+        "\e[2J"
+      end
+
+      # @return [String] The escape sequence to erase a line form the
+      #         cursor position to then end.
+      #
+      def self.erase_line
+        "\e[K"
+      end
+    end
+  end
+end

data/lib/claide/ansi/graphics.rb

@@ -0,0 +1,72 @@
+# encoding: utf-8
+
+module CLAide
+  class ANSI
+    # Provides support for generating escape sequences relative to the graphic
+    # mode.
+    #
+    module Graphics
+      # @return [String] The escape sequence for a text attribute.
+      #
+      # @param  [Symbol] key
+      #         The name of the text attribute.
+      #
+      def self.text_attribute(key)
+        code = ANSI.code_for_key(key, TEXT_ATTRIBUTES)
+        graphics_mode(code)
+      end
+
+      # @return [String] The escape sequence for a foreground color.
+      #
+      # @param  [Symbol] key
+      #         The name of the color.
+      #
+      def self.foreground_color(key)
+        code = ANSI.code_for_key(key, COLORS) + 30
+        graphics_mode(code)
+      end
+
+      # @return [String] The escape sequence for a background color.
+      #
+      # @param  [Symbol] key
+      #         The name of the color.
+      #
+      def self.background_color(key)
+        code = ANSI.code_for_key(key, COLORS) + 40
+        graphics_mode(code)
+      end
+
+      # @return [String] The escape sequence for a foreground color using the
+      #         xterm-256 format.
+      #
+      # @param  [Fixnum] key
+      #         The value of the color.
+      #
+      def self.foreground_color_256(color)
+        code = [38, 5, color]
+        graphics_mode(code)
+      end
+
+      # @return [String] The escape sequence for a background color using the
+      #         xterm-256 format.
+      #
+      # @param  [Fixnum] key
+      #         The value of the color.
+      #
+      def self.background_color_256(color)
+        code = [48, 5, color]
+        graphics_mode(code)
+      end
+
+      # @return [String] The escape sequence for a single or a list of codes.
+      #
+      # @param  [Fixnum, Array<Fixnum>] codes
+      #         The code(s).
+      #
+      def self.graphics_mode(codes)
+        codes = Array(codes)
+        "\e[#{codes.join(';')}m"
+      end
+    end
+  end
+end

data/lib/claide/ansi/string_escaper.rb

@@ -0,0 +1,81 @@
+require 'claide/ansi'
+
+module CLAide
+  class ANSI
+    # Provides support to wrap strings in ANSI sequences according to the
+    # `ANSI.disabled` setting.
+    #
+    class StringEscaper < String
+      # @param  [String] The string to wrap.
+      #
+      def initialize(string)
+        super
+      end
+
+      # @return [StringEscaper] Wraps a string in the given ANSI sequences,
+      #         taking care of handling existing sequences for the same
+      #         family of attributes (i.e. attributes terminated by the
+      #         same sequence).
+      #
+      def wrap_in_ansi_sequence(open, close)
+        if ANSI.disabled
+          self
+        else
+          gsub!(close, open)
+          insert(0, open).insert(-1, close)
+        end
+      end
+
+      # @return [StringEscaper]
+      #
+      # @param  [Array<Symbol>] keys
+      #         One or more keys corresponding to ANSI codes to apply to the
+      #         string.
+      #
+      def apply(*keys)
+        keys.flatten.each do |key|
+          send(key)
+        end
+        self
+      end
+
+      ANSI::COLORS.each_key do |key|
+        # Defines a method returns a copy of the receiver wrapped in an ANSI
+        # sequence for each foreground color (e.g. #blue).
+        #
+        # The methods handle nesting of ANSI sequences.
+        #
+        define_method key do
+          open = Graphics.foreground_color(key)
+          close = ANSI::DEFAULT_FOREGROUND_COLOR
+          wrap_in_ansi_sequence(open, close)
+        end
+
+        # Defines a method returns a copy of the receiver wrapped in an ANSI
+        # sequence for each background color (e.g. #on_blue).
+        #
+        # The methods handle nesting of ANSI sequences.
+        #
+        define_method "on_#{key}" do
+          open = Graphics.background_color(key)
+          close = ANSI::DEFAULT_BACKGROUND_COLOR
+          wrap_in_ansi_sequence(open, close)
+        end
+      end
+
+      ANSI::TEXT_ATTRIBUTES.each_key do |key|
+        # Defines a method returns a copy of the receiver wrapped in an ANSI
+        # sequence for each text attribute (e.g. #bold).
+        #
+        # The methods handle nesting of ANSI sequences.
+        #
+        define_method key do
+          open = Graphics.text_attribute(key)
+          close_code = TEXT_DISABLE_ATTRIBUTES[key]
+          close = Graphics.graphics_mode(close_code)
+          wrap_in_ansi_sequence(open, close)
+        end
+      end
+    end
+  end
+end

data/lib/claide/argv.rb

@@ -1,34 +1,42 @@
 # encoding: utf-8
 
-module CLAide
+require 'claide/argv/parser'
 
+module CLAide
   # This class is responsible for parsing the parameters specified by the user,
   # accessing individual parameters, and keep state by removing handled
   # parameters.
   #
   class ARGV
-
-    # @param [Array<String>] argv
+    # @return [ARGV] Coherces an object to the ARGV class if needed.
     #
-    #   A list of parameters. Each entry is ensured to be a string by calling
-    #   `#to_s` on it.
+    # @param  [Object] argv
+    #         The object which should be converted to the ARGV class.
     #
-    def initialize(argv)
-      @entries = self.class.parse(argv)
+    def self.coherce(argv)
+      if argv.is_a?(ARGV)
+        argv
+      else
+        ARGV.new(argv)
+      end
     end
 
-    # @return [Boolean]
+    # @param [Array<#to_s>] argv
+    #        A list of parameters.
     #
-    #   Returns whether or not there are any remaining unhandled parameters.
+    def initialize(argv)
+      @entries = Parser.parse(argv)
+    end
+
+    # @return [Boolean] Whether or not there are any remaining unhandled
+    #         parameters.
     #
     def empty?
       @entries.empty?
     end
 
-    # @return [Array<String>]
-    #
-    #   A list of the remaining unhandled parameters, in the same format a user
-    #   specifies it in.
+    # @return [Array<String>] A list of the remaining unhandled parameters, in
+    #         the same format a user specifies it in.
     #
     # @example
     #
@@ -49,10 +57,8 @@ module CLAide
       end
     end
 
-    # @return [Hash]
-    #
-    #   A hash that consists of the remaining flags and options and their
-    #   values.
+    # @return [Hash] A hash that consists of the remaining flags and options
+    #         and their values.
     #
     # @example
     #
@@ -67,9 +73,7 @@ module CLAide
       options
     end
 
-    # @return [Array<String>]
-    #
-    #   A list of the remaining arguments.
+    # @return [Array<String>] A list of the remaining arguments.
     #
     # @example
     #
@@ -81,13 +85,10 @@ module CLAide
       @entries.map { |type, value| value if type == :arg }.compact
     end
 
-    # @return [Array<String>]
-    #
-    #   A list of the remaining arguments.
-    #
-    # @note
+    # @return [Array<String>] A list of the remaining arguments.
     #
-    #   This version also removes the arguments from the remaining parameters.
+    # @note   This version also removes the arguments from the remaining
+    #         parameters.
     #
     # @example
     #
@@ -104,13 +105,9 @@ module CLAide
       arguments
     end
 
-    # @return [String]
-    #
-    #   The first argument in the remaining parameters.
-    #
-    # @note
+    # @return [String] The first argument in the remaining parameters.
     #
-    #   This will remove the argument from the remaining parameters.
+    # @note   This will remove the argument from the remaining parameters.
     #
     # @example
     #
@@ -126,23 +123,17 @@ module CLAide
       end
     end
 
-    # @return [Boolean, nil]
+    # @return [Boolean, nil] Returns `true` if the flag by the specified `name`
+    #         is among the remaining parameters and is not negated.
     #
-    #   Returns `true` if the flag by the specified `name` is among the
-    #   remaining parameters and is not negated.
+    # @param  [String] name
+    #         The name of the flag to look for among the remaining parameters.
     #
-    # @param [String] name
+    # @param  [Boolean] default
+    #         The value that is returned in case the flag is not among the
+    #         remaining parameters.
     #
-    #   The name of the flag to look for among the remaining parameters.
-    #
-    # @param [Boolean] default
-    #
-    #   The value that is returned in case the flag is not among the remaining
-    #   parameters.
-    #
-    # @note
-    #
-    #   This will remove the flag from the remaining parameters.
+    # @note   This will remove the flag from the remaining parameters.
     #
     # @example
     #
@@ -156,23 +147,18 @@ module CLAide
       delete_entry(:flag, name, default)
     end
 
-    # @return [String, nil]
-    #
-    #   Returns the value of the option by the specified `name` is among the
-    #   remaining parameters.
+    # @return [String, nil] Returns the value of the option by the specified
+    #         `name` is among the remaining parameters.
     #
-    # @param [String] name
+    # @param  [String] name
+    #         The name of the option to look for among the remaining
+    #         parameters.
     #
-    #   The name of the option to look for among the remaining parameters.
+    # @param  [String] default
+    #         The value that is returned in case the option is not among the
+    #         remaining parameters.
     #
-    # @param [String] default
-    #
-    #   The value that is returned in case the option is not among the
-    #   remaining parameters.
-    #
-    # @note
-    #
-    #   This will remove the option from the remaining parameters.
+    # @note   This will remove the option from the remaining parameters.
     #
     # @example
     #
@@ -188,8 +174,25 @@ module CLAide
 
     private
 
+    # @return [Array<Array<Symbol, String, Array>>] A list of tuples for each
+    #         non consumed parameter, where the first entry is the `type` and
+    #         the second entry the actual parsed parameter.
+    #
     attr_reader :entries
 
+    # @return [Bool, String, Nil] Removes an entry from the entries list and
+    #         returns its value or the default value if the entry was not
+    #         present.
+    #
+    # @param  [Symbol] requested_type
+    #         The type of the entry.
+    #
+    # @param  [String] requested_key
+    #         The key of the entry.
+    #
+    # @param  [Bool, String, Nil] default
+    #         The value which should be returned if the entry is not present.
+    #
     def delete_entry(requested_type, requested_key, default)
       result = nil
       @entries.delete_if do |type, (key, value)|
@@ -200,53 +203,5 @@ module CLAide
       end
       result.nil? ? default : result
     end
-
-    # @return [Array<Array>]
-    #
-    #   A list of tuples for each parameter, where the first entry is the
-    #   `type` and the second entry the actual parsed parameter.
-    #
-    # @example
-    #
-    #   list = parse(['tea', '--no-milk', '--sweetner=honey'])
-    #   list # => [[:arg, "tea"],
-    #              [:flag, ["milk", false]],
-    #              [:option, ["sweetner", "honey"]]]
-    #
-    def self.parse(argv)
-      entries = []
-      copy = argv.map(&:to_s)
-      while x = copy.shift
-        type = key = value = nil
-        if is_arg?(x)
-          # A regular argument (e.g. a command)
-          type, value = :arg, x
-        else
-          key = x[2..-1]
-          if key.include?('=')
-            # An option with a value
-            type = :option
-            key, value = key.split('=', 2)
-          else
-            # A boolean flag
-            type = :flag
-            value = true
-            if key[0,3] == 'no-'
-              # A negated boolean flag
-              key = key[3..-1]
-              value = false
-            end
-          end
-          value = [key, value]
-        end
-        entries << [type, value]
-      end
-      entries
-    end
-
-    def self.is_arg?(x)
-      x[0,2] != '--'
-    end
-
   end
 end