color_contrast_calc 0.5.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5a62e36d449991a9381385e68fcf0c2e8201bdbc
-  data.tar.gz: 1053f1e6a889f8062ab53de73eaf1f92c434785f
+SHA256:
+  metadata.gz: 07b766d958883d015466220f97ed047512e0fc6dd2a51288b5274c6b0287f0fe
+  data.tar.gz: 1e740d3598c423f07efb3632b31bf155dbf337f8f9265ede39f3b12bd3e50456
 SHA512:
-  metadata.gz: 1b51b39ef9e836dcf205883dba7a3ee96a3844eab201e799a012e22e85e88a4c69cdbe03d11f7d5f9fa1069c972034496c6c1b8e30d2a90b98b8bce04932d780
-  data.tar.gz: 49891f3150bdb8bf43831efe09150889109b9eaf9d0244ec5a4101d07dd77878caf82faa4831ea3779224ae46895daeebcef351ad38c9b958544ee7a24c3554d
+  metadata.gz: 7d3becf7316ad107082efb72a1e777fb23272a4fe73239170296e55e978d7d0935ad23e7b0a9203c0dc94164ac2dca5efc5763139c49e19cf116c50c28539e1c
+  data.tar.gz: 6e3e1efa303a5ea42e56fd4011ccee3cd19677f0ae770a279c9a4b6ffa9340bb63d5d192224b4f7b18a1364e2b299ecab878dee3a76aa657843ee333a619341b

data/.rubocop.yml

@@ -1,8 +1,16 @@
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.4
 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/MethodParameterName:
+  MinNameLength: 1

data/.travis.yml

@@ -1,10 +1,18 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2
-  - 2.3
-  - 2.4
   - 2.5
+  - 2.6
+  - 2.7
+  - 3.0
   - ruby-head
-  - jruby-head
-before_install: gem install bundler -v 1.15.3
+before_install: gem install bundler -v '~>2.0'
+jobs:
+  include:
+  - rvm: 2.4
+    before_install:
+      - yes | gem update --system --force
+      - gem install bundler
+  - rvm: jruby-head
+    before_install:
+      - bundle add rake --version "13.0.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)', 'hsl(0deg, 100%, 50%)' or
+# hwb(60deg 0% 0%) instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name
@@ -69,8 +70,41 @@ red
 
 ```
 
+#### `ColorContrastCalc.color_from()`の引数に使える色の表現
+
+`ColorContrastCalc.color_from()`の第1引数は以下の形式で指定できます。
+
+* RGB値の16進数表記: #ff0, #ffff00, #FF0, etc.
+* RGB値の関数形式表記: rgb(255, 255, 0), rgb(255 255 0), etc.
+* Integerの配列で表したRGB値: [255, 255, 0], etc.
+* HSL値の関数形式表記: hsl(60deg, 100%, 50%), hsl(60 100% 50%), etc.
+* [実験的対応] HWB値の関数形式表記: hwb(60deg 0% 0%), hwb(60 0% 0%), etc.
+* [拡張カラーキーワード](https://www.w3.org/TR/css-color-3/#svg-color): white, black, red, etc.
+
 ### 例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 +129,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,10 +152,34 @@ puts "Contrast level: #{level}"
 以下のように実行します:
 
 ```bash
+$ ruby yellow_black_hex_contrast.rb
 Contrast ratio between yellow and black: 19.555999999999997
 Contrast level: AAA
 ```
 
+#### 1.4: [実験的対応] 透明色間のコントラスト比の計算
+
+透明色間の計算のために``ColorContrastCalc.contrast_ratio_with_opacity()``が
+提供されています。
+
+このメソッドは3つの引数として、前景色と背景色、省略可能な基調色、を取ります。
+
+3番目の基調色は他の2色の下に配置され、完全に不透明なことが期待される点にご注意下さい。
+
+例:
+
+```bash
+irb -r color_contrast_calc
+irb(main):001:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)', 'white')
+=> 1.1828076947731336
+irb(main):002:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)') # 3番目の色のデフォルト値は白です。
+=> 1.1828076947731336
+irb(main):003:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)', 'black')
+=> 4.78414518008597
+irb(main):004:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0)', 'rgb(0 255 0 / 0.5)', 'black') # 完全に不透明な色について不透明度を指定する必要はありません。
+=> 4.78414518008597
+```
+
 ### 例2: ある色に対し十分なコントラスト比のある色を見つける
 
 2色の組み合わせのうち、一方の色のbrightness/lightnessを変化させることで十分な
@@ -229,32 +289,40 @@ The grayscale of #ffa500 is #acacac.
 ```ruby
 require 'color_contrast_calc'
 
