colir 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NTE0MzRiMWYxNmUzNjI2NWYwNjg1Mzk1MWEwOWIxYmY1OTUwZWE1Zg==
+  data.tar.gz: !binary |-
+    ZTJmYzZhOWQ3NWU2MzRiZWZlMmZiZDNmMGI5OTExMDJhZDE3MjE1YQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ODExMDk0MWI1NTMwNzZmMmIwZDk1ZmY0MjA5ODQ2MTlhZTJhNWIyNGM4ZmQ2
+    MDVjNmM0N2EwMDM0ZGE3ZTYxZTU2NjUzNGQ0ODg3MzM3ZGY4MzUyMGM3ZWRh
+    ZTdkYzhhMjYwNjdjZmM3NGQ2YjA4NzMwOGIxMjQ1MTRkZmU3ZmQ=
+  data.tar.gz: !binary |-
+    ODNiOWQ4NDc5Njg2ZmRlMmUzM2JjMWZhMjQ4ODYwZjkzN2JiYzdjODI1ZmE3
+    NTMyZmZhMDA4YzZhNGUwZDRjYzM3ZTlkZGI2ZjY5MzI0YWM5ZGE4ZDQxOGQy
+    Zjc2Mjk2Y2E2ZDI2NzRhNzZiYWI1ZDIzZWNjYjc1YzkxZDI0Mzc=

data/.gitignore

@@ -0,0 +1,4 @@
+*~
+*.gem
+Gemfile.lock
+.rbx

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+
+rvm:
+  - ruby-head
+  - 2.0.0
+  - 1.9.3
+  - rbx-19mode
+
+branches:
+  only:
+    - master
+
+before_install:
+  - gem install bundler

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+Colir changelog
+===============
+
+### v0.0.1 (April 05, 2013)
+
+* Initial release

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/LICENCE

@@ -0,0 +1,19 @@
+Copyright (C) 2013 Kyrylo Silin
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.md

