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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83b41e45a991b08c177b51e08ad7147ff5f22d60
-  data.tar.gz: b55cf5c98e93305486a863a38cc1642fd695b57a
+  metadata.gz: 763b7f5b0794c7dc09cd95962cd7735112f6d097
+  data.tar.gz: 03ff16e0f2504635475ae9d310ca3d8aef338fd3
 SHA512:
-  metadata.gz: c6a283052b0210c1434cc8492063bf95a7653bf28c08111e840b9a0d77d936d29c6b761498bdcc940ad62e5f579df217311cf740c12d8ca7023780795571106c
-  data.tar.gz: 8e61b3b0060212abcab4ba2de3d1a3d700c91ecd6dc1b8dec3f154fa954e39149f6d7ee73627b085cd4efe245162954424e68632967f7df4317185ac33ebf807
+  metadata.gz: 5fd92090950985a25e34d1ecf90387cc1e409473e9907f153e31c6b41aff2be6f835eb3b1a0ff69e6308f427b424ac62f1c803fc53d34bc21e45679f55f25dd3
+  data.tar.gz: 64e588328d689f4774d9154681549b80dee94f2944686b97f8029a136d0b796dc1427097ff45fe8d19194913d91061e957bcf1b09eac778f4c003383754746c9

data/.yardopts

@@ -0,0 +1 @@
+--markup=markdown

data/CHANGELOG.md

