color_contrast_calc 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5a62e36d449991a9381385e68fcf0c2e8201bdbc
-  data.tar.gz: 1053f1e6a889f8062ab53de73eaf1f92c434785f
+SHA256:
+  metadata.gz: 5fd16bbd48389db33f0f8cca8b247ff7d5f9a2b9722d8ec75bc700eda5a3ad31
+  data.tar.gz: ce493824b5a6fa1103a475073ca00bbd92e0b738863cfd338ebf6b2f8f419fd5
 SHA512:
-  metadata.gz: 1b51b39ef9e836dcf205883dba7a3ee96a3844eab201e799a012e22e85e88a4c69cdbe03d11f7d5f9fa1069c972034496c6c1b8e30d2a90b98b8bce04932d780
-  data.tar.gz: 49891f3150bdb8bf43831efe09150889109b9eaf9d0244ec5a4101d07dd77878caf82faa4831ea3779224ae46895daeebcef351ad38c9b958544ee7a24c3554d
+  metadata.gz: 7174b51afe73c2a632afa7d583e8f60a738891fb4f5a7e5c5deb5c50b849f7236fbf14440be3a94f80d3c077c0ad6a79d886ab8de7c3a30524c6184e98658741
+  data.tar.gz: 595e1f552a82d94bad86b93c7a5cf656634bdfb23cc88885789b850f142f09f5f5d673135c5658516b40267deb2fe2863f35a318c31304285e3921ce40e71e76

data/.rubocop.yml

@@ -2,7 +2,15 @@ AllCops:
   TargetRubyVersion: 2.2
 Layout/SpaceInsideBlockBraces:
   SpaceBeforeBlockParameters: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
 Metrics/BlockLength:
   Exclude: ["spec/**/*", "test/**/*"]
 Documentation:
   Enabled: false
+Style/FormatStringToken:
+  Enabled: false
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+Naming/UncommunicativeMethodParamName:
+  MinNameLength: 1

data/.travis.yml

@@ -1,10 +1,11 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2
   - 2.3
   - 2.4
   - 2.5
+  - 2.6
+  - 2.7
   - ruby-head
   - jruby-head
-before_install: gem install bundler -v 1.15.3
+before_install: gem install bundler -v '~>2.0'

data/README.ja.md

@@ -47,7 +47,8 @@ Or install it yourself as:
 require 'color_contrast_calc'
 
 # Create an instance of Color from a hex code
-# (You can pass 'red' or [255, 0, 0] instead of '#ff0000')
+# (You can pass 'red', [255, 0, 0], 'rgb(255, 0, 0)' or 'hsl(0deg, 100%, 50%)'
+# instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name
@@ -71,6 +72,28 @@ red
 
 ### 例1: 2つの色のコントラスト比を計算する
 
+#### 1.1: 最も簡便なやり方
+
+2色間のコントラスト比を計算するために`ColorContrastCalc`のクラスメソッドである`.contrast_ratio()`が利用可能です。
+
+例えば黄色と黒のコントラスト比をコマンドラインで計算したい場合、次のように出来ます:
+
+```bash
+$ ruby -rcolor_contrast_calc -e 'puts ColorContrastCalc.contrast_ratio("#ff0", "#000")'
+19.555999999999997
+```
+
+もしくは
+
+```bash
+$ ruby -rcolor_contrast_calc -e 'puts ColorContrastCalc.contrast_ratio("rgb(255, 255, 0)", "black")'
+19.555999999999997
+```
+
+(黄色を表すためには"hsl(60deg, 100%, 50%)", "#FFFF00", [255, 255, 0]等も使えます。)
+
+#### 1.2: Colorクラスのインスタンスを使っての計算
+
 例えば黄色と黒のコントラスト比を計算したい場合、
 次のコードを`yellow_black_contrast.rb`として保存し:
 
@@ -95,7 +118,9 @@ The contrast ratio between yellow and black is 19.5560
 The contrast ratio between #ffff00 and #000000 is 19.5560
 ```
 
-もしくは2色の16進数カラーコードあるいはRGB値からコントラスト比を計算することも可能です。
+#### 1.3: RGBを表す低レベルの値からの計算
+
+2色の16進数カラーコードあるいはRGB値からコントラスト比を計算することも可能です。
 
 次のコードを `yellow_black_hex_contrast.rb`として保存し:
 
@@ -116,6 +141,7 @@ puts "Contrast level: #{level}"
 以下のように実行します:
 
 ```bash
