colir 0.0.1

data/lib/colir/hslrgb.rb

@@ -0,0 +1,188 @@
+require 'bigdecimal'
+
+class Colir
+  # The module provides methods for RGB to HSL and HSL to RGB conversions. I
+  # just ported it from a C implementation.
+  # @see http://goo.gl/WLwi6
+  # @since 0.0.1
+  # @private
+  module HSLRGB
+
+    # Provides helper methods for the RGB colours.
+    module RGB
+
+      # The possible values of an RGB colour.
+      RGB_RANGE = 0x000000..0xffffff
+
+      # The possible values of an RGB byte.
+      RGB_BYTE_RANGE = 0x00..0xff
+
+      # Performs a validation check for the +rgb+.
+      #
+      # @example Truthy
+      #   RGB.valid_rgb?([255, 13, 0]) #=> true
+      #
+      # @example Falsey
+      #   RGB.valid_rgb?([256, 13, -1]) #=> false
+      #
+      # @param [Array<Integer>] rgb The RGB colour to be checked
+      # @return [Boolean] true if the given +rgb+ colour lies within the
+      #   `RGB_BYTE_RANGE`
+      def self.valid_rgb?(rgb)
+        rgb.all? { |b| valid_byte?(b) } && (rgb.length == 3)
+      end
+
+      # Converts +hex+ number to the RGB array.
+      #
+      # @example
+      #   RGB.int_bytes(0x123456) #=> [18, 52, 86]
+      #
+      # @param [String] hex The hex number expressed without the preceding `0x`
+      # @return [Array<Integer>] the RGB array
+      def self.int_bytes(hex)
+        hex.to_s(16).rjust(6, '0').scan(/../).map { |b| b.to_i(16) }
+      end
+
+      def self.valid_byte?(byte)
+        RGB_BYTE_RANGE.cover?(byte) && byte.integer?
+      end
+      private_class_method :valid_byte?
+    end
+
+    # Provides helper methods for HSL colours.
+    module HSL
+
+      # The possible values for the hue.
+      H_RANGE = 0..360
+
+      # The possible values for the saturation.
+      S_RANGE = 0..1
+
+      # The possible values for the lightness.
+      L_RANGE = S_RANGE
+
+      # Performs a validation check for the +hsl+.
+      #
+      # @example Truthy
+      #   RGB.valid_hsl?([180, 1, 0.55]) #=> true
+      #
+      # @example Falsey
+      #   RGB.valid_hsl?([180, 1.1, 0.55]) #=> false
+      #
+      # @param [Array<Number>] hsl The HSL colour to be checked
+      # @return [Boolean] true if the given +hsl+ colour lies within the
+      #   `H_RANGE`, `S_RANGE`, `L_RANGE`
+      def self.valid_hsl?(hsl)
+        valid_hue?(hsl[0]) && S_RANGE.cover?(hsl[1]) &&
+          L_RANGE.cover?(hsl[2]) && (hsl.length == 3)
+      end
+
+      def self.valid_hue?(hue)
+        H_RANGE.cover?(hue) && hue.integer?
+      end
+      private_class_method :valid_hue?
+    end
+
+    # The cached array of arrays, which contains order codes for the model  from
+    # `::hsl_to_rgb`. The model is an array, where the needed for conversion
+    # values are calculated only once. The order codes allows to refer to the
+    # calculated model array values via indices. Hopefully, it saves some CPU
+    # cycles.
+    RGB_ORDER_CODES = [
+      [0, 1, 2], # [0, 60)
+      [1, 0, 2], # [60, 120)
+      [2, 0, 1], # [120, 180)
+      [2, 1, 0], # [180, 240)
+      [1, 2, 0], # [240, 300)
+      [0, 2, 1], # [300, 360)
+    ]
+
+    # The code returned for 0 or 360 degrees.
+    RGB_DEFAULT_CODE = [2, 2, 2]
+
+    # Converts an RGB colour to its HSL counterpart.
+    #
+    # @example
+    #   rgb = 'c0c0c0'.scan(/../).map { |b| b.to_i(16) } #=> [192, 192, 192]
+    #   HSLRGB.rgb_to_hsl(192, 192, 192) #=> [0, 0.0, 0.75]
+    #
+    # @param [Integer] red Possible values: 0..255
+    # @param [Integer] green Possible values: 0..255
+    # @param [Integer] blue Possible values: 0..255
+    # @return [Array<Integer,BigDecimal>] the converted HSL representation of
+    #   an RGB colour
+    # @raise [RangeError] if one of the parameters doesn't lie within the
+    #   accepted range
+    # @see http://en.wikipedia.org/wiki/HSL_color_space HSL color space
+    # @see ::hsl_to_rgb
+    def self.rgb_to_hsl(red, green, blue)
+      validate_rgb!([red, green, blue])
+
+      red, green, blue = [red, green, blue].map { |b| b / BigDecimal('255.0') }
+      min, max = [red, green, blue].minmax
+      chroma = max - min
+
+      lightness = (min + max) * BigDecimal('0.5')
+
+      hue = 0
+      saturation = BigDecimal('0.0')
+
+      if chroma.nonzero?
+        hue = case max
+              when red   then (green - blue) / chroma % 6
+              when green then (blue - red) / chroma + 2
+              else            (red - green) / chroma + 4
+              end
+        hue = (hue * 60).round
+        saturation = chroma / (1 - (2 * lightness - 1).abs)
+      end
+
+      [hue, saturation, lightness]
+    end
+
+    def self.validate_rgb!(rgb)
+      unless RGB.valid_rgb?(rgb)
+        raise RangeError, 'out of allowed RGB byte values (0-255)'
+      end
+    end
+    private_class_method :validate_rgb!
+
+    def self.validate_hsl!(hsl)
+      unless HSL.valid_hsl?(hsl)
+        raise RangeError, 'out of allowed HSL values (h:0-360 s:0-1 l:0-1)'
+      end
+    end
+    private_class_method :validate_hsl!
+
+    # Converts an HSL colour to its RGB counterpart. The algorithm is correct,
+    # but sometimes you'll notice little laxity (because of rounding problems).
+    #
+    # @example
+    #   HSLRGB.hsl_to_rgb(180, 1, 0.55) #=> [26, 255, 255]
+    #
+    # @param [Integer] hue Possible values: 0..360
+    # @param [BigDecimal] saturation Possible values: 0..1
+    # @param [BigDecimal] lightness Possible values: 0..1
+    # @return [Array<Integer>] the converted RGB representation of a HSL colour
+    # @raise [RangeError] if one of the parameters doesn't lie within the
+    #   accepted range
+    # @see ::rgb_to_hsl
+    def self.hsl_to_rgb(hue, saturation, lightness)
+      validate_hsl!([hue, saturation, lightness])
+
+      chroma = (1 - (2 * lightness - 1).abs) * saturation
+      a = 1 * (lightness - 0.5 * chroma)
+      b = chroma * (1 - ((hue / BigDecimal('60.0')).modulo(2) - 1).abs)
+
+      degrees = Array.new(7) { |idx| idx * 60 }.each
+      model = [chroma+a, a+b, a]
+
+      RGB_ORDER_CODES.find(->{RGB_DEFAULT_CODE}) {
+        (degrees.next...degrees.peek) === hue
+      }.map { |id|
+        (model[id] * 255).round
+      }
+    end
+
+  end
+end

