rainbow 1.99.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 820cb8349ec300d38fa0b456dfec3d4fe3399314
-  data.tar.gz: bc326589c9e418bb2dc1d13989d9931b8a7d548e
+  metadata.gz: 372e902e66070b47cdb7c31a2261929f57086e59
+  data.tar.gz: 57e6af68cbd87bf8c79298b9d6d77e0a46719dc5
 SHA512:
-  metadata.gz: 7f487f330dd0cc1401f5b1172ac5e2eca94f54371f02ab79f5d12a5c23c2c3ee5938a9036875b53575721ecae9d33257676f3400f042894678d9beffe68c0df9
-  data.tar.gz: c0b10c5d741321d8743f5b0a35feb3cc9ba3128dd5798462a6b89c273a6d3b725a1062a1fe725a87a2f394b7dd34e78189b9eb0304c8776efd2806ee2ce6413f
+  metadata.gz: 37394c88313337fb8fc04dc6d1f649eaea0c257d25a4e44e4cd1f54d07a87fb3cfce3673c86a33079468440fd040d21bf4c57d53fd4ef9d8a8a01169465236fc
+  data.tar.gz: a0a235ea3d51152d2a107435229730daa19f8d4a1f838803af6af87707a2e17fc2f48fb6195d78fab26acce0673aca33535a499c9ebc4feb5b64d6696edf63f2

data/.rubocop.yml

@@ -0,0 +1,14 @@
+Documentation:
+  Enabled: false
+
+EmptyLinesAroundBody:
+  Enabled: false
+
+HashSyntax:
+  Enabled: false
+
+MethodName:
+  Enabled: false
+
+StringLiterals:
+  Enabled: false

data/.travis.yml

@@ -1,6 +1,5 @@
 bundler_args: --without guard
 rvm:
-  - 1.8.7
   - 1.9.2
   - 1.9.3
   - 2.0.0

data/Changelog.md

@@ -0,0 +1,67 @@
+# Rainbow changelog
+
+## 1.0.0 (2008-7-21)
+
+* initial version
+
+## 1.0.1 (2009-3-19)
+
+* Windows support
+
+## 1.0.2 (2009-5-15)
+
+* improved support for ruby 1.8.6 and 1.9.1
+
+## 1.0.3 (2009-7-26)
+
+* rainbow methods don't mutate the original string object anymore
+
+## 1.0.4 (2009-11-27)
+
+* support for 256 colors
+
+## 1.1 (2010-6-7)
+
+* option for enabling/disabling of escape code wrapping
+* auto-disabling when STDOUT is not a TTY
+
+## 1.1.1 (2011-2-7)
+
+* improved Windows support
+
+## 1.1.2 (2011-11-13)
+
+* improved compatibility with MRI 1.9.3
+
+## 1.1.3 (2011-12-6)
+
+* improved compatibility with MRI 1.8.7
+* fix for regression with regards to original string mutation
+
+## 1.1.4 (2012-4-28)
+
+* option for forcing coloring even when STDOUT is not a TTY (CLICOLOR_FORCE env var)
+* fix for frozen strings
+
+## 1.99.0 (2013-12-26)
+
+* preparation for dropping String monkey patching
+* `require "rainbow/string"` if you want to use monkey patched String
+* introduction of Rainbow() wrapper
+* support for MRI 1.8.7, 1.9.2, 1.9.3, 2.0 and 2.1, JRuby and Rubinius
+* deprecation of Sickill::Rainbow namespace (use Rainbow.enabled = true instead)
+
+## 1.99.1 (2013-12-28)
+
+* drop support for ruby 1.8
+* `require "rainbow/string"` -> `require "rainbow/ext/string"`
+* custom rainbow wrapper instances (with separate enabled/disabled state)
+* shortcut methods for changing text color (`Rainbow("foo").red`)
+
+## 1.99.2 (2014-01-24)
+
+* bring back ruby 1.8 support
+
+## 2.0.0 (2014-01-24)
+
+* disable string mixin by default