+$ ruby yellow_black_hex_contrast.rb
 Contrast ratio between yellow and black: 19.555999999999997
 Contrast level: AAA
 ```

data/README.md

@@ -46,7 +46,8 @@ Save the following code as `color_instance.rb`:
 require 'color_contrast_calc'
 
 # Create an instance of Color from a hex code
-# (You can pass 'red' or [255, 0, 0] instead of '#ff0000')
+# (You can pass 'red', [255, 0, 0], 'rgb(255, 0, 0)' or 'hsl(0deg, 100%, 50%)'
+# instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name
@@ -70,6 +71,28 @@ red
 
 ### Example 1: Calculate the contrast ratio between two colors
 
+#### 1.1: The easiest way
+
+To calculate the contrast ratio between two colors, a class method of `ColorContrastCalc`, `.contrast_ratio()` is available.
+
+For example, if you want calculate the contrast ratio between  yellow and black at the command line, you can do as follows:
+
+```bash
+$ ruby -rcolor_contrast_calc -e 'puts ColorContrastCalc.contrast_ratio("#ff0", "#000")'
+19.555999999999997
+```
+
+Or
+
+```bash
+$ ruby -rcolor_contrast_calc -e 'puts ColorContrastCalc.contrast_ratio("rgb(255, 255, 0)", "black")'
+19.555999999999997
+```
+
+(To represent a yellow, you can also use "hsl(60deg, 100%, 50%)", "#FFFF00", [255, 255, 0]...)
+
+#### 1.2: Calculate using Color instances
+
 If you want to calculate the contrast ratio between yellow and black,
 save the following code as `yellow_black_contrast.rb`:
 
@@ -94,7 +117,9 @@ The contrast ratio between yellow and black is 19.5560
 The contrast ratio between #ffff00 and #000000 is 19.5560
 ```
 
-Or it is also possible to calculate the contrast ratio of two colors from
+#### 1.3: Calculate from low level RGB values
+
+It is also possible to calculate the contrast ratio of two colors from
 their hex color codes or RGB values.
 
 Save the following code as `yellow_black_hex_contrast.rb`:
@@ -116,6 +141,7 @@ puts "Contrast level: #{level}"
 Then execute the script:
 
 ```bash
+$ ruby yellow_black_hex_contrast.rb
 Contrast ratio between yellow and black: 19.555999999999997
 Contrast level: AAA
 ```