-color_names = ['red', 'yellow', 'lime', 'cyan', 'fuchsia', 'blue']
-colors = color_names.map {|c| ColorContrastCalc.color_from(c) }
+color_names = ['red', 'lime', 'cyan', 'yellow', 'fuchsia', 'blue']
 
 # Sort by hSL order.  An uppercase for a component of color means
 # that component should be sorted in descending order.
 
-hsl_ordered = ColorContrastCalc.sort(colors, 'hSL')
-puts("Colors sorted in the order of hSL: #{hsl_ordered.map(&:name)}")
+hsl_ordered = ColorContrastCalc.sort(color_names, 'hSL')
+puts("Colors sorted in the order of hSL: #{hsl_ordered}")
 
 # Sort by RGB order.
 
-rgb_ordered = ColorContrastCalc.sort(colors, 'RGB')
-puts("Colors sorted in the order of RGB: #{rgb_ordered.map(&:name)}")
+rgb_ordered = ColorContrastCalc.sort(color_names, 'RGB')
+puts("Colors sorted in the order of RGB: #{rgb_ordered}")
 
 # You can also change the precedence of components.
 
-grb_ordered = ColorContrastCalc.sort(colors, 'GRB')
-puts("Colors sorted in the order of GRB: #{grb_ordered.map(&:name)}")
+grb_ordered = ColorContrastCalc.sort(color_names, 'GRB')
+puts("Colors sorted in the order of GRB: #{grb_ordered}")
 
 # And you can directly sort hex color codes.
 
 ## Hex color codes that correspond to the color_names given above.
-hex_codes = ['#ff0000', '#ff0', '#00ff00', '#0ff', '#f0f', '#0000FF']
+hex_codes = ['#ff0000', '#00ff00', '#0ff', '#ff0', '#f0f', '#0000FF']
 
 hsl_ordered = ColorContrastCalc.sort(hex_codes, 'hSL')
 puts("Colors sorted in the order of hSL: #{hsl_ordered}")
+
+# If you want to sort colors in different notations,
+# you should specify a key_mapper.
+
+colors = ['rgb(255 0 0)', 'hsl(120 100% 50%)', '#0ff', 'hwb(60 0% 0%)', [255, 0, 255], '#0000ff']
+
+key_mapper = proc {|c| ColorContrastCalc.color_from(c) }
+colors_in_hsl_order = ColorContrastCalc.sort(colors, 'hSL', key_mapper)
+puts("Colors sorted in the order of hSL: #{colors_in_hsl_order}")
 ```
 
 以下のように実行します:
@@ -265,6 +333,7 @@ Colors sorted in the order of hSL: ["red", "yellow", "lime", "cyan", "blue", "fu
 Colors sorted in the order of RGB: ["yellow", "fuchsia", "red", "cyan", "lime", "blue"]
 Colors sorted in the order of GRB: ["yellow", "cyan", "lime", "fuchsia", "red", "blue"]
 Colors sorted in the order of hSL: ["#ff0000", "#ff0", "#00ff00", "#0ff", "#0000FF", "#f0f"]
+Colors sorted in the order of hSL: ["rgb(255 0 0)", "hwb(60 0% 0%)", "hsl(120 100% 50%)", "#0ff", "#0000ff", [255, 0, 255]]
 ```
 
 ### 例5: 定義済みの色のリスト

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)', 'hsl(0deg, 100%, 50%)' or
+# hwb(60deg 0% 0%) instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name
@@ -68,8 +69,41 @@ red
 
 ```
 
+#### Color units for the argument of `ColorContrastCalc.color_from()`
+
+The following formats are supported for the first argument of `ColorContrastCalc.color_from()`.
+
+* RGB values in hexadecimal notation: #ff0, #ffff00, #FF0, etc.
+* RGB values in functional notation: rgb(255, 255, 0), rgb(255 255 0), etc.
+* RGB values as an Array of Integers: [255, 255, 0], etc.
+* HSL colors in functional notation: hsl(60deg, 100%, 50%), hsl(60 100% 50%), etc.
+* [Experimental] HWB colors in functional notation: hwb(60deg 0% 0%), hwb(60 0% 0%), etc.
+* [Extended color keywords](https://www.w3.org/TR/css-color-3/#svg-color): white, black, red, etc.
+
 ### 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 to 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 +128,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,10 +152,37 @@ 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
 ```
 
