chroma 0.0.1.alpha.2 → 0.0.1.alpha.3

data/lib/chroma/color_modes.rb

@@ -3,11 +3,36 @@ module Chroma
     class << self
       private
 
-      def build(*attrs)
-        Class.new do
-          attr_accessor *(attrs + [:a])
+      # Builds a new color mode class.
+      #
+      # @param name  [String]        the class name
+      # @param attrs [Array<Symbol>] the instance attribute names
+      # @!macro [attach] build
+      #   @!parse class $1
+      #     attr_accessor :$2, :$3, :$4, :a
+      #
+      #     # @param $2 [Numeric]
+      #     # @param $3 [Numeric]
+      #     # @param $4 [Numeric]
+      #     # @param a [Numeric]
+      #     def initialize(${2-4}, a = 1)
+      #       @$2, @$3, @$4, @a = $2, $3, $4, a
+      #     end
+      #
+      #     # Returns the values `$2`, `$3`, `$4`, and `a` as an array.
+      #     #
+      #     # @return [Array<Numeric>]
+      #     def to_a
+      #       [@$2, @$3, @$4, @a]
+      #     end
+      #
+      #     alias_method :to_ary, :to_a
+      #     end
+      def build(name, *attrs)
+        class_eval <<-EOS
+          class #{name}
+            attr_accessor #{(attrs + [:a]).map{|attr| ":#{attr}"} * ', '}
 