data/color_contrast_calc.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) {|f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 0.49.1'

data/examples/color_instance.rb

@@ -3,7 +3,8 @@ require 'color_contrast_calc'
 require 'color_contrast_calc'
 
 # Create an instance of Color from a hex code
-# (You can pass 'red' or [255, 0, 0] instead of '#ff0000')
+# (You can pass 'red', [255, 0, 0], 'rgb(255, 0, 0)' or 'hsl(0deg, 100%, 50%)'
+# instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name

data/lib/color_contrast_calc.rb

@@ -17,7 +17,7 @@ module ColorContrastCalc
   # as [255, 255, 0] or "#ffff00". +name+ is assigned to the returned
   # instance.
   # @param color_value [String, Array<Integer>] Name of a predefined
-  #   color, hex color code or RGB value
+  #   color, hex color code, rgb/hsl functions or RGB value
   # @param name [String] Without specifying a name, a color keyword name
   #   (if exists) or the value of normalized hex color code is assigned
   #   to Color#name
@@ -52,6 +52,26 @@ module ColorContrastCalc
     Sorter.sort(colors, color_order, key_mapper)
   end
 
+  ##
+  # Calculate the contrast ratio of given colors.
+  #
+  # The definition of contrast ratio is given at
+  # {https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef}
+  #
+  # Please note that this method may be slow, as it internally creates
+  # Color instances.
+  #
+  # @param color1 [String, Array<Integer>] RGB color given as a string or
+  #   an array of integers. Yellow, for example, can be given as "#ffff00",
+  #   "#ff0", "rgb(255, 255, 0)", "hsl(60deg, 100%, 50%)" or [255, 255, 0].
+  # @param color2 [String, Array<Integer>] RGB color given as a string or
+  #   an array of integers.
+  # @return [Float] Contrast ratio
+
+  def self.contrast_ratio(color1, color2)
+    Color.as_color(color1).contrast_ratio_against(Color.as_color(color2))
+  end
+
   ##
   # Return an array of named colors.
   #

data/lib/color_contrast_calc/color.rb

@@ -2,16 +2,13 @@
 
 require 'color_contrast_calc/utils'
 require 'color_contrast_calc/checker'
+require 'color_contrast_calc/invalid_color_representation_error'
 require 'color_contrast_calc/threshold_finder'
+require 'color_contrast_calc/color_function_parser'
 require 'color_contrast_calc/deprecated'
 require 'json'
 
 module ColorContrastCalc
-  ##
-  # Error raised if creating a Color instance with invalid value.
-
-  class InvalidColorRepresentationError < StandardError; end
-
   ##
   # Represent specific colors.
   #
@@ -86,20 +83,22 @@ module ColorContrastCalc
       # as [255, 255, 0] or "#ffff00". +name+ is assigned to the returned
       # instance.
       # @param color_value [String, Array<Integer>] Name of a predefined
-      #   color, hex color code or RGB value
+      #   color, hex color code, rgb/hsl functions or RGB value
       # @param name [String] Without specifying a name, a color keyword name
       #   (if exists) or the value of normalized hex color code is assigned
       #   to Color#name
       # @return [Color] Instance of Color
 
       def color_from(color_value, name = nil)
-        error_message = 'A color should be given as an array or string.'
-
         if !color_value.is_a?(String) && !color_value.is_a?(Array)
-          raise InvalidColorRepresentationError, error_message
+          raise InvalidColorRepresentationError.from_value(color_value)
         end
 
         return color_from_rgb(color_value, name) if color_value.is_a?(Array)
+
+        if /\A(?:rgb|hsl)/i =~ color_value
+          return color_from_func(color_value, name)
+        end
         color_from_str(color_value, name)
       end
 
@@ -127,10 +126,8 @@ module ColorContrastCalc
       end
 
       def color_from_rgb(rgb_value, name = nil)
-        error_message = 'An RGB value should be given in form of [r, g, b].'
-
         unless Utils.valid_rgb?(rgb_value)
-          raise InvalidColorRepresentationError, error_message
+          raise InvalidColorRepresentationError.from_value(rgb_value)
         end
 
         hex_code = Utils.rgb_to_hex(rgb_value)
@@ -139,14 +136,23 @@ module ColorContrastCalc
 
       private :color_from_rgb
 
-      def color_from_str(color_value, name = nil)
-        error_message = 'A hex code is in form of "#xxxxxx" where 0 <= x <= f.'
+      def color_from_func(color_value, name = nil)
+        conv = ColorFunctionParser.parse(color_value)
+        if conv.scheme == ColorFunctionParser::Scheme::RGB
+          return color_from_rgb(conv.to_a, name || color_value)
+        end
+
+        from_hsl(conv.to_a, name || color_value)
+      end
+
+      private :color_from_func
 
+      def color_from_str(color_value, name = nil)
         named_color = !name && List::NAME_TO_COLOR[color_value]
         return named_color if named_color
 
         unless Utils.valid_hex?(color_value)
-          raise InvalidColorRepresentationError, error_message
+          raise InvalidColorRepresentationError.from_value(color_value)
         end
 
         hex_code = Utils.normalize_hex(color_value)
@@ -294,6 +300,18 @@ module ColorContrastCalc
       generate_new_color(Converter::Grayscale, ratio, name)
     end
 
+    ##
+    # Return a complementary color of the original color.
+    #
+    # @param name [String] You can name the color to be created.
+    #   Without this option, the value of normalized hex color
+    #   code is assigned instead.
+    # @return [Color] New  complementary color
+    def complementary(name = nil)
+      minmax = rgb.minmax.reduce {|min, max| min + max }
+      self.class.new(rgb.map {|c| minmax - c }, name)
+    end
+
     ##
     # Try to find a color who has a satisfying contrast ratio.
     #

data/lib/color_contrast_calc/color_function_parser.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'strscan'
+require 'stringio'
+require 'color_contrast_calc/utils'
+require 'color_contrast_calc/invalid_color_representation_error'
+
+module ColorContrastCalc
+  ##
+  # Module that converts RGB/HSL functions into data apt for calculation.
+
+  module ColorFunctionParser
+    ##
+    # Define types of color functions.
+
+    module Scheme
+      RGB = 'rgb'
+      HSL = 'hsl'
+    end
+
+    ##
+    # Hold information about a parsed RGB/HSL function.
+    #
+    # This class is intended to be used internally in ColorFunctionParser,
+    # so do not rely on the current class name and its interfaces.
+    # They may change in the future.
+
+    class Converter
+      ##
+      # @!attribute [r] scheme
+      #   @return [String] Type of function: 'rgb' or 'hsl'
+      # @!attribute [r] source
+      #   @return [String] The original RGB/HSL function before the conversion
+
+      attr_reader :scheme, :source
+
+      ##
+      # @private
+      #
+      # Parameters passed to this method is generated by
+      # ColorFunctionParser.parse() and the manual creation of
+      # instances of this class by end users is not expected.
+
+      def initialize(parsed_value, original_value)
+        @scheme = parsed_value[:scheme]
+        @params = parsed_value[:parameters]
+        @source = original_value
+        @normalized = normalize_params
+      end
+
+      def normalize_params
+        raise NotImplementedError, 'Overwrite the method in a subclass'
+      end
+
+      private :normalize_params
+
+      ##
+      # Return the RGB value gained from a RGB/HSL function.
+      #
+      # @return [Array<Integer>] RGB value represented as an array
+
+      def rgb
+        raise NotImplementedError, 'Overwrite the method in a subclass'
+      end
+
+      ##
+      # Return the parameters of a RGB/HSL function as an array of
+      # Integer/Float.
+      # The unit for H, S, L is assumed to be deg, %, % respectively.
+      #
+      # @return [Array<Integer, Float>] RGB/HSL value represented as an array
+
+      def to_a
+        @normalized
+      end
+
+      # @private
+      class Rgb < self
+        def normalize_params
+          @params.map do |param|
+            if param[:unit] == '%'
+              (param[:number] * 255.0 / 100).round
+            else
+              param[:number].to_i
+            end
+          end
+        end
+
+        alias rgb to_a
+      end
+
+      # @private
+      class Hsl < self
+        def normalize_params
+          @params.map do |param|
+            param[:number].to_f
+          end
+        end
+
+        def rgb
+          Utils.hsl_to_rgb(to_a)
+        end
+      end
+
+      # @private
+      def self.create(parsed_value, original_value)
+        case parsed_value[:scheme]
+        when Scheme::RGB
+          Rgb.new(parsed_value, original_value)
+        when Scheme::HSL
+          Hsl.new(parsed_value, original_value)
+        end
+      end
+    end
+
+    # @private
+    module TokenRe
+      SPACES = /\s+/.freeze
+      SCHEME = /(rgb|hsl)/i.freeze
+      OPEN_PAREN = /\(/.freeze
+      CLOSE_PAREN = /\)/.freeze
+      COMMA = /,/.freeze
+      NUMBER = /(\d+)(:?\.\d+)?/.freeze
+      UNIT = /(%|deg)/.freeze
+    end
+
+    def self.format_error_message(scanner, re)
+      out = StringIO.new
+      color_value = scanner.string
+      [
+        format('"%s" is not a valid code. An error occurred at:', color_value),
+        color_value,
+        "#{' ' * scanner.charpos}^ while searching with #{re}"
+      ].each do |line|
+        out.puts line
+      end
+
+      out.string
+    end
+
+    private_class_method :format_error_message
+
+    def self.skip_spaces!(scanner)
+      scanner.scan(TokenRe::SPACES)
+    end
+
+    private_class_method :skip_spaces!
+
+    def self.read_token!(scanner, re)
+      skip_spaces!(scanner)
+      token = scanner.scan(re)
+
+      return token if token
+
+      error_message = format_error_message(scanner, re)
+      raise InvalidColorRepresentationError, error_message
+    end
+
+    private_class_method :read_token!
+
+    def self.read_scheme!(scanner)
+      scheme = read_token!(scanner, TokenRe::SCHEME)
+
+      parsed_value = {
+        scheme: scheme.downcase,
+        parameters: []
+      }
+
+      read_open_paren!(scanner, parsed_value)
+    end
+
+    private_class_method :read_scheme!
+
+    def self.read_open_paren!(scanner, parsed_value)
+      read_token!(scanner, TokenRe::OPEN_PAREN)
+
+      read_parameters!(scanner, parsed_value)
+    end
+
+    private_class_method :read_open_paren!
+
+    def self.read_close_paren!(scanner)
+      scanner.scan(TokenRe::CLOSE_PAREN)
+    end
+
+    private_class_method :read_close_paren!
+
+    def self.read_parameters!(scanner, parsed_value)
+      read_number!(scanner, parsed_value)
+    end
+
+    private_class_method :read_parameters!
+
+    def self.read_number!(scanner, parsed_value)
+      number = read_token!(scanner, TokenRe::NUMBER)
+
+      parsed_value[:parameters].push({ number: number, unit: nil })
+
+      read_unit!(scanner, parsed_value)
+    end
+
+    private_class_method :read_number!
+
+    def self.read_unit!(scanner, parsed_value)
+      unit = scanner.scan(TokenRe::UNIT)
+
+      parsed_value[:parameters].last[:unit] = unit if unit
+
+      read_comma!(scanner, parsed_value)
+    end
+
+    private_class_method :read_unit!
+
+    def self.read_comma!(scanner, parsed_value)
+      return parsed_value if read_close_paren!(scanner)
+
+      read_token!(scanner, TokenRe::COMMA)
+      read_number!(scanner, parsed_value)
+    end
+
+    private_class_method :read_comma!
+
+    ##
+    # Parse an RGB/HSL function and store the result as an instance of
+    # ColorFunctionParser::Converter.
+    #
+    # @param color_value [String] RGB/HSL function defined at
+    #   https://www.w3.org/TR/css-color-4/
+    # @return [Converter] An instance of ColorFunctionParser::Converter
+
+    def self.parse(color_value)
+      parsed_value = read_scheme!(StringScanner.new(color_value))
+      Converter.create(parsed_value, color_value)
+    end
+
+    ##
+    # Return An RGB value gained from an RGB/HSL function.
+    #
+    # @return [Array<Integer>] RGB value represented as an array
+
+    def self.to_rgb(color_value)
+      parse(color_value).rgb
+    end
+  end
+end

data/lib/color_contrast_calc/invalid_color_representation_error.rb

@@ -0,0 +1,38 @@
+module ColorContrastCalc
+  ##
+  # Error raised if creating a Color instance with invalid value.
+
+  class InvalidColorRepresentationError < StandardError
+    module Template
+      RGB = 'An RGB value should be in form of [r, g, b], but %s.'
+      COLOR_NAME = '%s seems to be an undefined color name.'
+      HEX = 'A hex code #xxxxxx where 0 <= x <= f is expected, but %s.'
+      UNEXPECTED = 'A color should be given as an array or string, but %s.'
+    end
+
+    def self.may_be_name?(value)
+      # all of the color keywords contain an alphabet between g-z.
+      /^#/ !~ value && /[g-z]/i =~ value
+    end
+
+    private_class_method :may_be_name?
+
+    def self.select_message_template(value)
+      case value
+      when Array
+        Template::RGB
+      when String
+        may_be_name?(value) ? Template::COLOR_NAME : Template::HEX
+      else
+        Template::UNEXPECTED
+      end
+    end
+
+    private_class_method :select_message_template
+
+    def self.from_value(value)
+      message = format(select_message_template(value), value)
+      new(message)
+    end
+  end
+end

data/lib/color_contrast_calc/utils.rb

@@ -16,7 +16,7 @@ module ColorContrastCalc
 
     private_constant :HSL_UPPER_LIMIT
 
-    HEX_RE = /\A#?[0-9a-f]{3}([0-9a-f]{3})?\z/i
+    HEX_RE = /\A#?[0-9a-f]{3}([0-9a-f]{3})?\z/i.freeze
 
     private_constant :HEX_RE
 

data/lib/color_contrast_calc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ColorContrastCalc
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: color_contrast_calc
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - HASHIMOTO, Naoki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-30 00:00:00.000000000 Z
+date: 2020-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.15'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -112,9 +112,11 @@ files:
 - lib/color_contrast_calc.rb
 - lib/color_contrast_calc/checker.rb
 - lib/color_contrast_calc/color.rb
+- lib/color_contrast_calc/color_function_parser.rb
 - lib/color_contrast_calc/converter.rb
 - lib/color_contrast_calc/data/color_keywords.json
 - lib/color_contrast_calc/deprecated.rb
+- lib/color_contrast_calc/invalid_color_representation_error.rb
 - lib/color_contrast_calc/shim.rb
 - lib/color_contrast_calc/sorter.rb
 - lib/color_contrast_calc/threshold_finder.rb
@@ -140,7 +142,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Utility that helps you choose colors with sufficient contrast, WCAG 2.0 in