@@ -1,5 +1,33 @@
-### v0.0.1.alpha.2
+### [v0.0.1.alpha.3] - 2015-01-13
+
+**Bug Fixes:**
+
+* Fix bug where `Color#complement` didn't return a color of the same format.
+* Fix bug where palettes did not have the same format as the seed color. (#16)
+* Fix bug where the helper method `bound01` was not always producing accurate
+  results for percentages due to integer division.
+* Fix bug where a `Color` created from an rgba string
+  (e.g. `'rgba(255, 0, 0, 0.5).paint'`) was not serializing to an rgba string
+  from `to_s`. (#17)
+
+**Method Changes:**
+
+* Add `Color#format` method to return `@format` instance variable.
+* Change arguments for `analogous` and `monochromatic` to option arguments.
+* Add ability to output palette as an array of color format strings via the
+  `:as` option. (#10)
+* On `Color` rename `greyscale` to `grayscale` and alias `greyscale` back
+  to `grayscale`.
+
+**Miscellaneous Changes:**
+
+* Introduced custom errors and replaced `raise` calls with them.
+* Added API doc headers. (#4)
+
+### [v0.0.1.alpha.2] - 2015-01-13
+
 **Bug Fixes:**
+
 * Fixed bug with number of arguments passed to generator classes in RgbGenerator. (#1)
 * Make `FromHexStringValues.from_hex8` take alpha as second parameter instead of last.
   Fixes incorrect color generation from hex8. (#6)
@@ -14,6 +42,7 @@
   wrong alpha value. (#15)
 
 **Method Changes:**
+
 * Add optional `hex_for_unknown` parameter to `Color::Serializers#to_name`.
   If true, it allows `to_name` to default to hex string if name is not found
   instead of returning `'<unknown>'`. (#2)
@@ -35,3 +64,7 @@
   * `to_rgb`    -> `rgb` (moved attr_reader to serializers and made public)
   * `to_rgb_s`  -> `to_rgb`
   * Removed `to_name_s` alias
+
+### [v0.0.1.alpha.1] - 2015-01-11
+
+* Initial release

data/README.md

@@ -1,5 +1,7 @@
 # Chroma
 
+[![Gem Version](https://badge.fury.io/rb/chroma.svg)](http://badge.fury.io/rb/chroma)
+
 Chroma is a color manipulation and palette generation library. It is heavily
 inspired by and a very close Ruby port of the
 [tinycolor.js](https://bgrins.github.io/TinyColor/)
@@ -21,7 +23,7 @@ where you feel it is necessary. Please refer to the
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'chroma', '0.0.1.alpha.1'
+gem 'chroma', '0.0.1.alpha.3'
 ```
 
 And then execute:

data/Rakefile

@@ -1,2 +1,9 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  # Rspec not available
+end

data/lib/chroma.rb

@@ -1,5 +1,6 @@
 # General
 require 'chroma/version'
+require 'chroma/errors'
 require 'yaml'
 
 # Modules
@@ -37,22 +38,80 @@ require 'chroma/converters/hsv_converter'
 # Extensions
 require 'chroma/extensions/string'
 
+# The main module.
 module Chroma
   class << self
+    # Returns a new instance of color. Supports hexadecimal, rgb, rgba, hsl,
+    # hsla, hsv, hsva, and named color formats.
+    #
+    # @api public
+    #
+    # @example
+    #   Chroma.paint('red')
+    #   Chroma.paint('#f00')
+    #   Chroma.paint('#ff0000')
+    #   Chroma.paint('rgb(255, 0, 0)')
+    #   Chroma.paint('hsl(0, 100%, 50%)')
+    #   Chroma.paint('hsv(0, 100%, 100%)')
+    #
+    # @param input [String] the color
+    # @return      [Color]  an instance of {Color}
     def paint(input)
       Color.new(input)
     end
 
+    # Returns the hexadecimal string representation of a named color and nil
+    # if no match is found. Favors 3-character hexadecimal if possible.
+    #
+    # @example
+    #   Chroma.hex_from_name('red')       #=> 'f00'
+    #   Chroma.hex_from_name('aliceblue') #=> 'f0f8ff'
+    #   Chroma.hex_from_name('foo')       #=> nil
+    #
+    # @param name [String]      the color name
+    # @return     [String, nil] the color as a string hexadecimal or nil
     def hex_from_name(name)
       named_colors_map[name]
     end
 
+    # Returns the color name of a hexadecimal color if available and nil if no
+    # match is found. Requires 3-character hexadecimal input for applicable
+    # colors.
+    #
+    # @example
+    #   Chroma.name_from_hex('f00')    #=> 'red'
+    #   Chroma.name_from_hex('f0f8ff') #=> 'aliceblue'
+    #   Chroma.name_from_hex('123123') #=> nil
+    #
+    # @param hex [String]      the hexadecimal color
+    # @return    [String, nil] the color name or nil
     def name_from_hex(hex)
       hex_named_colors_map[hex]
     end
 
+    # Defines a custom palette for use by {Color#palette}. Uses a DSL inside
+    # `block` that mirrors the methods in {Color::Modifiers}.
+    #
+    # @example
+    #   'red'.paint.palette.respond_to? :my_palette #=> false
+    #
+    #   Chroma.define_palette :my_palette do
+    #     spin 60
+    #     spin 120
+    #     spin 240
+    #   end
+    #
+    #   'red'.paint.palette.respond_to? :my_palette #=> true
+    #
+    # @param name  [Symbol, String]              the name of the custom palette
+    # @param block [Proc]                        the palette definition block
+    # @raise       [Errors::PaletteDefinedError] if the palette is already defined
+    # @return      [Symbol, String]              the name of the custom palette
     def define_palette(name, &block)
-      raise "Palette `#{name}' already exists" if Harmonies.method_defined? name
+      if Harmonies.method_defined? name
+        raise Errors::PaletteDefinedError, "Palette `#{name}' already exists"
+      end
+
       PaletteBuilder.build(name, &block)
     end
 

data/lib/chroma/color.rb

@@ -1,34 +1,83 @@
 module Chroma
+  # The main class to represent colors.
   class Color
     include Attributes
     include Serializers
     include Modifiers
     include Helpers::Bounders
 
+    # @param input  [String, ColorModes::Rgb, ColorModes::Hsl, ColorModes::Hsv]
+    # @param format [Symbol] the color mode format
     def initialize(input, format = nil)
       @input = input
       @rgb, gen_format = generate_rgb_and_format(input)
       @format = format || gen_format
     end
 
+    # Returns self. Useful for ducktyping situations with {String#paint}.
+    #
+    # @example
+    #   red = 'red'.paint
+    #
+    #   red.paint            #=> red
+    #   red.paint.equal? red #=> true
+    #
+    # @return [self]
     def paint
       self
     end
 
+    # Returns true if `self` is equal to `other` and they're both instances of
+    # {Color}.
+    #
+    # @example
+    #   red = 'red'.paint
+    #   blue = 'blue'.paint
+    #
+    #   red.eql? red          #=> true
+    #   red.eql? blue         #=> false
+    #   red.eql? '#f00'.paint #=> true
+    #
+    # @param other [Color]
+    # @return      [true, false]
     def eql?(other)
       self.class == other.class && self == other
     end
 
+    # Returns true if both are equal in value.
+    #
+    # @example
+    #   red = 'red'.paint
+    #   blue = 'blue'.paint
+    #
+    #   red == red          #=> true
+    #   red == blue         #=> false
+    #   red == '#f00'.paint #=> true
+    #
+    # @param other [Color]
+    # @return      [true, false]
     def ==(other)
       to_hex == other.to_hex
     end
 
+    # Returns the complementary color.
+    #
+    # @example
+    #   'red'.paint.complement #=> cyan
+    #
+    # @return [Color] the complementary color
     def complement
       hsl = self.hsl
       hsl.h = (hsl.h + 180) % 360
-      Color.new(hsl)
+      self.class.new(hsl, @format)
     end
 
+    # Returns an instance of {Harmonies} from which to call a palette method.
+    #
+    # @example
+    #   'red'.paint.palette #=> #<Chroma::Harmonies:0x007faf6b9f9148 @color=red>
+    #
+    # @return [Harmonies]
     def palette
       Harmonies.new(self)
     end

data/lib/chroma/color/attributes.rb

@@ -1,18 +1,49 @@
 module Chroma
   class Color
+    # Attribute methods for {Color}.
     module Attributes
+      attr_reader :format
+
+      # Determines if the color is dark.
+      #
+      # @example
+      #   'red'.paint.dark?    #=> true
+      #   'yellow'.paint.dark? #=> false
+      #
+      # @return [true, false]
       def dark?
         brightness < 128
       end
 
+      # Determines if the color is light.
+      #
+      # @example
+      #   'red'.paint.light?    #=> false
+      #   'yellow'.paint.light? #=> true
+      #
+      # @return [true, false]
       def light?
         !dark?
       end
 
+      # Returns the alpha channel value.
+      #
+      # @example
+      #   'red'.paint.alpha                #=> 1.0
+      #   'rgba(0, 0, 0, 0.5)'.paint.alpha #=> 0.5
+      #
+      # @return [Float]
       def alpha
         @rgb.a
       end
 
+      # Calculates the brightness.
+      #
+      # @example
+      #   'red'.paint.brightness    #=> 76.245
+      #   'yellow'.paint.brightness #=> 225.93
+      #
+      # @return [Float]
       def brightness
         (@rgb.r * 299 + @rgb.g * 587 + @rgb.b * 114) / 1000.0
       end

data/lib/chroma/color/modifiers.rb

@@ -1,12 +1,29 @@
 module Chroma
   class Color
+    # Methods that return a new modified {Color}.
     module Modifiers
+      # Lightens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.lighten     #=> #ff3333
+      #   'red'.paint.lighten(20) #=> #ff6666
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def lighten(amount = 10)
         hsl = self.hsl
         hsl.l = clamp01(hsl.l + amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Brightens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.brighten     #=> #ff1919
+      #   'red'.paint.brighten(20) #=> #ff3333
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def brighten(amount = 10)
         # Don't include alpha
         rgb = @rgb.to_a[0..2].map(&:round)
@@ -19,28 +36,69 @@ module Chroma
         self.class.new(ColorModes::Rgb.new(*rgb), @format)
       end
 
+      # Darkens the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.darken     #=> #cc0000
+      #   'red'.paint.darken(20) #=> #990000
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def darken(amount = 10)
         hsl = self.hsl
         hsl.l = clamp01(hsl.l - amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Desaturates the color by the given `amount`.
+      #
+      # @example
+      #   'red'.paint.desaturate     #=> #f20d0d
+      #   'red'.paint.desaturate(20) #=> #e61919
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def desaturate(amount = 10)
         hsl = self.hsl
         hsl.s = clamp01(hsl.s - amount / 100.0)
         self.class.new(hsl, @format)
       end
 
+      # Saturates the color by the given `amount`.
+      #
+      # @example
+      #   '#123'.paint.saturate     #=> #0e2236
+      #   '#123'.paint.saturate(20) #=> #0a223a
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def saturate(amount = 10)
         hsl = self.hsl
         hsl.s = clamp01(hsl.s + amount / 100.0)
         self.class.new(hsl, @format)
       end
 
-      def greyscale
+      # Converts the color to grayscale.
+      #
+      # @example
+      #   'green'.paint.greyscale #=> #404040
+      #
+      # @return [Color]
+      def grayscale
         desaturate(100)
       end
 
+      alias_method :greyscale, :grayscale
+
+      # Spins around the hue color wheel by `amount` in degrees.
+      #
+      # @example
+      #   'red'.paint.spin(30) #=> #ff80000
+      #   'red'.paint.spin(60) #=> yellow
+      #   'red'.paint.spin(90) #=> #80ff00
+      #
+      # @param amount [Fixnum]
+      # @return       [Color]
       def spin(amount)
         hsl = self.hsl
         hue = (hsl.h.round + amount) % 360

data/lib/chroma/color/serializers.rb

@@ -1,28 +1,81 @@
 module Chroma
   class Color
+    # Methods for serializing {Color} to different color mode string formats.
     module Serializers
+      # Convert to hsv string.
+      #
+      # @example
+      #   'red'.paint.to_hsv                  #=> 'hsv(0, 100%, 100%)'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_hsv #=> 'hsva(0, 100%, 100%, 0.5)'
+      #
+      # @return [String]
       def to_hsv
         to_hs(:v)
       end
 
+      # Convert to hsl string.
+      #
+      # @example
+      #   'red'.paint.to_hsl                  #=> 'hsl(0, 100%, 50%)'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_hsl #=> 'hsla(0, 100%, 50%, 0.5)'
+      #
+      # @return [String]
       def to_hsl
         to_hs(:l)
       end
 
+      # Convert to hexadecimal string.
+      #
+      # @example
+      #   'red'.paint.to_hex                  #=> '#ff0000'
+      #   'red'.paint.to_hex(true)            #=> '#f00'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#ff0000'
+      #
+      # @param allow_3 [true, false] output 3-character hexadecimal
+      #   if possible
+      # @return [String]
       def to_hex(allow_3 = false)
         "##{to_basic_hex(allow_3)}"
       end
 
+      # Convert to 8-character hexadecimal string. The highest order byte
+      #   (left most hexadecimal pair represents the alpha value).
+      #
+      # @example
+      #   'red'.paint.to_hex                  #=> '#ffff0000'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_hex #=> '#80ff0000'
+      #
+      # @return [String]
       def to_hex8
         "##{to_basic_hex8}"
       end
 
+      # Convert to rgb string.
+      #
+      # @example
+      #   'red'.paint.to_rgb                  #=> 'rgb(255, 0, 0)'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_rgb #=> 'rgb(255, 0, 0, 0.5)'
+      #
+      # @return [String]
       def to_rgb
         middle = @rgb.to_a[0..2].map(&:round).join(', ')
 
         with_alpha(:rgb, middle)
       end
 
+      # Convert to named color if possible. If a color name can't be found, it
+      # returns `'<unknown>'` or the hexadecimal string based on the value of
+      # `hex_for_unknown`.
+      #
+      # @example
+      #   'red'.paint.to_name                  #=> 'red'
+      #   'rgba(255, 0, 0, 0.5)'.paint.to_name #=> '<unknown>'
+      #   '#00f'.paint.to_name                 #=> 'blue'
+      #   '#123'.paint.to_name(true)           #=> '#112233'
+      #
+      # @param hex_for_unknown [true, false] determine how unknown color names
+      #   should be returned
+      # @return [String]
       def to_name(hex_for_unknown = false)
         return 'transparent' if alpha.zero?
 
@@ -37,6 +90,16 @@ module Chroma
         end
       end
 
+      # Convert to a string based on the color format.
+      #
+      # @example
+      #   'red'.paint.to_s             #=> 'red'
+      #   'rgb(255, 0, 0)'.paint.to_s  #=> 'rgb(255, 0, 0)'
+      #   '#f00'.paint.to_s            #=> '#f00'
+      #   '#80ff0000'.paint.to_s(:rgb) #=> 'rgba(255, 0, 0, 0.5)'
+      #
+      # @param format [Symbol] the color format
+      # @return       [String]
       def to_s(format = @format)
         use_alpha = alpha < 1 && alpha >= 0 && /^hex(3|6)?$/ =~ format
 
@@ -56,14 +119,20 @@ module Chroma
 
       alias_method :inspect, :to_s
 
+      # Converts to an instance of {ColorModes::Hsv}
+      # @return [ColorModes::Hsv]
       def hsv
         Converters::HsvConverter.convert_rgb(@rgb)
       end
 
+      # Converts to an instance of {ColorModes::Hsl}
+      # @return [ColorModes::Hsl]
       def hsl
         Converters::HslConverter.convert_rgb(@rgb)
       end
 
+      # Converts to an instance of {ColorModes::Rgb}
+      # @return [ColorModes::Rgb]
       attr_reader :rgb
 
       private