@@ -0,0 +1,186 @@
+Colir
+=====
+
+[![Build Status][ci-badge]][ci-link]
+
+* Repository: [https://github.com/kyrylo/colir][cr]
+
+Description
+-----------
+
+This tiny library provides support for RGB colours and some simple manipulations
+with them.
+
+Installation
+------------
+
+    gem install colir
+
+Synopsis
+--------
+
+The name Colir means “colour” in Ukrainian (roughly). OK, enough of rant, let's
+talk about the API instead.
+
+###### Basics
+
+You can create colours with human readable names. For example, the following
+code would create opaque red colour (0xff000000).
+
+```ruby
+require 'colir'
+
+# Create a new Colir.
+red = Colir.red #=> #<Colir:...>
+# Get a valid RGB colour, represented as an integer number.
+red.hex #=> 16711680
+# Why do you never trust me?
+red.hex.to_s(16) #=> "ff0000"
+
+# You can also get the same colour, but with alpha channel.
+red.hexa #=> 4278190080
+# Okay, okay!
+red.hexa.to_s(16) #=> "ff000000"
+```
+
+The list of all human readable colour names can be found at [w3schools][w3].
+Actually, you can create any valid RGB colours, not just the predefined ones.
+
+```ruby
+# This is valid.
+yup = Colir.new(0xff0000) #=> #<Colir:...>
+# This isn't. There is no such RGB colour.
+nope = Colir.new(0xff00001) #=> RangeError: out of allowed RGB values
+```
+
+###### Transparency
+
+As you may have noticed, the library supports transparent colours.
+
+```ruby
+# Shortcut methods have only 1 parameter, which is transparency. It must lie
+# within the range of 0..1
+red = Colir.red(0.3)
+red.hexa #=> 4278190110
+red.hexa.to_s(16) #=> "ff00001e"
+red.transparency #=> 0.3
+
+# With arbitrary colours you can pass the second parameter.
+green = Colir.new(0x00ff00, 0.3)
+green.hexa #=> 16711710
+green.hexa.to_s(16) #=> "0x00ff001e"
+green.transparency #=> 0.3
+
+# The default transparency is 0.0
+green = Colir.new(0x00ff00)
+green.transparency #=> 0.0
+```
+
+It's possible to adjust a Colir's transparency.
+
+```ruby
+# `#opaque!` and `#transparent!` set a Colir's transparency to `0.0`
+# and `1.0` respectively.
+blue = Colir.new(0x0000ff, 0.45)
+blue.transparency #=> 0.3
+blue.transparent! #=> (Colir: 0x00ff00e1)
+blue.transparency #=> 0.0
+blue.opaque! #=> (Colir: 0x00ff00ff)
+blue.transparency #=> 1.0
+
+# You can set your own transparency value.
+blue.transparency = 0.9 #=> 0.9
+blue.transparency #=> 0.9
+
+# But be careful, as the valid value is anything in between 0 and 1.
+blue.transparency = 1.01 #=> RangeError: ...
+```
+
+###### Shades
+
+Last but not least, you can use colour shades.
+
+```ruby
+yellow = Colir.yellow
+yellow.shade #=> 0
+
+# Let's make it a bit darker.
+yellow.darken #=> #<Colir:...>
+yellow.shade #=> -1
+yellow.hex #=> 13421568
+
+# Hum, that's not dark enough. Let's do it one more time.
+yellow.darken
+yellow.shade #=> -2
+yellow.hex #=> 10066176
+
+# Actually, the previous shade was better!
+yellow.lighten
+yellow.shade #=> -1
+yellow.hex #=> 13421568
+```
+
+The previous examples modify the Colir object (`#darken` and `#lighten`).
+Hovewer, there are two other methods that return a new object: `#darker` and
+`#lighter`.
+
+```ruby
+# HEXes
+orange = Colir.orange
+orange.hex #=> 16753920
+orange.darker.hex #=> 13403392
+orange.hex #=> 16753920
+
+# Shades
+orange = Colir.orange
+orange.shade #=> 0
+orange.lighter.shade #=> 1
+orange.shade #=> 0
+```
+
+There is a handy way to reset the shade level. Can you guess it? Of course, it's
+the `#reset_shade` method!
+
+```ruby
+indigo = Colir.indigo
+indigo.lighten
+indigo.lighten
+indigo.lighten
+indigo.lighten
+indigo.lighten
+indigo.shades #=> 5
+indigo.reset_shade #=> #<Colir:...>
+indigo.shade #=> 0
+```
+
+Limitations
+-----------
+
+### OS support
+
+Colir is a cross-platform library.
+
+### Rubies
+
+* Ruby 1.9.3 and higher
+* Rubinius 2.0.0rc1 and higher (mode 1.9 and higher)
+
+Initially I wanted to supprot JRuby 1.7.3 (mode 1.9), but it has a [critical bug
+in `BigDecimal` library](http://jira.codehaus.org/browse/JRUBY-7101), which
+Colir actively utilises.
+
+Credits
+-------
+
+* The first contributor badge goes to [kachick][kachick]
+
+Licence
+-------
+
+The project uses Zlib licence. See LICENCE file for more information.
+
+[cr]: https://github.com/kyrylo/colir
+[ci-badge]: https://travis-ci.org/kyrylo/colir.png?branch=master "Build status"
+[ci-link]: https://travis-ci.org/kyrylo/colir/ "Build history"
+[w3]: http://www.w3schools.com/cssref/css_colornames.asp
+[kachick]: https://github.com/kachick

data/Rakefile

@@ -0,0 +1,15 @@
+def quiet
+  ENV['VERBOSE'] ? '' : '-q'
+end
+
+def test_files
+  paths = FileList['spec/**/*_spec.rb']
+  paths.shuffle!.join(' ')
+end
+
+desc "Run tests"
+task :test do
+  exec "bacon -Ispec #{ quiet } #{ test_files }"
+end
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/colir.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name         = 'colir'
+  s.version      = File.read('VERSION')
+  s.date         = Time.now.strftime('%Y-%m-%d')
+  s.summary      = 'Colir means colour in Ukrainan. In Ruby it means HEX colour'
+  s.description  = 'This library is about HEX colours.'
+  s.author       = 'Kyrylo Silin'
+  s.email        = 'kyrylosilin@gmail.com'
+  s.homepage     = 'https://github.com/kyrylo/colir'
+  s.licenses     = 'zlib'
+
+  s.require_path = 'lib'
+  s.files        = `git ls-files`.split("\n")
+
+  s.add_development_dependency 'bacon'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'pry'
+end

data/lib/colir.rb

@@ -0,0 +1,357 @@
+require 'bigdecimal'
+
+require_relative 'colir/hslrgb'
+
+# This tiny library provides support for RGB colours and some simple
+# manipulations with them. See README.md for more information.
+class Colir
+
+  # The VERSION file must be in the root directory of the library.
+  VERSION_FILE = File.expand_path('../../VERSION', __FILE__)
+
+  VERSION = File.exist?(VERSION_FILE) ?
+    File.read(VERSION_FILE).chomp : '(could not find VERSION file)'
+
+  # The list for human readable colour according to the HTML and CSS color
+  # specification. Does not include alpha channel.
+  COLIRS = {
+    alice_blue:              0xf0f8ff,
+    antique_white:           0xfaebd7,
+    aqua:                    0x00ffff,
+    aquamarine:              0x7fffd4,
+    azure:                   0xf0ffff,
+    beige:                   0xf5f5dc,
+    bisque:                  0xffe4c4,
+    black:                   0x000000,
+    blanched_almond:         0xffebcd,
+    blue:                    0x0000ff,
+    blue_violet:             0x8a2be2,
+    brown:                   0xa52a2a,
+    burly_wood:              0xdeb887,
+    cadet_blue:              0x5f9ea0,
+    chartreuse:              0x7fff00,
+    chocolate:               0xd2691e,
+    coral:                   0xff7f50,
+    cornflower_blue:         0x6495ed,
+    cornsilk:                0xfff8dc,
+    crimson:                 0xdc143c,
+    cyan:                    0x00ffff,
+    dark_blue:               0x00008b,
+    dark_cyan:               0x008b8b,
+    dark_golden_rod:         0xb8860b,
+    dark_gray:               0xa9a9a9,
+    dark_green:              0xa9a9a9,
+    dark_khaki:              0xbdb76b,
+    dark_magenta:            0x8b008b,
+    dark_olive_green:        0x556b2f,
+    dark_orange:             0xff8c00,
+    dark_orchid:             0x9932cc,
+    dark_red:                0x9932cc,
+    dark_salmon:             0xe9967a,
+    dark_sea_green:          0x8fbc8f,
+    dark_slate_blue:         0x483d8b,
+    dark_slate_gray:         0x2f4f4f,
+    dark_turquoise:          0x00ced1,
+    dark_violet:             0x9400d3,
+    deep_pink:               0xff1493,
+    deep_sky_blue:           0x00bfff,
+    dim_gray:                0x696969,
+    dim_grey:                0x696969,
+    dodger_blue:             0x1e90ff,
+    fire_brick:              0xb22222,
+    floral_white:            0xfffaf0,
+    forest_green:            0x228b22,
+    fuchsia:                 0xff00ff,
+    gainsboro:               0xdcdcdc,
+    ghost_white:             0xf8f8ff,
+    gold:                    0xffd700,
+    golden_rod:              0xdaa520,
+    gray:                    0x808080,
+    green:                   0x008000,
+    green_yellow:            0xadff2f,
+    honey_dew:               0xf0fff0,
+    hot_pink:                0xff69b4,
+    indian_red:              0xcd5c5c,
+    indigo:                  0x4b0082,
+    ivory:                   0xfffff0,
+    khaki:                   0xf0e68c,
+    lavender:                0xe6e6fa,
+    lavender_blush:          0xfff0f5,
+    lawn_green:              0x7cfc00,
+    lemon_chiffon:           0xfffacd,
+    light_blue:              0xadd8e6,
+    light_coral:             0xf08080,
+    light_cyan:              0xe0ffff,
+    light_golden_rod_yellow: 0xfafad2,
+    light_gray:              0xd3d3d3,
+    light_green:             0x90ee90,
+    light_pink:              0xffb6c1,
+    light_salmon:            0xffa07a,
+    light_sea_green:         0x20b2aa,
+    light_sky_blue:          0x87cefa,
+    light_slate_gray:        0x778899,
+    light_steel_blue:        0xb0c4de,
+    light_yellow:            0xffffe0,
+    lime:                    0x00ff00,
+    lime_green:              0x32cd32,
+    linen:                   0xfaf0e6,
+    magenta:                 0xff00ff,
+    maroon:                  0x800000,
+    medium_aqua_marine:      0x66cdaa,
+    medium_blue:             0x0000cd,
+    medium_orchid:           0xba55d3,
+    medium_purple:           0x9370db,
+    medium_sea_green:        0x3cb371,
+    medium_slate_blue:       0x7b68ee,
+    medium_spring_green:     0x00fa9a,
+    medium_turquoise:        0x48d1cc,
+    medium_violet_red:       0xc71585,
+    midnight_blue:           0x191970,
+    mint_cream:              0xf5fffa,
+    misty_rose:              0xffe4e1,
+    moccasin:                0xffe4b5,
+    navajo_white:            0xffdead,
+    navy:                    0x000080,
+    old_lace:                0xfdf5e6,
+    olive:                   0x808000,
+    olive_drab:              0x6b8e23,
+    orange:                  0xffa500,
+    orange_red:              0xff4500,
+    orchid:                  0xda70d6,
+    pale_golden_rod:         0xeee8aa,
+    pale_green:              0x98fb98,
+    pale_turquoise:          0xafeeee,
+    pale_violet_red:         0xdb7093,
+    papaya_whip:             0xffefd5,
+    peach_puff:              0xffdab9,
+    peru:                    0xcd853f,
+    pink:                    0xffc0cb,
+    plum:                    0xdda0dd,
+    powder_blue:             0xb0e0e6,
+    purple:                  0x800080,
+    red:                     0xff0000,
+    rosy_brown:              0xbc8f8f,
+    royal_blue:              0x4169e1,
+    saddle_brown:            0x8b4513,
+    salmon:                  0xfa8072,
+    sandy_brown:             0xf4a460,
+    sea_green:               0x2e8b57,
+    sea_shell:               0xfff5ee,
+    sienna:                  0xa0522d,
+    silver:                  0xc0c0c0,
+    sky_blue:                0x87ceeb,
+    slate_blue:              0x6a5acd,
+    slate_gray:              0x708090,
+    snow:                    0xfffafa,
+    spring_green:            0x00ff7f,
+    steel_blue:              0x468284,
+    tan:                     0xd2b48c,
+    teal:                    0x008080,
+    thistle:                 0xd8bfd8,
+    tomato:                  0xff6347,
+    turquoise:               0x40e0d0,
+    violet:                  0xee82ee,
+    wheat:                   0xf5debe,
+    white:                   0x000000,
+    white_smoke:             0xf5f5f5,
+    yellow:                  0xffff00,
+    yellow_green:            0x9acd32
+  }
+
+  class << self
+    # Dynamically define class methods. Each human readable colour turns into a
+    # method. It's useful if you don't care about precise colours or can't
+    # remember HEX codes for a colour.
+    #
+    # @example Accessing a colour
+    #   Colir.wheat.hex #=> 0xf5debe00
+    #
+    # @example Transparency
+    #   Colir.wheat(0.3).hex #=> 0xf5debee1
+    #
+    # @param [Float] transparency
+    #
+    # @return [Colir]
+    # @see Colir
+    COLIRS.each do |name, hex|
+      define_method(name) { |transparency = nil|
+        new(hex, transparency || TRANSPARENCY)
+      }
+    end
+  end
+
+  # The possible number of shades of a Colir in each direction.
+  SHADE_FACTOR = 5
+
+  # The default transparency (opaque).
+  TRANSPARENCY = 0.0
+
+  # The default shade assigned to any Colir.
+  SHADE = 0
+
+  # @see HSLRGB::HSL::L_RANGE
+  UPPER_LIMIT = BigDecimal(HSLRGB::HSL::L_RANGE.max.to_f.to_s)
+
+  # The mi
+  RGB_LOWER_LIMIT = 0x000000
+
+  RGB_UPPER_LIMIT = 0xffffff
+
+  # @return [Integer] the HEX colour without the alpha channel
+  attr_reader :hex
+
+  # @return [Float] the transparency. Lies within the range of [0, 1].
+  attr_reader :transparency
+
+  # @return [Integer] the current shade of the colour. Lies within the
+  #   range of [-5, 5]
+  attr_reader :shade
+
+  # Creates a new HEXA colour, where the A states for "Alpha".
+  #
+  # @param [Integer] hex It's convenient to use Ruby's HEX notation: `0xaaff33`
+  # @param [Float] transparency Alpha channel. Must lie within the range
+  #   of [0, 1].
+  # @raise [RangeError] if the transparency is a bad value
+  def initialize(hex, transparency = TRANSPARENCY)
+    validate_colir!(hex, transparency)
+
+    @hex = hex
+    @transparency = transparency
+    @shade = SHADE
+    @ld_seq = [:base]
+  end
+
+  # @return [Integer] the HEXA representation of the Colir
+  def hexa
+    hex = @hex.to_s(16).rjust(6, '0')
+    alpha = (transparency * 100).to_i.to_s(16).rjust(2, '0')
+    (hex + alpha).to_i(16)
+  end
+
+  # Make the colour fully transparent.
+  # @return [self]
+  def transparent!
+    @transparency = 1.0
+    self
+  end
+
+  # Sets the new +transparency+.
+  #
+  # @return [Float] the new transparency
+  # @raise [RangeError] if transparency does not lie within the valid range
+  def transparency=(transparency)
+    validate_transparency!(transparency)
+    @transparency = transparency
+  end
+
+  # Make the colour fully opaque.
+  # @return [self]
+  def opaque!
+    @transparency = TRANSPARENCY
+    self
+  end
+
+  # Lightens `self` by 1 shade. The maximum number of positive shades is 5. The
+  # method stops increasing the shade levels when it reaches the limit and
+  # merely returns `self` without any changes. The final shade is white colour.
+  #
+  # @return [self] the lightened `self`
+  def lighten
+    if @shade < SHADE_FACTOR
+      calculate_new_hex { |hsl|
+        hsl[2] += if @ld_seq.last == :base || @ld_seq.last == :ltn
+                    @ld_seq << :ltn
+                    l_factor
+                  else
+                    @ld_seq.pop
+                    d_factor
+                  end
+        @shade += 1
+        hsl
+      }
+    end
+    self
+  end
+
+  # Darkens `self` by 1 shade. The maximum number of negative shades is -5. The
+  # method stops decreasing the shade levels when it reaches the limit and
+  # merely returns `self` without any changes. The final shade is black colour.
+  #
+  # @return [self] the darkened `self`
+  def darken
+    if SHADE_FACTOR * -1 < @shade
+      calculate_new_hex { |hsl|
+        hsl[2] -= if @ld_seq.last == :base || @ld_seq.last == :dkn
+                    @ld_seq << :dkn
+                    d_factor
+                  else
+                    @ld_seq.pop
+                    l_factor
+                  end
+        @shade -= 1
+        hsl
+      }
+    end
+    self
+  end
+
+  # Resets the `@shade` to the default value, restoring the `@hex` number.
+  # @return [self]
+  def reset_shade
+    @shade.abs.times { @ld_seq.last == :ltn ? darken : lighten }
+    self
+  end
+
+  # @return [Colir] a new Colir, but darker than `self` by 1 shade. It does not
+  #   modify `self`
+  def darker
+    self.class.new(@hex, @transparency).darken
+  end
+
+  # @return [Colir] a new Colir, but lighter than `self` by 1 shade. It does not
+  #   modify `self`
+  def lighter
+    self.class.new(@hex, @transparency).lighten
+  end
+
+  private
+
+  # @return [BigDecimal] the lightening factor
+  def l_factor
+    @l_factor ||= (UPPER_LIMIT - @hsl[2]) / SHADE_FACTOR
+  end
+
+  # @return [BigDecimal] the darkening factor
+  def d_factor
+    @d_factor ||= @hsl[2] / SHADE_FACTOR
+  end
+
+  # @yield [hsl]
+  # @yieldparam [Array<Integer,BigDecimal>] an HSL colour based on the
+  #   current HEX
+  # @yieldreturn [Array<Integer,BigDecimal>] an HSL colour with
+  #   corrected lightness
+  # @return [void]
+  def calculate_new_hex
+    @hsl ||= HSLRGB.rgb_to_hsl(*HSLRGB::RGB.int_bytes(@hex))
+    @hex = HSLRGB.hsl_to_rgb(*yield(@hsl)).map do |b|
+      b.to_s(16).rjust(2, '0')
+    end.join('').to_i(16)
+  end
+
+  def validate_colir!(hex, transparency)
+    unless HSLRGB::RGB::RGB_RANGE.cover?(hex)
+      raise RangeError, 'out of allowed RGB values (0x000000-0xffffff)'
+    end
+
+    validate_transparency!(transparency)
+  end
+
+  def validate_transparency!(transparency)
+    unless (0..1).cover?(transparency)
+      raise RangeError, 'out of allowed transparency values (0-1)'
+    end
+  end
+
+end