+
+#### 1.4: [Experimental] Calculate the contrast ratio between transparent colors
+
+``ColorContrastCalc.contrast_ratio_with_opacity()`` is provided for the
+calculation.
+
+The method takes three arguments, foreground color, background color and an
+optional base color.
+
+Please note that the third color is placed below the other two colors and
+expects to be fully opaque.
+
+For example:
+
+```bash
+irb -r color_contrast_calc
+irb(main):001:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)', 'white')
+=> 1.1828076947731336
+irb(main):002:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)') # The default value for the third parameter is white.
+=> 1.1828076947731336
+irb(main):003:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0 / 1.0)', 'rgb(0 255 0 / 0.5)', 'black')
+=> 4.78414518008597
+irb(main):004:0> ColorContrastCalc.contrast_ratio_with_opacity('rgb(255 255 0)', 'rgb(0 255 0 / 0.5)', 'black') # For a fully opaque color, you don't need to specify the opacity.
+=> 4.78414518008597
+```
+
 ### Example 2: Find colors that have enough contrast ratio with a given color
 
 If you want to find a combination of colors with sufficient contrast
@@ -229,32 +292,40 @@ For example, save the following code as `sort_colors.rb`:
 ```ruby
 require 'color_contrast_calc'
 
-color_names = ['red', 'yellow', 'lime', 'cyan', 'fuchsia', 'blue']
-colors = color_names.map {|c| ColorContrastCalc.color_from(c) }
+color_names = ['red', 'lime', 'cyan', 'yellow', 'fuchsia', 'blue']
 
 # Sort by hSL order.  An uppercase for a component of color means
 # that component should be sorted in descending order.
 
-hsl_ordered = ColorContrastCalc.sort(colors, 'hSL')
-puts("Colors sorted in the order of hSL: #{hsl_ordered.map(&:name)}")
+hsl_ordered = ColorContrastCalc.sort(color_names, 'hSL')
+puts("Colors sorted in the order of hSL: #{hsl_ordered}")
 
 # Sort by RGB order.
 
-rgb_ordered = ColorContrastCalc.sort(colors, 'RGB')
-puts("Colors sorted in the order of RGB: #{rgb_ordered.map(&:name)}")
+rgb_ordered = ColorContrastCalc.sort(color_names, 'RGB')
+puts("Colors sorted in the order of RGB: #{rgb_ordered}")
 
 # You can also change the precedence of components.
 
-grb_ordered = ColorContrastCalc.sort(colors, 'GRB')
-puts("Colors sorted in the order of GRB: #{grb_ordered.map(&:name)}")
+grb_ordered = ColorContrastCalc.sort(color_names, 'GRB')
+puts("Colors sorted in the order of GRB: #{grb_ordered}")
 
 # And you can directly sort hex color codes.
 
 ## Hex color codes that correspond to the color_names given above.
-hex_codes = ['#ff0000', '#ff0', '#00ff00', '#0ff', '#f0f', '#0000FF']
+hex_codes = ['#ff0000', '#00ff00', '#0ff', '#ff0', '#f0f', '#0000FF']
 
 hsl_ordered = ColorContrastCalc.sort(hex_codes, 'hSL')
 puts("Colors sorted in the order of hSL: #{hsl_ordered}")
+
+# If you want to sort colors in different notations,
+# you should specify a key_mapper.
+
+colors = ['rgb(255 0 0)', 'hsl(120 100% 50%)', '#0ff', 'hwb(60 0% 0%)', [255, 0, 255], '#0000ff']
+
+key_mapper = proc {|c| ColorContrastCalc.color_from(c) }
+colors_in_hsl_order = ColorContrastCalc.sort(colors, 'hSL', key_mapper)
+puts("Colors sorted in the order of hSL: #{colors_in_hsl_order}")
 ```
 
 Then execute the script:
