color 1.7.1 → 2.0.0.pre.0

data/lib/color/grayscale.rb

@@ -1,197 +1,165 @@
-# A colour object representing shades of grey. Used primarily in PDF
-# document creation.
-class Color::GrayScale
+# frozen_string_literal: true
+
+##
+# \Grayscale is a color object representing shades of gray as a ratio of black to white,
+# where 0% (0.0) gray is black and 100% (1.0) gray is white.
+#
+# \Grayscale colors are immutable Data class instances. Array deconstruction is `[gray]`
+# and hash deconstruction is `{g:, gray:}`. See #g, #gray.
+class Color::Grayscale
   include Color
 
-  # The format of a DeviceGrey colour for PDF. In color-tools 2.0 this will
-  # be removed from this package and added back as a modification by the
-  # PDF::Writer package.
-  PDF_FORMAT_STR  = "%.3f %s"
+  ##
+  # :attr_reader: brightness
+  # Returns the grayscale value as a proportion of white (0.0 .. 1.0).
 
-  class << self
-    # Creates a greyscale colour object from fractional values 0..1.
-    #
-    #   Color::GreyScale.from_fraction(0.5)
-    def from_fraction(g = 0, &block)
-      new(g, 1.0, &block)
-    end
+  ##
+  # :attr_reader: g
+  # Returns the grayscale value as a proportion of white (0.0 .. 1.0).
 
-    # Creates a greyscale colour object from percentages 0..100.
-    #
-    #   Color::GrayScale.from_percent(50)
-    def from_percent(g = 0, &block)
-      new(g, &block)
-    end
-  end
+  ##
+  # :attr_reader: gray
+  # Returns the grayscale value as a percentage of white (0.0 .. 100.0).
 
-  # Creates a greyscale colour object from percentages 0..100.
+  ##
+  # Creates a grayscale color object from a percentage value (0.0 .. 100.0).
+  #
+  # ```ruby
+  # Color::Grayscale.from_percentage(50) # => Grayscale [0.50%]
+  # Color::Grayscale.from_values(50) # => Grayscale [0.50%]
+  # ```
   #
-  #   Color::GrayScale.new(50)
-  def initialize(g = 0, radix = 100.0, &block) # :yields self:
-    @g = Color.normalize(g / radix)
-    block.call if block
+  # :call-seq:
+  #   from_percentage(g)
+  #   from_percentage(g:)
+  #   from_values(g)
+  #   from_values(g:)
+  def self.from_percentage(*args, **kwargs)
+    g =
+      case [args, kwargs]
+      in [[g], {}]
+        g
+      in [[], {g:}]
+        g
+      else
+        new(*args, **kwargs)
+      end
+
+    new(g: g / 100.0)
   end
 
-  # Coerces the other Color object to grayscale.
-  def coerce(other)
-    other.to_grayscale
+  class << self
+    alias_method :from_values, :from_percentage
+    alias_method :from_fraction, :new
+    alias_method :from_internal, :from_fraction # :nodoc:
   end
 
-  # Present the colour as a DeviceGrey fill colour string for PDF. This will
-  # be removed from the default package in color-tools 2.0.
-  def pdf_fill
-    PDF_FORMAT_STR % [ @g, "g" ]
+  ##
+  # Creates a grayscale color object from a fractional value (0.0 .. 1.0).
+  #
+  # ```ruby
+  # Color::Grayscale.from_fraction(0.5)
+  # Color::Grayscale.new(0.5)
+  # Color::Grayscale[g: 0.5]
+  # ```
+  def initialize(g:)
+    super(g: normalize(g))
   end
 
-  # Present the colour as a DeviceGrey stroke colour string for PDF. This
-  # will be removed from the default package in color-tools 2.0.
-  def pdf_stroke
-    PDF_FORMAT_STR % [ @g, "G" ]
-  end
+  ##
+  # Coerces the other Color object to grayscale.
+  def coerce(other) = other.to_grayscale
 