data/Gemfile

@@ -3,8 +3,8 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in rainbow.gemspec
 gemspec
 
-gem 'coveralls', :require => false
-gem 'mime-types', '< 2.0.0', :platforms => [:ruby_18]
+gem 'coveralls', require: false
+gem 'mime-types', '< 2.0.0', platforms: [:ruby_18]
 
 group :guard do
   gem 'guard'
@@ -12,6 +12,6 @@ group :guard do
 end
 
 platform :rbx do
+  gem 'json'
   gem 'rubysl'
-  gem 'rubysl-json'
 end

data/Guardfile

@@ -1,7 +1,7 @@
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
-guard :rspec, :cmd => 'rspec --color' do
+guard :rspec, cmd: 'rspec --color' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { "spec" }
   watch('spec/spec_helper.rb')  { "spec" }

data/README.markdown

@@ -6,25 +6,33 @@
 
 Rainbow is a ruby gem for colorizing printed text on ANSI terminals.
 
-It provides a string wrapper object that allows for wrapping a string with
-[ANSI escape codes](http://en.wikipedia.org/wiki/ANSI_escape_code). These codes
-when printed in a terminal change text attributes like text color, background,
+It provides a string presenter object, which adds several methods to your
+strings for wrapping them in [ANSI escape
+codes](http://en.wikipedia.org/wiki/ANSI_escape_code). These codes when printed
+in a terminal change text attributes like text color, background color,
 intensity etc.
 
-## Example
+## Usage
+
+To make your string colored wrap it with `Rainbow()` presenter and call
+`.color(<color name>)` on it.
+
+### Example
 
 ```ruby
 require 'rainbow'
 
-puts Rainbow("this is red").color(:red) + " and " + Rainbow("this on yellow bg").background(:yellow) + " and " + Rainbow("even bright underlined!").underline.bright
+p Rainbow("this is red").red + " and " + Rainbow("this on yellow bg").bg(:yellow) + " and " + Rainbow("even bright underlined!").underline.bright
+
+# => "\e[31mthis is red\e[0m and \e[43mthis on yellow bg\e[0m and \e[4m\e[1meven bright underlined!\e[0m"
 ```
 
-## API
+### Rainbow presenter API
 
-Following methods are available on a string wrapper object:
+Rainbow presenter adds the following methods to presented string:
 
-* `foreground(color)` (with `color` and `colour` aliases)
-* `background(color)`
+* `color(c)` (with `foreground`, and `fg` aliases)
+* `background(c)` (with `bg` alias)
 * `bright`
 * `underline`
 * `blink`
@@ -32,17 +40,32 @@ Following methods are available on a string wrapper object:
 * `hide`
 * `italic` (not well supported by terminal emulators).
 
-All of the methods return wrapped string so you can chain method calls as in
-the above example.
+Text color can also be changed by calling a method named by a color:
+
+* `black`
+* `red`
+* `green`
+* `yellow`
+* `blue`
+* `magenta`
+* `cyan`
+* `white`
+
+All of the methods return `self` (the presenter object) so you can chain method
+calls:
+
+```ruby
+Rainbow("hola!").blue.bright.underline
+```
 
 ### String mixin
 
-If you prefer not to wrap every string you want to colorize with `Rainbow()`
-you can include all the rainbow methods in a String class directly by requiring
-`rainbow/string`:
+If you don't like wrapping every string you want to colorize with `Rainbow()`
+you can include all the rainbow presenter methods directly in a String class by
+requiring `rainbow/ext/string`:
 
 ```ruby
-require 'rainbow/string'
+require 'rainbow/ext/string'
 
 puts "this is red".color(:red) + " and " + "this on yellow bg".background(:yellow) + " and " + "even bright underlined!".underline.bright
 ```
@@ -50,54 +73,88 @@ puts "this is red".color(:red) + " and " + "this on yellow bg".background(:yello
 This way of using Rainbow is not recommended though as it pollutes String's
 public interface with methods that are presentation specific.
 
-NOTE: the mixin is included in String by default in rainbow 1.99 to not break
-backwards compatibility. It won't be included by default in rainbow 2.0.
+NOTE: the mixing doesn't include shortcut methods for changing text color, you
+should use "string".color(:blue) instead of "string".blue
+
+NOTE: the mixin is included in String by default in rainbow 1.x versions.
+In rainbow 2.x the behavior was changed - if you're upgrading from 1.x to 2.x
+and you used direct String methods then you can either require the string
+extension as shown above or update your code to use the new presenter API.
 
 ### Color specification
 
-Both `foreground/color/colour` and `background` accept color specified in any
+Both `color` and `background` accept color specified in any
 of the following ways:
 
-* color number (where 1 is red, 2 is green and so on):
-  `Rainbow("hello").foreground(1)`
+* color number (where 0 is black, 1 is red, 2 is green and so on):
+  `Rainbow("hello").color(1)`
 
-* color name as a symbol (available: :black, :red, :green, :yellow, :blue,
+* color name as a symbol (:black, :red, :green, :yellow, :blue,
   :magenta, :cyan, :white):
-  `Rainbow("hello").foreground(:yellow)`
+  `Rainbow("hello").color(:yellow)`.
+  This can be simplified to `Rainbow("hello").yellow`
 
 * RGB triplet as separate values in the range 0-255:
-  `Rainbow("hello").foreground(115, 23, 98)`
+  `Rainbow("hello").color(115, 23, 98)`
 
 * RGB triplet as a hex string:
-  `Rainbow("hello").foreground("FFC482")` or `Rainbow("hello").foreground("#FFC482")`
+  `Rainbow("hello").color("FFC482")` or `Rainbow("hello").color("#FFC482")`
 
 When you specify a color with a RGB triplet rainbow finds the nearest match
 from 256 colors palette. Note that it requires a 256-colors capable terminal to
 display correctly.
 
-## Windows support
+### Configuration
 
-For Windows support, you should install the following gems:
+Rainbow can be enabled/disabled globally by setting:
 
 ```ruby
-gem install windows-pr win32console
+Rainbow.enabled = true/false
 ```
 
-If the above gems aren't installed then all strings are returned unmodified.
+When disabled all the methods return an unmodified string
+(`Rainbow("hello").red == "hello"`).
+
+It's enabled by default, unless STDOUT/STDERR is not a TTY or a terminal is
+dumb.
 
-## Configuration
+### Advanced usage
 
-Rainbow can be enabled/disabled globally by setting:
+`Rainbow()` and `Rainbow.enabled` operate on the global Rainbow wrapper
+instance. If you would like to selectively enable/disable coloring in separate
+parts of your application you can get a new Rainbow wrapper instance for each
+of them and control the state of coloring during the runtime.
 
 ```ruby
-Rainbow.enabled = true/false
+rainbow_one = Rainbow.new
+rainbow_two = Rainbow.new
+
+rainbow_one.enabled = false
+
+Rainbow("hello").red          # => "\e[31mhello\e[0m" ("hello" if not on TTY)
+rainbow_one.wrap("hello").red # => "hello"
+rainbow_two.wrap("hello").red # => "\e[31mhello\e[0m" ("hello" if not on TTY)
 ```
 
-When disabled all the methods return an unmodified string
-(`Rainbow("hello").color(:red) == "hello"`).
+By default each new instance inherits enabled/disabled state from the global
+`Rainbow.enabled`.
 
-It's enabled by default, unless STDOUT/STDERR is not a TTY or a terminal is
-dumb.
+This feature comes handy for example when you have multiple output formatters
+in your application and some of them print to a terminal but others write to a
+file. Normally rainbow would detect that STDIN/STDERR is a TTY and would
+colorize all the strings, even the ones that go through file writing
+formatters. You can easily solve that by disabling coloring for the Rainbow
+instances that are used by formatters with file output.
+
+## Windows support
+
+For Windows support, you should install the following gems:
+
+```ruby
+gem install windows-pr win32console
+```
+
+If the above gems aren't installed then all strings are returned unmodified.
 
 ## Installation
 

data/lib/rainbow/color.rb

@@ -4,17 +4,22 @@ module Rainbow
     attr_reader :ground
 
     def self.build(ground, values)
-      raise ArgumentError.new(
-        "Wrong number of arguments for color definition, should be 1 or 3"
-      ) unless [1, 3].include?(values.size)
+      unless [1, 3].include?(values.size)
+        fail ArgumentError,
+          "Wrong number of arguments for color definition, should be 1 or 3"
+      end
 
       color = values.size == 1 ? values.first : values
 
       case color
-        when ::Fixnum then Indexed.new(ground, color)
-        when ::Symbol then Named.new(ground, color)
-        when ::Array  then RGB.new(ground, *color)
-        when ::String then RGB.new(ground, *parse_hex_color(color))
+      when ::Fixnum
+        Indexed.new(ground, color)
+      when ::Symbol
+        Named.new(ground, color)
+      when ::Array
+        RGB.new(ground, *color)
+      when ::String
+        RGB.new(ground, *parse_hex_color(color))
       end
     end
 
@@ -47,21 +52,22 @@ module Rainbow
     class Named < Indexed
 
       NAMES = {
-        :black   => 0,
-        :red     => 1,
-        :green   => 2,
-        :yellow  => 3,
-        :blue    => 4,
-        :magenta => 5,
-        :cyan    => 6,
-        :white   => 7,
-        :default => 9,
+        black:   0,
+        red:     1,
+        green:   2,
+        yellow:  3,
+        blue:    4,
+        magenta: 5,
+        cyan:    6,
+        white:   7,
+        default: 9,
       }
 
       def initialize(ground, name)
-        raise ArgumentError.new(
-          "Unknown color name, valid names: #{color_names.join(', ')}"
-        ) unless color_names.include?(name)
+        unless color_names.include?(name)
+          fail ArgumentError,
+            "Unknown color name, valid names: #{color_names.join(', ')}"
+        end
 
         super(ground, NAMES[name])
       end
@@ -83,9 +89,9 @@ module Rainbow
       end
 
       def initialize(ground, *values)
-        raise ArgumentError.new(
-          "RGB value outside 0-255 range"
-        ) if values.min < 0 or values.max > 255
+        if values.min < 0 || values.max > 255
+          fail ArgumentError, "RGB value outside 0-255 range"
+        end
 
         super(ground, 8)
         @r, @g, @b = values

data/lib/rainbow/ext/string.rb

@@ -0,0 +1,52 @@
+require 'rainbow'
+
+module Rainbow
+  module Ext
+    module String
+      module InstanceMethods
+
+        def foreground(*color)
+          Rainbow(self).foreground(*color)
+        end
+
+        alias_method :color, :foreground
+        alias_method :colour, :foreground
+
+        def background(*color)
+          Rainbow(self).background(*color)
+        end
+
+        def reset
+          Rainbow(self).reset
+        end
+
+        def bright
+          Rainbow(self).bright
+        end
+
+        def italic
+          Rainbow(self).italic
+        end
+
+        def underline
+          Rainbow(self).underline
+        end
+
+        def blink
+          Rainbow(self).blink
+        end
+
+        def inverse
+          Rainbow(self).inverse
+        end
+
+        def hide
+          Rainbow(self).hide
+        end
+
+      end
+    end
+  end
+end
+
+::String.send(:include, Rainbow::Ext::String::InstanceMethods)

data/lib/rainbow/global.rb

@@ -0,0 +1,21 @@
+require 'rainbow/wrapper'
+
+module Rainbow
+
+  def self.global
+    @global ||= Wrapper.new
+  end
+
+  def self.enabled
+    global.enabled
+  end
+
+  def self.enabled=(value)
+    global.enabled = value
+  end
+
+end
+
+def Rainbow(string)
+  Rainbow.global.wrap(string.to_s)
+end

data/lib/rainbow/legacy.rb

@@ -2,7 +2,8 @@ module Sickill
   module Rainbow
 
     def self.enabled=(value)
-      STDERR.puts "Rainbow gem notice: Sickill::Rainbow.enabled= is deprecated, use Rainbow.enabled= instead."
+      STDERR.puts("Rainbow gem notice: Sickill::Rainbow.enabled= is " \
+                  "deprecated, use Rainbow.enabled= instead.")
       ::Rainbow.enabled = value
     end
 

data/lib/rainbow/null_presenter.rb

@@ -0,0 +1,30 @@
+module Rainbow
+
+  class NullPresenter < ::String
+
+    def color(*values); self; end
+    def background(*values); self; end
+    def reset; self; end
+    def bright; self; end
+    def italic; self; end
+    def underline; self; end
+    def blink; self; end
+    def inverse; self; end
+    def hide; self; end
+
+    def black; self; end
+    def red; self; end
+    def green; self; end
+    def yellow; self; end
+    def blue; self; end
+    def magenta; self; end
+    def cyan; self; end
+    def white; self; end
+
+    alias_method :foreground, :color
+    alias_method :fg, :color
+    alias_method :bg, :background
+
+  end
+
+end

data/lib/rainbow/presenter.rb

@@ -0,0 +1,113 @@
+require 'rainbow/string_utils'
+require 'rainbow/color'
+
+module Rainbow
+
+  class Presenter < ::String
+
+    TERM_EFFECTS = {
+      reset:     0,
+      bright:    1,
+      italic:    3,
+      underline: 4,
+      blink:     5,
+      inverse:   7,
+      hide:      8,
+    }
+
+    # Sets color of this text.
+    def color(*values)
+      wrap_with_sgr(Color.build(:foreground, values).codes)
+    end
+
+    alias_method :foreground, :color
+    alias_method :fg, :color
+
+    # Sets background color of this text.
+    def background(*values)
+      wrap_with_sgr(Color.build(:background, values).codes)
+    end
+
+    alias_method :bg, :background
+
+    # Resets terminal to default colors/backgrounds.
+    #
+    # It shouldn't be needed to use this method because all methods
+    # append terminal reset code to end of string.
+    def reset
+      wrap_with_sgr(TERM_EFFECTS[:reset])
+    end
+
+    # Turns on bright/bold for this text.
+    def bright
+      wrap_with_sgr(TERM_EFFECTS[:bright])
+    end
+
+    # Turns on italic style for this text (not well supported by terminal
+    # emulators).
+    def italic
+      wrap_with_sgr(TERM_EFFECTS[:italic])
+    end
+
+    # Turns on underline decoration for this text.
+    def underline
+      wrap_with_sgr(TERM_EFFECTS[:underline])
+    end
+
+    # Turns on blinking attribute for this text (not well supported by terminal
+    # emulators).
+    def blink
+      wrap_with_sgr(TERM_EFFECTS[:blink])
+    end
+
+    # Inverses current foreground/background colors.
+    def inverse
+      wrap_with_sgr(TERM_EFFECTS[:inverse])
+    end
+
+    # Hides this text (set its color to the same as background).
+    def hide
+      wrap_with_sgr(TERM_EFFECTS[:hide])
+    end
+
+    def black
+      color(:black)
+    end
+
+    def red
+      color(:red)
+    end
+
+    def green
+      color(:green)
+    end
+
+    def yellow
+      color(:yellow)
+    end
+
+    def blue
+      color(:blue)
+    end
+
+    def magenta
+      color(:magenta)
+    end
+
+    def cyan
+      color(:cyan)
+    end
+
+    def white
+      color(:white)
+    end
+
+    private
+
+    def wrap_with_sgr(codes) #:nodoc:
+      self.class.new(StringUtils.wrap_with_sgr(self, [*codes]))
+    end
+
+  end
+
+end

data/lib/rainbow/version.rb

@@ -1,3 +1,3 @@
 module Rainbow
-  VERSION = "1.99.0".freeze
+  VERSION = "2.0.0".freeze
 end