@@ -265,6 +336,7 @@ Colors sorted in the order of hSL: ["red", "yellow", "lime", "cyan", "blue", "fu
 Colors sorted in the order of RGB: ["yellow", "fuchsia", "red", "cyan", "lime", "blue"]
 Colors sorted in the order of GRB: ["yellow", "cyan", "lime", "fuchsia", "red", "blue"]
 Colors sorted in the order of hSL: ["#ff0000", "#ff0", "#00ff00", "#0ff", "#0000FF", "#f0f"]
+Colors sorted in the order of hSL: ["rgb(255 0 0)", "hwb(60 0% 0%)", "hsl(120 100% 50%)", "#0ff", "#0000ff", [255, 0, 255]]
 ```
 
 ### Example 5: Lists of predefined colors

data/color_contrast_calc.gemspec

@@ -7,7 +7,7 @@ require 'color_contrast_calc/version'
 Gem::Specification.new do |spec|
   spec.name          = 'color_contrast_calc'
   spec.version       = ColorContrastCalc::VERSION
-  spec.required_ruby_version = ">= 2.2"
+  spec.required_ruby_version = ">= 2.4"
   spec.authors       = ['HASHIMOTO, Naoki']
   spec.email         = ['hashimoto.naoki@gmail.com']
 
@@ -23,9 +23,9 @@ 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 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~> 0.49.1'
-  spec.add_development_dependency 'yard', '~> 0.9.9'
+  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '~> 1.7'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end

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)', 'hsl(0deg, 100%, 50%)' or
+# hwb(60deg 0% 0%) instead of '#ff0000')
 red = ColorContrastCalc.color_from('#ff0000')
 puts red.class
 puts red.name

data/examples/sort_colors.rb

@@ -2,29 +2,37 @@
 
 require 'color_contrast_calc'
 
-color_names = ['red', 'yellow', 'lime', 'cyan', 'fuchsia', 'blue']
-colors = color_names.map {|c| ColorContrastCalc.color_from(c) }
+color_names = ['red', 'lime', 'cyan', 'yellow', 'fuchsia', 'blue']
 
 # Sort by hSL order.  An uppercase for a component of color means
 # that component should be sorted in descending order.
 
-hsl_ordered = ColorContrastCalc.sort(colors, 'hSL')
-puts("Colors sorted in the order of hSL: #{hsl_ordered.map(&:name)}")
+hsl_ordered = ColorContrastCalc.sort(color_names, 'hSL')
+puts("Colors sorted in the order of hSL: #{hsl_ordered}")
 
 # Sort by RGB order.
 
-rgb_ordered = ColorContrastCalc.sort(colors, 'RGB')
-puts("Colors sorted in the order of RGB: #{rgb_ordered.map(&:name)}")
+rgb_ordered = ColorContrastCalc.sort(color_names, 'RGB')
+puts("Colors sorted in the order of RGB: #{rgb_ordered}")
 
 # You can also change the precedence of components.
 
-grb_ordered = ColorContrastCalc.sort(colors, 'GRB')
-puts("Colors sorted in the order of GRB: #{grb_ordered.map(&:name)}")
+grb_ordered = ColorContrastCalc.sort(color_names, 'GRB')
+puts("Colors sorted in the order of GRB: #{grb_ordered}")
 
 # And you can directly sort hex color codes.
 
 ## Hex color codes that correspond to the color_names given above.
-hex_codes = ['#ff0000', '#ff0', '#00ff00', '#0ff', '#f0f', '#0000FF']
+hex_codes = ['#ff0000', '#00ff00', '#0ff', '#ff0', '#f0f', '#0000FF']
 
 hsl_ordered = ColorContrastCalc.sort(hex_codes, 'hSL')
 puts("Colors sorted in the order of hSL: #{hsl_ordered}")
+
+# If you want to sort colors in different notations,
+# you should specify a key_mapper.
+
+colors = ['rgb(255 0 0)', 'hsl(120 100% 50%)', '#0ff', 'hwb(60 0% 0%)', [255, 0, 255], '#0000ff']
+
+key_mapper = proc {|c| ColorContrastCalc.color_from(c) }
+colors_in_hsl_order = ColorContrastCalc.sort(colors, 'hSL', key_mapper)
+puts("Colors sorted in the order of hSL: #{colors_in_hsl_order}")