-  def to_255
-    [(@g * 255).round, 255].min
-  end
-  private :to_255
+  ##
+  # Convert \Grayscale to Color::CMYK.
+  def to_cmyk(...) = Color::CMYK.from_fraction(0, 0, 0, 1.0 - g.to_f)
 
-  # Present the colour as an HTML/CSS colour string.
-  def html
-    gs = "%02x" % to_255
-    "##{gs * 3}"
-  end
+  ##
+  # Convert \Grayscale to Color::RGB.
+  def to_rgb(...) = Color::RGB.from_fraction(g, g, g)
 
-  # Present the colour as an RGB HTML/CSS colour string (e.g., "rgb(0%, 50%,
-  # 100%)").
-  def css_rgb
-    "rgb(%3.2f%%, %3.2f%%, %3.2f%%)" % [ gray, gray, gray ]
-  end
+  ##
+  def to_grayscale(...) = self
 
-  # Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g.,
-  # "rgb(0%, 50%, 100%, 1)").
-  def css_rgba
-    "rgba(%3.2f%%, %3.2f%%, %3.2f%%, %1.2f)" % [ gray, gray, gray, 1 ]
+  ##
+  # Convert \Grayscale to Color::YIQ.
+  #
+  # This approximates the actual value, as I and Q are calculated by treating the
+  # grayscale value as a RGB value. The Y (intensity or brightness) value is the same as
+  # the grayscale value.
+  def to_yiq(...)
+    y = g
+    i = (g * 0.596) + (g * -0.275) + (g * -0.321)
+    q = (g * 0.212) + (g * -0.523) + (g * 0.311)
+    Color::YIQ.from_fraction(y, i, q)
   end
 
-  # Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180,
-  # 25%, 35%)"). Note that this will perform a #to_hsl operation.
-  def css_hsl
-    to_hsl.css_hsl
-  end
+  ##
+  # Converts \Grayscale to Color::HSL.
+  def to_hsl(...) = Color::HSL.from_fraction(0, 0, g)
 
-  # Present the colour as an HSLA (with alpha) HTML/CSS colour string (e.g.,
-  # "hsla(180, 25%, 35%, 1)"). Note that this will perform a #to_hsl
-  # operation.
-  def css_hsla
-    to_hsl.css_hsla
-  end
+  ##
+  # Converts \Grayscale to Color::CIELAB via Color::RGB.
+  def to_lab(...) = to_rgb(...).to_lab(...)
 
-  # Convert the greyscale colour to CMYK.
-  def to_cmyk
-    k = 1.0 - @g.to_f
-    Color::CMYK.from_fraction(0, 0, 0, k)
+  ##
+  # Present the color as an HTML/CSS color string (e.g., `#dddddd`).
+  def html
+    "##{("%02x" % translate_range(g, to: 0.0..255.0)) * 3}"
   end
 
-  # Convert the greyscale colour to RGB.
-  def to_rgb(ignored = true)
-    Color::RGB.from_fraction(g, g, g)
-  end
+  ##
+  # Present the color as a CSS `rgb` color with optional `alpha`.
+  #
+  # ```ruby
+  # Color::Grayscale[0.5].css               # => rgb(50.00% 50.00% 50.00%)
+  # Color::Grayscale[0.5].css(alpha: 0.75)  # => rgb(50.00% 50.00% 50.00% / 0.75)
+  # ```
+  def css(alpha: nil)
+    params = ([css_value(gray, :percent)] * 3).join(" ")
+    params = "#{params} / #{css_value(alpha)}" if alpha
 
-  # Reflexive conversion.
-  def to_grayscale
-    self
+    "rgb(#{params})"
   end
-  alias to_greyscale to_grayscale
 
