redgreenblue 0.7.0 → 0.12.0

data/lib/redgreenblue/hex.rb

@@ -1,35 +1,66 @@
 class RGB
 
+  # Returns a 6-digit hexadecimal string representing the object's red, green, and blue components as 8-bit values.
+  #
+  # If shorthand is true, returns 3-digit shorthand if possible.
   def hex(shorthand=false)
     if shorthand
-      RGB.hex_shorthand hexadecimal
+      RGB.hex_shorthand hex6
     else
-      hexadecimal
+      hex6
     end
   end
 
-  def hex=(s)
-    if ( s =~ /^(#?)(\h\h)(\h\h)(\h\h)$/ ) # 6-digit hex
-      self.rgb = [ $2.to_i(16), $3.to_i(16), $4.to_i(16) ]
-    elsif  ( s =~ /^(#?)(\h)(\h)(\h)$/ ) # 3-digit hex
-      self.rgb = [ ($2*2).to_i(16), ($3*2).to_i(16), ($4*2).to_i(16) ]
+  # Sets red, green, and blue using a 6- or 3-digit hexadecimal string.
+  #
+  # The string may include a '#' prefix.
+  def hex=(hex_string)
+    if rgb = RGB.hex_to_rgb(hex_string)
+      self.rgb = rgb
+    else
+      raise ArgumentError, "'#{hex_string}' is not a usable hexadecimal string"
+    end
+  end
+
+
+# Class methods
+
+
+  # Creates a new object from a 6- or 3-digit hexadecimal string representing red, green, and blue.
+  #
+  # The string may include a '#' prefix.
+  def self.hex(hex_string)
+    if rgb = RGB.hex_to_rgb(hex_string)
+      self.rgb rgb
+    else
+      raise ArgumentError, "'#{hex_string}' is not a usable hexadecimal string"
     end
   end
 
-  # factory method
-  def self.hex(s)
-    c = self.new
-    c.hex = s
-    c
+  # Returns a 3-digit shorthand version of a 6-digit hexadecimal string.
+  #
+  # If a shorthand version is not possible, returns the original string.
+  def self.hex_shorthand(hex_string)
+    hex_string.sub( /^(#?)(\h)\2(\h)\3(\h)\4$/, '\1\2\3\4' )
   end
 
-  def self.hex_shorthand(h)
-    h.sub( /^(#?)(\h)\2(\h)\3(\h)\4$/, '\1\2\3\4' )
+  # Parses a 6- or 3-digit hexadecimal string.
+  # Returns three integers in the range 0..255, or nil if not successful.
+  #
+  # The string may include a '#' prefix.
+  def self.hex_to_rgb(hex_string)
+    if hex_string =~ /^(#?)(\h\h)(\h\h)(\h\h)$/
+      [$2, $3, $4].map { |h| h.to_i(16) }
+    elsif hex_string =~ /^(#?)(\h)(\h)(\h)$/
+      [$2, $3, $4].map { |h| (h*2).to_i(16) }
+    else
+      nil
+    end
   end
 
   private
 
-  def hexadecimal
+  def hex6
     '%02x%02x%02x' % [ r, g, b ]
   end
 

data/lib/redgreenblue/hsb.rb

@@ -0,0 +1,61 @@
+require 'redgreenblue/hsv'
+
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB object from HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
+    alias hsb hsv
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  # Returns color as HSB:
+  # hue (0..360), saturation (0..1), brightness (0..1).
+  # When saturation is 0, hue is nil.
+  alias hsb         hsv
+
+  # Returns the object's HSB-hue (0..360).
+  alias hsb_h       hsv_h
+
+  # Returns the object's HSB-saturation (0..1).
+  alias hsb_s       hsv_s
+
+  # Returns the object's HSB-brightness (0..1).
+  alias hsb_b       hsv_v
+
+  # Sets red, green, and blue using HSB values: hue (0..360), saturation (0..1), and brightness (0..1).
+  alias hsb=        hsv=
+
+  # Sets HSB-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving HSB-saturation and -brightness unchanged.
+  # When hue is nil, saturation will be 0.
+  alias hsb_h=      hsv_h=
+
+  # Sets HSB-saturation to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSB-hue and -brightness unchanged.
+  # When saturation is 0, hue will be nil.
+  alias hsb_s=      hsv_s=
+
+  # Sets HSB-brightness to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSB-hue and -saturation unchanged.
+  # When brightness is 0, hue will be nil, and saturation will be 0.
+  alias hsb_b=      hsv_v=
+
+  # Sets red, green, and blue by rotating the object's HSB-hue a number of degrees.
+  alias hsb_rotate! hsv_rotate!
+
+  # Creates one or more new RGB objects by rotating this object's HSB-hue a number of degrees.
+  alias hsb_rotate  hsv_rotate
+
+end

data/lib/redgreenblue/hsl.rb

@@ -0,0 +1,96 @@
+require 'redgreenblue/hsx_shared'
+require 'redgreenblue/math'
+
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB object from HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+    def hsl(*a)
+      new hsl_to_values(*a)
+    end
+
+    # Calculates RGB values from HSL.
+    # Given hue (0..360), saturation (0..1), and lightness (0..1),
+    # returns red, green, and blue as three values between 0 and 1.
+    def hsl_to_values(*a)
+      hsm_to_values(:hsl, a)
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  # Returns color as HSL:
+  # hue (0..360), saturation (0..1), lightness (0..1).
+  # When saturation is 0, hue is nil.
+  def hsl
+    hsl_hsv_c[0]
+  end
+
+  # Returns the object's HSL-hue (0..360).
+  def hsl_h
+    hsl[0]
+  end
+
+  # Returns the object's HSL-saturation (0..1).
+  def hsl_s
+    hsl[1]
+  end
+
+  # Returns the object's HSL-lightness (0..1).
+  def hsl_l
+    hsl[2]
+  end
+
+  # Sets red, green, and blue using HSL values: hue (0..360), saturation (0..1), and lightness (0..1).
+  def hsl=(*a)
+    self.values = RGB.hsl_to_values(*a)
+  end
+
+  # Sets HSL-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving saturation and lightness unchanged.
+  # When hue is nil, saturation will be 0.
+  def hsl_h=(degrees)
+    self.hsl = hsl.fill(degrees,0,1)
+  end
+
+  # Sets HSL-saturation to a value between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving hue and lightness unchanged.
+  # When saturation is 0, hue will be nil.
+  def hsl_s=(value)
+    self.hsl = hsl.fill(value  ,1,1)
+  end
+
+  # Sets HSL-lightness to a value between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving hue and saturation unchanged.
+  # When lightness is 0 or 1, hue will be nil, and saturation will be 0.
+  def hsl_l=(value)
+    self.hsl = hsl.fill(value  ,2,1)
+  end
+
+  # Sets red, green, and blue by rotating the object's HSL-hue a number of degrees.
+  def hsl_rotate!(degrees)
+    self.hsl = zip_add(hsl, [degrees, 0, 0])
+    self
+  end
+
+  # Creates one or more new RGB objects by rotating this object's HSL-hue a number of degrees.
+  def hsl_rotate(a_degrees, *b_degrees)
+    if a_degrees.class != Array and b_degrees.none?
+      RGB.hsl zip_add(hsl, [a_degrees, 0, 0])
+    else
+      ( [a_degrees] + b_degrees ).flatten.map { |degrees| RGB.hsl zip_add(hsl, [degrees, 0, 0]) }
+    end
+  end
+
+end

data/lib/redgreenblue/hsv.rb

@@ -0,0 +1,96 @@
+require 'redgreenblue/hsx_shared'
+require 'redgreenblue/math'
+
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    # Creates a new RGB object from HSV values: hue (0..360), saturation (0..1), and value (0..1).
+    def hsv(*a)
+      new hsv_to_values(*a)
+    end
+
+    # Calculates RGB values from HSV.
+    # Given hue (0..360), saturation (0..1), and value (0..1),
+    # returns red, green, and blue as three values between 0 and 1.
+    def hsv_to_values(*a)
+      hsm_to_values(:hsv, a)
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  # Returns color as HSV:
+  # hue (0..360), saturation (0..1), value (0..1).
+  # When saturation is 0, hue is nil.
+  def hsv
+    hsl_hsv_c[1]
+  end
+
+  # Returns the object's HSV-hue (0..360).
+  def hsv_h
+    hsv[0]
+  end
+
+  # Returns the object's HSV-saturation (0..1).
+  def hsv_s
+    hsv[1]
+  end
+
+  # Returns the object's HSV-value (0..1).
+  def hsv_v
+    hsv[2]
+  end
+
+  # Sets red, green, and blue using HSV values: hue (0..360), saturation (0..1), and value (0..1).
+  def hsv=(*a)
+    self.values = RGB.hsv_to_values(*a)
+  end
+
+  # Sets HSV-hue to a number of degrees (0..360) or nil.
+  #
+  # Adjusts red, green, and blue, leaving HSV-saturation and -value unchanged.
+  # When hue is nil, saturation will be 0.
+  def hsv_h=(degrees)
+    self.hsv = hsv.fill(degrees,0,1)
+  end
+
+  # Sets HSV-saturation to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSV-hue and -value unchanged.
+  # When saturation is 0, hue will be nil.
+  def hsv_s=(value)
+    self.hsv = hsv.fill(value  ,1,1)
+  end
+
+  # Sets HSV-value to a number between 0 and 1.
+  #
+  # Adjusts red, green, and blue, leaving HSV-hue and -saturation unchanged.
+  # When value is 0, hue will be nil, and saturation will be 0.
+  def hsv_v=(value)
+    self.hsv = hsv.fill(value  ,2,1)
+  end
+
+  # Sets red, green, and blue by rotating the object's HSV-hue a number of degrees.
+  def hsv_rotate!(degrees)
+    self.hsv = zip_add(hsv, [degrees, 0, 0])
+    self
+  end
+
+  # Creates one or more new RGB objects by rotating this object's HSV-hue a number of degrees.
+  def hsv_rotate(a_degrees, *b_degrees)
+    if a_degrees.class != Array and b_degrees.none?
+      RGB.hsv zip_add(hsv, [a_degrees, 0, 0])
+    else
+      ( [a_degrees] + b_degrees ).flatten.map { |degrees| RGB.hsv zip_add(hsv, [degrees, 0, 0]) }
+    end
+  end
+
+end

data/lib/redgreenblue/hsx_shared.rb

@@ -0,0 +1,94 @@
+class RGB
+
+  #----------------------------------------------------------------------#
+  #                            Class Methods                             #
+  #----------------------------------------------------------------------#
+
+  class << self
+
+    private
+
+    # Calculates RGB values from HSL or HSV.
+    # With help from:
+    # - https://en.wikipedia.org/wiki/HSL_and_HSV
+    def hsm_to_values(type, *a)
+      raise NotImplementedError unless [:hsl, :hsv].include? type
+
+      hue, saturation, magnitude = a.flatten
+
+      if ( saturation == 0 ) or ( ! hue )
+        return Array.new(3) { magnitude }
+      end
+
+      hue = hue.modulo 360
+
+      chroma = case type
+        when :hsl
+          ( 1 - ( 2 * magnitude - 1 ).abs ) * saturation
+        when :hsv
+          magnitude * saturation
+      end
+
+      values = [
+        chroma,
+        ( 1 - ( ( hue / 60.0 ).modulo(2) - 1 ).abs ) * chroma,
+        0
+      ]
+
+      values = case type
+        when :hsl
+          values.map { |v| ( v + magnitude - chroma / 2.0 ).round(9) }
+        when :hsv
+          values.map { |v| ( v + magnitude - chroma       ).round(9) }
+      end
+
+      # order values according to hue sextant
+      [ [0,1,2], [1,0,2], [2,0,1], [2,1,0], [1,2,0], [0,2,1] ][hue.div 60].map { |i| values[i]}
+    end
+
+  end
+
+  #----------------------------------------------------------------------#
+  #                           Instance Methods                           #
+  #----------------------------------------------------------------------#
+
+  private
+
+  # Compute HSL, HSV, and chroma.
+  # With help from:
+  # - https://en.wikipedia.org/wiki/HSL_and_HSV
+  def hsl_hsv_c
+    sorted_hash = to_h
+    min, max = sorted_hash.values.values_at(2,0)
+
+    chroma = max - min
+
+    hue =
+      if chroma == 0
+        nil
+      else
+        ( case sorted_hash.keys.first
+          when :red
+            60 * ( ( ( green - blue  ) / chroma ).modulo 6 )
+          when :green
+            60 * ( (   blue  - red   ) / chroma + 2 )
+          when :blue
+            60 * ( (   red   - green ) / chroma + 4 )
+          end
+        ).round(6)
+      end
+
+    lightness = ( min + max ) / 2.0
+
+    saturation_hsl =
+      chroma == 0 ? 0.0 : ( chroma / ( 1 - (2 * lightness - 1).abs ) ).round(9)
+
+    value = max
+
+    saturation_hsv =
+      value == 0 ? 0.0 : chroma / value
+
+    [ [hue, saturation_hsl, lightness], [hue, saturation_hsv, value], chroma ]
+  end
+
+end

data/lib/redgreenblue/inspect.rb

@@ -0,0 +1,73 @@
+class RGB
+
+  private
+
+  def _inspect_default(prefix='RGB')
+    "#{prefix} #{_inspect_hex} (red=%1.5f green=%1.5f blue=%1.5f)" % [red, green, blue] + ( name ? ' ' + name : '' )
+  end
+
+  def _inspect_hex
+    (self == snap ? '#' : '~') + hex
+  end
+
+  def _inspect_swatch
+    terminal_background + "   \e[0m"
+  end
+
+  def _inspect_short
+    "#{_inspect_swatch} #{_inspect_hex}"
+  end
+
+  def _inspect_simple
+    _inspect_default _inspect_swatch
+  end
+
+  def _inspect_name
+    _inspect_swatch + ( name ? ' ' + name : '' )
+  end
+
+  public
+
+  # Returns a programmer-friendly representation of the object.
+  #
+  # You can choose among several inspect styles. See the styles, style, and style= class methods.
+  def inspect
+    send "_inspect_#{self.class.style}"
+  end
+
+  # Returns a string representation of the object.
+  def to_s
+    _inspect_default
+  end
+
+  # Returns the base inspect style, dependent on the COLORTERM environment variable.
+  def self.base_style
+    if styles.include? ENV['REDGREENBLUE_STYLE']
+      ENV['REDGREENBLUE_STYLE']
+    else
+      if ENV['COLORTERM'] == 'truecolor'
+        'simple'
+      else
+        'default'
+      end
+    end
+  end
+
+  # Returns the current inspect style.
+  def self.style
+    @@style ||= base_style
+  end
+
+  # Returns a list of all available inspect styles.
+  def self.styles
+    ( self.instance_methods + self.private_instance_methods ).grep( /^_inspect_(.*)/ ) { $1 }.sort
+  end
+
+  # Selects an inspect style.
+  #
+  # Only the first few characters of your preferred style are required.
+  def self.style=(s)
+    @@style = styles.grep( /^#{s.to_s.downcase}/ ).first || style
+  end
+
+end