-          class_eval <<-EOS
             def initialize(#{attrs * ', '}, a = 1)
               #{attrs.map{|attr| "@#{attr}"} * ', '}, @a = #{attrs * ', '}, a
             end
@@ -17,13 +42,15 @@ module Chroma
             end
 
             alias_method :to_ary, :to_a
-          EOS
-        end
+          end
+        EOS
       end
     end
 
-    Rgb = build :r, :g, :b
-    Hsl = build :h, :s, :l
-    Hsv = build :h, :s, :v
+    private
+
+    build 'Rgb', :r, :g, :b
+    build 'Hsl', :h, :s, :l
+    build 'Hsv', :h, :s, :v
   end
 end

data/lib/chroma/converters/base.rb

@@ -1,20 +1,30 @@
 module Chroma
   module Converters
+    # Base class for converting one color mode to another.
+    # @abstract
     class Base
       include Helpers::Bounders
 
+      # @param input [ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
+      # @return [Base]
       def initialize(input)
         @input = input
       end
 
+      # @param rgb [ColorModes::Rgb]
+      # @return [ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
       def self.convert_rgb(rgb)
         new(rgb).convert_rgb
       end
 
+      # @param hsl [ColorModes::Hsl]
+      # @return [ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
       def self.convert_hsl(hsl)
         new(hsl).convert_hsl
       end
 
+      # @param hsv [ColorModes::Hsv]
+      # @return [ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
       def self.convert_hsv(hsv)
         new(hsv).convert_hsv
       end

data/lib/chroma/converters/hsl_converter.rb

@@ -1,6 +1,9 @@
 module Chroma
   module Converters
+    # Class to convert a color mode to {ColorModes::Hsl}.
     class HslConverter < Base
+      # Convert rgb to hsl.
+      # @return [ColorModes::Hsl]
       def convert_rgb
         r = bound01(@input.r, 255)
         g = bound01(@input.g, 255)
@@ -35,10 +38,14 @@ module Chroma
         ColorModes::Hsl.new(h * 360, s, l, @input.a)
       end
 
+      # Returns @input because it's the same color mode.
+      # @return [ColorModes::Hsl]
       def convert_hsl
         @input
       end
 
+      # Convert hsv to hsl.
+      # @return [ColorModes::Hsl]
       def convert_hsv
         HsvConverter.convert_rgb(RgbConverter.convert_hsl(@input))
       end

data/lib/chroma/converters/hsv_converter.rb

@@ -1,6 +1,9 @@
 module Chroma
   module Converters
+    # Class to convert a color mode to {ColorModes::Hsl}.
     class HsvConverter < Base
+      # Convert rgb to hsv.
+      # @return [ColorModes::Hsv]
       def convert_rgb
         r = bound01(@input.r, 255)
         g = bound01(@input.g, 255)
@@ -29,10 +32,14 @@ module Chroma
         ColorModes::Hsv.new(h * 360, s, v, @input.a)
       end
 
+      # Convert hsl to hsv.
+      # @return [ColorModes::Hsv]
       def convert_hsl
         HslConverter.convert_rgb(RgbConverter.convert_hsv(@input))
       end
 
+      # Returns @input because it's the same color mode.
+      # @return [ColorModes::Hsv]
       def convert_hsv
         @input
       end

data/lib/chroma/converters/rgb_converter.rb

@@ -1,10 +1,15 @@
 module Chroma
   module Converters
+    # Class to convert a color mode to {ColorModes::Rgb}.
     class RgbConverter < Base
+      # Returns @input because it's the same color mode.
+      # @return [ColorModes::Rgb]
       def convert_rgb
         @input
       end
 
+      # Convert hsl to rgb.
+      # @return [ColorModes::Rgb]
       def convert_hsl
         h, s, l = @input
 
@@ -25,6 +30,8 @@ module Chroma
         ColorModes::Rgb.new(r, g, b, bound_alpha(@input.a))
       end
 
+      # Convert hsv to rgb.
+      # @return [ColorModes::Rgb]
       def convert_hsv
         h, s, v = @input
 

data/lib/chroma/errors.rb

@@ -0,0 +1,6 @@
+module Chroma
+  module Errors
+    class PaletteDefinedError < StandardError; end
+    class UnrecognizedColor < StandardError; end
+  end
+end

data/lib/chroma/extensions/string.rb

@@ -1,4 +1,15 @@
 class String
+  # Creates {Chroma::Color} directly from a string representing a color.
+  #
+  # @example
+  #   'red'.paint
+  #   '#f00'.paint
+  #   '#ff0000'.paint
+  #   'rgb(255, 0, 0)'.paint
+  #   'hsl(0, 100%, 50%)'.paint
+  #   'hsv(0, 100%, 100%)'.paint
+  #
+  # @return [Chroma::Color]
   def paint
     Chroma.paint(self)
   end

data/lib/chroma/harmonies.rb

@@ -1,55 +1,138 @@
 module Chroma
+  # Class to hold all palette methods.
   class Harmonies
+    # @param color [Color]
     def initialize(color)
       @color = color
     end
 
-    def complement
-      [@color, @color.complement]
+    # Generate a complement palette.
+    #
+    # @example
+    #   'red'.paint.palette.complement            #=> [red, cyan]
+    #   'red'.paint.palette.complement(as: :name) #=> ['red', 'cyan']
+    #   'red'.paint.palette.complement(as: :hex)  #=> ['#ff0000', '#00ffff']
+    #
+    # @param options [Hash]
+    # @option options :as [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def complement(options = {})
+      with_reformat([@color, @color.complement], options[:as])
     end
 
-    def triad
-      hsl_map([0, 120, 240])
+    # Generate a triad palette.
+    #
+    # @example
+    #   'red'.paint.palette.triad            #=> [red, lime, blue]
+    #   'red'.paint.palette.triad(as: :name) #=> ['red', 'lime', 'blue']
+    #   'red'.paint.palette.triad(as: :hex)  #=> ['#ff0000', '#00ff00', '#0000ff']
+    #
+    # @param options [Hash]
+    # @option options :as [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def triad(options = {})
+      hsl_map([0, 120, 240], options)
     end
 
-    def tetrad
-      hsl_map([0, 90, 180, 270])
+    # Generate a tetrad palette.
+    #
+    # @example
+    #   'red'.paint.palette.tetrad            #=> [red, #80ff00, cyan, #7f00ff]
+    #   'red'.paint.palette.tetrad(as: :name) #=> ['red', '#80ff00', 'cyan', '#7f00ff']
+    #   'red'.paint.palette.tetrad(as: :hex)  #=> ['#ff0000', '#80ff00', '#00ffff', '#7f00ff']
+    #
+    # @param options [Hash]
+    # @option options :as [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def tetrad(options = {})
+      hsl_map([0, 90, 180, 270], options)
     end
 
-    def split_complement
-      hsl_map([0, 72, 216])
+    # Generate a split complement palette.
+    #
+    # @example
+    #   'red'.paint.palette.split_complement            #=> [red, #ccff00, #0066ff]
+    #   'red'.paint.palette.split_complement(as: :name) #=> ['red', '#ccff00', '#0066ff']
+    #   'red'.paint.palette.split_complement(as: :hex)  #=> ['#ff0000', '#ccff00', '#0066ff']
+    #
+    # @param options [Hash]
+    # @option options :as [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def split_complement(options = {})
+      hsl_map([0, 72, 216], options)
     end
 
-    def analogous(results = 6, slices = 30)
+    # Generate an analogous palette.
+    #
+    # @example
+    #   'red'.paint.palette.analogous                         #=> [red, #ff0066, #ff0033, red, #ff3300, #ff6600]
+    #   'red'.paint.palette.analogous(as: :hex)               #=> ['#f00', '#f06', '#f03', '#f00', '#f30', '#f60']
+    #   'red'.paint.palette.analogous(results: 3)             #=> [red, #ff001a, #ff1a00]
+    #   'red'.paint.palette.analogous(results: 3, slices: 60) #=> [red, #ff000d, #ff0d00]
+    #
+    # @param options [Hash]
+    # @option options :results [Symbol] (6) number of results to return
+    # @option options :slices  [Symbol] (30)
+    #   the angle in degrees to slice the hue circle per color
+    # @option options :as      [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def analogous(options = {})
+      results = options[:results] || 6
+      slices = options[:slices] || 30
+
       hsl = @color.hsl
       part = 360 / slices
       hsl.h = ((hsl.h - (part * results >> 1)) + 720) % 360
 
-      (results - 1).times.reduce([@color]) do |arr, n|
+      palette = (results - 1).times.reduce([@color]) do |arr, n|
         hsl.h = (hsl.h + part) % 360
-        arr << Color.new(hsl)
+        arr << Color.new(hsl, @color.format)
       end
+
+      with_reformat(palette, options[:as])
     end
 
-    def monochromatic(results = 6)
+    # Generate a monochromatic palette.
+    #
+    # @example
+    #   'red'.paint.palette.monochromatic             #=> [red, #2a0000, #550000, maroon, #aa0000, #d40000]
+    #   'red'.paint.palette.monochromatic(as: :hex)   #=> ['#ff0000', '#2a0000', '#550000', '#800000', '#aa0000', '#d40000']
+    #   'red'.paint.palette.monochromatic(results: 3) #=> [red, #550000, #aa0000]
+    #
+    # @param options [Hash]
+    # @option options :results [Symbol] (6) number of results to return
+    # @option options :as      [Symbol] (nil) optional format to output colors as strings
+    # @return [Array<Color>, Array<String>] depending on presence of `options[:as]`
+    def monochromatic(options = {})
+      results = options[:results] || 6
+
       h, s, v = @color.hsv
       modification = 1.0 / results
 
-      results.times.map do
-        Color.new(ColorModes::Hsv.new(h, s, v)).tap do
+      palette = results.times.map do
+        Color.new(ColorModes::Hsv.new(h, s, v), @color.format).tap do
           v = (v + modification) % 1
         end
       end
+
+      with_reformat(palette, options[:as])
     end
 
     private
 
-    def hsl_map(degrees)
+    def with_reformat(palette, as)
+      palette.map! { |color| color.to_s(as) } unless as.nil?
+      palette
+    end
+
+    def hsl_map(degrees, options)
       h, s, l = @color.hsl
 
-      degrees.map do |deg|
-        Color.new(ColorModes::Hsl.new((h + deg) % 360, s, l))
+      degrees.map! do |deg|
+        Color.new(ColorModes::Hsl.new((h + deg) % 360, s, l), @color.format)
       end
+
+      with_reformat(degrees, options[:as])
     end
   end
 end

data/lib/chroma/helpers/bounders.rb

@@ -1,26 +1,44 @@
 module Chroma
   module Helpers
     module Bounders
+      # Bounds a value `n` that is from `0` to `max` to `0` to `1`.
+      #
+      # @param n   [Numeric, String]
+      # @param max [Fixnum]
+      # @return    [Float]
       def bound01(n, max)
         is_percent = n.to_s.include? '%'
         n = [max, [0, n.to_f].max].min
-        n = (n * max).to_i / 100 if is_percent
+        n = (n * max).to_i / 100.0 if is_percent
 
         return 1 if (n - max).abs < 0.000001
 
         (n % max) / max.to_f
       end
 
+      # Ensure alpha value `a` is between `0` and `1`.
+      #
+      # @param a [Numeric, String] alpha value
+      # @return  [Numeric]
       def bound_alpha(a)
         a = a.to_f
         a = 1 if a < 0 || a > 1
         a
       end
 
+      # Ensures a number between `0` and `1`. Returns `n` if it is between `0`
+      #   and `1`.
+      #
+      # @param n [Numeric]
+      # @return  [Numeric]
       def clamp01(n)
         [1, [0, n].max].min
       end
 
+      # Converts `n` to a percentage type value.
+      #
+      # @param n [Numeric, String]
+      # @return  [String, Float]
       def to_percentage(n)
         n = n.to_f
         n = "#{n * 100}%" if n <= 1

data/lib/chroma/palette_builder.rb

@@ -1,14 +1,25 @@
 module Chroma
+  # Class internally used to build custom palettes from {Chroma.define_palette}.
   class PaletteBuilder
+    # Wrapper to instantiate a new instance of {PaletteBuilder} and call its
+    #   {PaletteBuilder#build} method.
+    #
+    # @param name  [Symbol, String] the name of the custom palette
+    # @param block [Proc]           the palette definition block
+    # @return      [Symbol, String] the name of the custom palette
     def self.build(name, &block)
       new(name, &block).build
     end
 
+    # @param name  [Symbol, String] the name of the custom palette
+    # @param block [Proc]           the palette definition block
     def initialize(name, &block)
       @name = name
       @block = block
     end
 
+    # Build the custom palette by defining a new method on {Harmonies}.
+    # @return [Symbol, String] the name of the custom palette
     def build
       dsl = PaletteBuilderDsl.new
       dsl.instance_eval(&@block)
@@ -23,6 +34,7 @@ module Chroma
 
     private
 
+    # Internal class for palette building DSL syntax.
     class PaletteBuilderDsl
       attr_reader :conversions
 
@@ -36,6 +48,8 @@ module Chroma
         end
       end
 
+      # Internal class to represent color modification calls in the palette
+      # builder DSL definition syntax.
       class ColorCalls
         attr_reader :name, :args
 

data/lib/chroma/rgb_generator.rb

@@ -1,6 +1,13 @@
 module Chroma
+  # Main module to generate an instance of {ColorModes::Rgb} from several
+  # possible inputs.
   module RgbGenerator
     class << self
+      # Generates an instance of {ColorModes::Rgb} as well as color format
+      #   symbol.
+      #
+      # @param input [String, ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
+      # @return      [[ColorModes::Rgb, Symbol]]
       def generate_rgb_and_format(input)
         get_generator(input).generate.tap do |(rgb)|
           rgb.r = round(rgb.r)
@@ -23,12 +30,7 @@ module Chroma
       end
 
       def round(n)
-        if n < 1
-          n.round
-        else
-          #(n * 100).round / 100
-          n
-        end
+        n < 1 ? n.round : n
       end
     end
   end