-  # Lightens the greyscale colour by the stated percent.
-  def lighten_by(percent)
-    g = [@g + (@g * (percent / 100.0)), 1.0].min
-    Color::GrayScale.from_fraction(g)
-  end
+  ##
+  # Lightens the grayscale color by the stated percent.
+  def lighten_by(percent) = Color::Grayscale.from_fraction([g + (g * (percent / 100.0)), 1.0].min)
 
-  # Darken the greyscale colour by the stated percent.
-  def darken_by(percent)
-    g = [@g - (@g * (percent / 100.0)), 0.0].max
-    Color::GrayScale.from_fraction(g)
-  end
+  ##
+  # Darken the grayscale color by the stated percent.
+  def darken_by(percent) = Color::Grayscale.from_fraction([g - (g * (percent / 100.0)), 0.0].max)
 
-  # Returns the YIQ (NTSC) colour encoding of the greyscale value. This is
-  # an approximation, as the values for I and Q are calculated by treating
-  # the greyscale value as an RGB value. The Y (intensity or brightness)
-  # value is the same as the greyscale value.
-  def to_yiq
-    y = @g
-    i = (@g * 0.596) + (@g * -0.275) + (@g * -0.321)
-    q = (@g * 0.212) + (@g * -0.523) + (@g *  0.311)
-    Color::YIQ.from_fraction(y, i, q)
-  end
+  ##
+  alias_method :brightness, :g
 
-  # Returns the HSL colour encoding of the greyscale value.
-  def to_hsl
-    Color::HSL.from_fraction(0, 0, @g)
-  end
+  ##
+  def gray = g * 100.0
 
-  # Returns the brightness value for this greyscale value; this is the
-  # greyscale value itself.
-  def brightness
-    @g
-  end
+  ##
+  def inspect = "Grayscale [%.2f%%]" % [gray] # :nodoc:
 
-  # Returns the grayscale value as a percentage of white (100% gray is
-  # white).
-  def gray
-    @g * 100.0
-  end
-  alias grey gray
-  # Returns the grayscale value as a fractional value of white in the range
-  # 0.0 .. 1.0.
-  def g
-    @g
-  end
-  # Sets the grayscale value as a percentage of white.
-  def gray=(gg)
-    @g = Color.normalize(gg / 100.0)
-  end
-  alias grey= gray= ;
-  # Returns the grayscale value as a fractional value of white in the range
-  # 0.0 .. 1.0.
-  def g=(gg)
-    @g = Color.normalize(gg)
+  ##
+  def pretty_print(q) # :nodoc:
+    q.text "Grayscale"
+    q.breakable
+    q.group 2, "[", "]" do
+      q.text "%.2f%%" % gray
+    end
   end
 
-  # Adds another colour to the current colour. The other colour will be
-  # converted to grayscale before addition. This conversion depends upon a
-  # #to_grayscale method on the other colour.
-  #
-  # The addition is done using the grayscale accessor methods to ensure a
-  # valid colour in the result.
-  def +(other)
-    self.class.from_fraction(g + other.to_grayscale.g)
-  end
+  ##
+  def to_a = [gray] # :nodoc:
 
-  # Subtracts another colour to the current colour. The other colour will be
-  # converted to grayscale before subtraction. This conversion depends upon
-  # a #to_grayscale method on the other colour.
-  #
-  # The subtraction is done using the grayscale accessor methods to ensure a
-  # valid colour in the result.
-  def -(other)
-    self + (-other)
-  end
+  ##
+  alias_method :deconstruct, :to_a
 
-  def inspect
-    "Gray [%.2f%%]" % [ gray ]
-  end
+  ##
+  def deconstruct_keys(_keys) = {g:, gray:}
 
-  def to_a
-    [ g ]
-  end
+  ##
+  def to_internal = [g] # :nodoc:
 
-  def -@
-    gs = self.dup
-    gs.instance_variable_set(:@g, -g)
-    gs
-  end
+  ##
+  def components = 1 # :nodoc:
 end
-
-# A synonym for Color::GrayScale.
-Color::GreyScale = Color::GrayScale