data/spec/colir_spec.rb

@@ -0,0 +1,407 @@
+require_relative 'helper'
+
+describe Colir do
+  describe "some shortcuts" do
+    it "has a shortcut for red colour" do
+      Colir.red.hexa.should == 0xff000000
+    end
+
+    it "has a shortcut for blanched almond colour" do
+      Colir.blanched_almond.hexa.should == 0xffebcd00
+    end
+
+    it "has a shortcut royal blue colour" do
+      Colir.royal_blue.hexa.should == 0x4169e100
+    end
+
+    it "can set the colour's transparency" do
+      Colir.snow(0.5).transparency.should == 0.5
+    end
+  end
+
+  describe "#intialize" do
+    it "accepts transparency parameter" do
+      Colir.new(0x012345, 0.77).transparency.should == 0.77
+    end
+
+    it "doesn't allow too low HEX number" do
+      should.raise(RangeError) {
+        Colir.new(-0x000001)
+      }.message.should =~ /out of allowed RGB values/
+    end
+
+    it "doesn't allow too high HEX number" do
+      should.raise(RangeError) {
+        Colir.new(0x1000000)
+      }.message.should =~ /out of allowed RGB values/
+    end
+  end
+
+  describe "#hex" do
+    it "returns the hex code of a colour (without transparency)" do
+      Colir.new(0x123456, 0.1).hex.should == 0x123456
+    end
+  end
+
+  describe "#hexa" do
+    it "returns the hex code of a colour (with transparency)" do
+      Colir.new(0x123456, 0.1).hexa.should == 0x1234560a
+    end
+  end
+
+  describe "#transparency" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "defaults to no transparency" do
+      @colir.transparency.should == 0.0
+    end
+
+    it "can be set to a specific value" do
+      Colir.new(0x123456, 0.98).transparency.should == 0.98
+    end
+
+    it "must lie within the range of 0 to 1 (min)" do
+      should.raise(RangeError) {
+        Colir.new(0x123456, -0.01)
+      }.message.should =~ /out of allowed transparency values \(0-1\)/
+    end
+
+    it "must lie within the range of 0 to 1 (max)" do
+      should.raise(RangeError) {
+        Colir.new(0x123456, 1.01)
+      }.message.should =~ /out of allowed transparency values \(0-1\)/
+    end
+
+    it "returns a Float value" do
+      @colir.transparency.should.be kind_of(Float)
+    end
+  end
+
+  describe "#transparency=" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "can be set" do
+      @colir.transparency = 0.89
+      @colir.transparency.should == 0.89
+    end
+
+    it "raises error on a bad value" do
+      should.raise(RangeError) {
+        @colir.transparency = 1.01
+      }.message.should =~ /out of allowed transparency values/
+    end
+  end
+
+  describe "#transparent!" do
+    it "changes the object's transparency to full transparency" do
+      colir = Colir.new(0x123456, 0.3).transparent!
+      colir.transparency.should == 1.0
+    end
+  end
+
+  describe "#opaque!" do
+    it "changes the object's transparency to no transparency" do
+      colir = Colir.new(0x123456, 0.3).opaque!
+      colir.transparency.should == 0.0
+    end
+  end
+
+  describe "#shade" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "returns 0 colour shade for a colour without shades" do
+      @colir.shade.should == 0
+    end
+
+    it "returns -1 for a darker colour" do
+      @colir.darken.shade.should == -1
+    end
+
+    it "returns 1 for a lighter colour" do
+      @colir.lighten.shade.should == 1
+    end
+  end
+
+  describe "#reset_shade" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "resets the colour to its initial state" do
+      before = @colir.shade
+      3.times { @colir.darken }
+      @colir.shade.should.not == before
+      @colir.reset_shade
+      @colir.shade.should == before
+    end
+
+    it "restores the hex number" do
+      before = @colir.hex
+      3.times { @colir.darken }
+      @colir.hex.should.not == before
+      @colir.reset_shade
+      @colir.hex.should == before
+    end
+  end
+
+  describe "#darker" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "returns a new object" do
+      before_id = @colir.object_id
+      after_id = @colir.darker.object_id
+      after_id.should.not == before_id
+    end
+
+    it "doesn't modify the base colour" do
+      before = @colir.hex
+      @colir.darker
+      @colir.hex.should == before
+    end
+
+    it "returns a new colour, but a little bit darker" do
+      @colir.darker.shade.should == -1
+    end
+  end
+
+  describe "#lighter" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "returns a new object" do
+      before_id = @colir.object_id
+      after_id = @colir.lighter.object_id
+      after_id.should.not == before_id
+    end
+
+    it "doesn't modify the base colour" do
+      before = @colir.hex
+      @colir.lighter
+      @colir.hex.should == before
+    end
+
+    it "returns a new colour, but a little bit darker" do
+      @colir.lighter.shade.should == 1
+    end
+  end
+
+  describe "#darken" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "modifies the base colour" do
+      old_colour = @colir.hex
+      @colir.darken
+      @colir.hex.should.not == old_colour
+    end
+
+    it "makes the current colour darker" do
+      @colir.darken
+      @colir.hex.should == 0x0e2a45
+    end
+
+    it "makes the current colour even more dark" do
+      3.times { @colir.darken }
+      @colir.hex.should == 0x071522
+    end
+
+    describe "lower limit" do
+      before do
+        5.times { @colir.darken }
+      end
+
+      it "stops darkening the current colour when meets the limit of shades" do
+        old_hex = @colir.hex
+        @colir.darken.hex.should == old_hex
+      end
+
+      it "finally reaches black colour" do
+        @colir.hex.should == 0x000000
+      end
+    end
+  end
+
+  describe "#lighten" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "modifies the base colour" do
+      old_colour = @colir.hex
+      @colir.lighten
+      @colir.hex.should.not == old_colour
+    end
+
+    it "makes the current colour lighter" do
+      @colir.lighten
+      @colir.hex.should == 0x205d99
+    end
+
+    it "makes the current colour even more light" do
+      3.times { @colir.lighten }
+      @colir.hex.should == 0x79aee3
+    end
+
+    describe "upper limit" do
+      before do
+        5.times { @colir.lighten }
+      end
+
+      it "stops lightening the current colour when meets the limit of shades" do
+        old_hex = @colir.hex
+        @colir.lighten.hex.should == old_hex
+      end
+
+      it "finally reaches white colour" do
+        @colir.hex.should == 0xffffff
+      end
+    end
+  end
+
+  describe "shading" do
+    before do
+      @colir = Colir.new(0x123456)
+    end
+
+    it "darkens properly" do
+      @colir.darken.hex.should == 0x0e2a45
+      @colir.darken.hex.should == 0x0b1f34
+      @colir.darken.hex.should == 0x071522
+      @colir.darken.hex.should == 0x040a11
+      @colir.darken.hex.should == 0
+    end
+
+    it "lightens properly" do
+      @colir.lighten.hex.should == 0x205d99
+      @colir.lighten.hex.should == 0x3685d5
+      @colir.lighten.hex.should == 0x79aee3
+      @colir.lighten.hex.should == 0xbcd6f1
+      @colir.lighten.hex.should == 0xffffff
+    end
+
+    it "darkens and lightens properly" do
+      before = @colir.hex
+      2.times { @colir.lighten }
+      5.times { @colir.darken }
+      10.times { @colir.lighten }
+      5.times { @colir.darken }
+      after = @colir.hex
+      before.should == after
+    end
+
+    describe "lower limit - 0x000000" do
+      describe "darkening" do
+        before do
+          @colir = Colir.new(0x000000)
+        end
+
+        it "doesn't change the hex value" do
+          before = @colir.hex
+          after = @colir.darken.hex
+          after.should == before
+        end
+
+        it "does change the shade level" do
+          @colir.darken.shade.should == -1
+        end
+
+        it "doesn't overflow the shade level" do
+          6.times { @colir.darken }
+          @colir.shade.should == -5
+        end
+      end
+
+      describe "lightening" do
+        before do
+          @colir = Colir.new(0x000000)
+        end
+
+        it "does change the hex value" do
+          before = @colir.hex
+          after = @colir.lighten.hex
+          after.should.not == before
+        end
+
+        it "does change the shade level" do
+          @colir.lighten.shade.should == 1
+        end
+
+        it "doesn't overflow the shade level" do
+          6.times { @colir.lighten }
+          @colir.shade.should == 5
+        end
+      end
+    end
+
+    describe "very close to lower limit" do
+      describe "darkening" do
+        before do
+          @colir = Colir.new(0x000001)
+        end
+
+        it "does change the hex value when it's time" do
+          before = @colir.hex
+          3.times { @colir.darken }
+          after = @colir.hex
+          after.should.not == before
+        end
+
+        it "stops darkening when reaches the lower limit" do
+          3.times { @colir.darken }
+          before = @colir.hex
+          after = @colir.darken.hex
+          after.should == before
+        end
+
+        it "keeps changing the shade level" do
+          2.times { @colir.darken }
+          @colir.shade.should == -2
+
+          2.times { @colir.darken }
+          @colir.shade.should == -4
+        end
+      end
+    end
+
+    describe "very close to upper limit" do
+      describe "lightening" do
+        before do
+          @colir = Colir.new(0xfffffe)
+        end
+
+        it "does change the hex value when it's time" do
+          before = @colir.hex
+          3.times { @colir.lighten }
+          after = @colir.hex
+          after.should.not == before
+        end
+
+        it "stops lightening when reaches the upper limit" do
+          3.times { @colir.lighten }
+          before = @colir.hex
+          after = @colir.lighten.hex
+          after.should == before
+        end
+
+        it "keeps changing the shade level" do
+          2.times { @colir.lighten }
+          @colir.shade.should == 2
+
+          2.times { @colir.lighten }
+          @colir.shade.should == 4
+        end
+      end
+    end
+
+  end
+end