imglab 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78faee0a4ff6558f7ece0d993cac443de2b480e0c230a5586dc6fdbc8c6867db
-  data.tar.gz: e6cbb31a3d1e86d8b54cc7c9985b10cd3555886d941ca66925b6752f8bacf51d
+  metadata.gz: 9b66cec4bc8fd3fb132c6deae52a45fee6282e40a15e31ba1c15a8fa54868705
+  data.tar.gz: 41a3f77bb418201e13167b89c86c03d59359061dd116381508cfb76517a8d462
 SHA512:
-  metadata.gz: cb456e7d68b9e66ae072ec27f5232c455cd32f040b3b029dbd0d03362709f22bbd3c61a3b2d908589eff85ff28dde67ceba0c7dd2d12ccb458a121ac035c4974
-  data.tar.gz: 4053ed5c372ad62d78bd0af9c8d762b0cd9a6dfa9cba6215328d59bfd73e75951b96c97986ee5657a455954d3fd09cc4d8ce91292edda7061a67b006e8e3c329
+  metadata.gz: d2a4c896cfdf4db54f0f2521cc50c085b87ca80ff49024341d8cc63c4be178edfdf1895b0075566c1636747d4db7cc23cb7a102d20c9e7f24b3d4beab9e7c683
+  data.tar.gz: 0e938c85258bf827bbf80dc93c330f994fcab7cb967ee882c6ae3ec37f05e4b7bd7e6c40e7fdac401e3738832d4b0728266ac3041650c2e37bc97849e21b6caf

data/README.md

@@ -7,7 +7,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "imglab", "~> 0.2"
+gem "imglab", "~> 0.3"
 ```
 
 And then execute:
@@ -24,7 +24,7 @@ $ gem install imglab
 
 ## Ruby compatibility
 
-`imglab` has been successfully tested on the following Ruby versions: `3.1`, `3.0`, `2.7`, `2.6`, `2.5`, `2.4`, `2.3`, `2.2`, `2.1` and `2.0`.
+`imglab` has been successfully tested on the following Ruby versions: `3.2`, `3.1`, `3.0`, `2.7`, `2.6`, `2.5`, `2.4`, `2.3`, `2.2`, `2.1` and `2.0`.
 
 ## Generating URLs
 
@@ -178,7 +178,7 @@ Imglab.url("assets", "image.jpeg", width: 500, height: 500, mode: "crop", crop:
 
 ### Specifying URL parameters
 
-Some imglab parameters can receive URLs as values. It is possible to specify these parameter values as strings.
+Some imglab parameters can receive URLs as values. It is possible to specify these parameter values as strings:
 
 ```ruby
 Imglab.url("assets", "image.jpeg", width: 500, height: 600, watermark: "logo.svg")
@@ -200,7 +200,7 @@ Imglab.url(
   "image.jpeg",
   width: 500,
   height: 600,
-  watermark: Imglab.url("assets", "logo.svg", width: 100, format: "png")
+  watermark: Imglab.url("assets", "logo.svg", width: 100, format: :png)
 )
 "https://assets.imglab-cdn.net/image.jpeg?width=500&height=600&watermark=https%3A%2F%2Fassets.imglab-cdn.net%2Flogo.svg%3Fwidth%3D100%26format%3Dpng"
 ```
@@ -213,7 +213,7 @@ Imglab.url(
   "image.jpeg",
   width: 500,
   height: 600,
-  watermark: Imglab.url("marketing", "logo.svg", width: 100, format: "png")
+  watermark: Imglab.url("marketing", "logo.svg", width: 100, format: :png)
 )
 "https://assets.imglab-cdn.net/image.jpeg?width=500&height=600&watermark=https%3A%2F%2Fmarketing.imglab-cdn.net%2Flogo.svg%3Fwidth%3D100%26format%3Dpng"
 ```
@@ -228,7 +228,7 @@ Imglab.url(
   "image.jpeg",
   width: 500,
   height: 600,
-  watermark: Imglab.url(marketing_source, "logo.svg", width: 100, format: "png")
+  watermark: Imglab.url(marketing_source, "logo.svg", width: 100, format: :png)
 )
 ```
 
@@ -257,8 +257,8 @@ Imglab.url("assets", "image.jpeg", width: 500, expires: 1.hour.from_now)
 For on-premises imglab server is possible to define custom sources pointing to your server location.
 
 * `:https` - a `boolean` value specifying if the source should use https or not (default: `true`)
-* `:host` - a `string` specifying the host where the imglab server is located. (default: `imglab-cdn.net`)
-* `:port` - a `integer` specifying a port where the imglab server is located.
+* `:host` - a `string` specifying the host where the imglab server is located. (default: `"imglab-cdn.net"`)
+* `:port` - an `integer` specifying a port where the imglab server is located. (default: `nil`)
 * `:subdomains` - a `boolean` value specifying if the source should be specified using subdomains instead of using the path. (default: `true`)
 
 If we have our on-premises imglab server at `http://my-company.com:8080` with a source named `images` we can use the following source settings to access a `logo.png` image:
@@ -266,7 +266,7 @@ If we have our on-premises imglab server at `http://my-company.com:8080` with a
 ```ruby
 source = Imglab::Source.new("images", https: false, host: "my-company.com", port: 8080)
 
-Imglab.url(source, "logo.png", width: 300, height: 300, format: "png")
+Imglab.url(source, "logo.png", width: 300, height: 300, format: :png)
 "http://images.my-company.com:8080/logo.png?width=300&height=300&format=png"
 ```
 
@@ -282,7 +282,7 @@ source = Imglab::Source.new(
   secure_salt: "images-secure-salt"
 )
 
-Imglab.url(source, "logo.png", width: 300, height: 300, format: "png")
+Imglab.url(source, "logo.png", width: 300, height: 300, format: :png)
 "http://images.my-company.com:8080/logo.png?width=300&height=300&format=png&signature=generated-signature"
 ```
 
@@ -299,10 +299,309 @@ source = Imglab::Source.new(
   subdomains: false
 )
 
-Imglab.url(source, "logo.png", width: 300, height: 300, format: "png")
+Imglab.url(source, "logo.png", width: 300, height: 300, format: :png)
 "http://my-company.com:8080/images/logo.png?width=300&height=300&format=png"
 ```
 
+## Generating srcsets
+
+You can use `Imglab.srcset` function to generate custom string values for `srcset` attributes, to be used for Web responsive images inside an `<img>` HTML element or picture `<source>`.
+
+This function works similarly to `Imglab.url`, expecting the same parameters and values, except for some specific query parameters that have a special meaning and can receive `Range` and arrays as values.
+
+> To learn more about responsive images and the `srcset` attribute, you can take a look to the [MDN article about responsive images](https://developer.mozilla.org/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images).
+
+### Fixed size
+
+When enough information is provided about the image output size (using `width` or `height` parameters), `srcset` function will generate URLs with a default sequence of device pixel ratios:
+
+For the following example we are specying a fixed value of `500` pixels for `width` parameter:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500)
+```
+
+Generating the following output:
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=1 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=2 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=3 3x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=4 4x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=5 5x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=6 6x
+```
+
+A very common practice consists in reducing the quality of images with high pixel density, decreasing the final file size. To achieve this you can optionally specify a Ruby `Range` value for `quality` parameter, gradually reducing the file size while increasing the image size.
+
+In this example we are specifying a fixed `width` value of `500` pixels and a `quality` range between `80` and `40`:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500, quality: 80..40)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=80&dpr=1 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=70&dpr=2 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=61&dpr=3 3x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=53&dpr=4 4x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=46&dpr=5 5x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&quality=40&dpr=6 6x
+```
+
+A custom `Range` value can be set for `dpr` parameter too, overriding the default sequence of generated dprs:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500, dpr: 1..4)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=1 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=2 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=3 3x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=4 4x
+```
+
+Using `Range` values for `dpr` and `quality` parameters in the same `srcset` call is also possible:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500, dpr: 1..4, quality: 80..40)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=1&quality=80 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=2&quality=63 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=3&quality=50 3x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=4&quality=40 4x
+```
+
+If necessary you can also use arrays with explicit values for `dpr` and `quality`:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500, dpr: [1, 2, 3], quality: [80, 75, 60])
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=1&quality=80 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=2&quality=75 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=3&quality=60 3x
+```
+
+Or even use a specific `quality` value for all the URLs in the same srcset:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 500, dpr: [1, 2, 3], quality: 70)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=1&quality=70 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=2&quality=70 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=500&dpr=3&quality=70 3x
+```
+
+### Fluid width
+
+When a specific sequence of widths is required you can use a `Range`, `sequence`, or array for `width` parameter.
+
+When a `Range` value is used, a sequence with a default size of 16 URLs will be generated inside the specified interval:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 100..2000)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=122 122w,
+https://assets.imglab-cdn.net/image.jpeg?width=149 149w,
+https://assets.imglab-cdn.net/image.jpeg?width=182 182w,
+https://assets.imglab-cdn.net/image.jpeg?width=222 222w,
+https://assets.imglab-cdn.net/image.jpeg?width=271 271w,
+https://assets.imglab-cdn.net/image.jpeg?width=331 331w,
+https://assets.imglab-cdn.net/image.jpeg?width=405 405w,
+https://assets.imglab-cdn.net/image.jpeg?width=494 494w,
+https://assets.imglab-cdn.net/image.jpeg?width=603 603w,
+https://assets.imglab-cdn.net/image.jpeg?width=737 737w,
+https://assets.imglab-cdn.net/image.jpeg?width=900 900w,
+https://assets.imglab-cdn.net/image.jpeg?width=1099 1099w,
+https://assets.imglab-cdn.net/image.jpeg?width=1341 1341w,
+https://assets.imglab-cdn.net/image.jpeg?width=1638 1638w,
+https://assets.imglab-cdn.net/image.jpeg?width=2000 2000w
+```
+
+If required you can specify a `Range` value for `quality` parameter too:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 100..2000, quality: 80..40)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100&quality=80 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=122&quality=76 122w,
+https://assets.imglab-cdn.net/image.jpeg?width=149&quality=73 149w,
+https://assets.imglab-cdn.net/image.jpeg?width=182&quality=70 182w,
+https://assets.imglab-cdn.net/image.jpeg?width=222&quality=66 222w,
+https://assets.imglab-cdn.net/image.jpeg?width=271&quality=63 271w,
+https://assets.imglab-cdn.net/image.jpeg?width=331&quality=61 331w,
+https://assets.imglab-cdn.net/image.jpeg?width=405&quality=58 405w,
+https://assets.imglab-cdn.net/image.jpeg?width=494&quality=55 494w,
+https://assets.imglab-cdn.net/image.jpeg?width=603&quality=53 603w,
+https://assets.imglab-cdn.net/image.jpeg?width=737&quality=50 737w,
+https://assets.imglab-cdn.net/image.jpeg?width=900&quality=48 900w,
+https://assets.imglab-cdn.net/image.jpeg?width=1099&quality=46 1099w,
+https://assets.imglab-cdn.net/image.jpeg?width=1341&quality=44 1341w,
+https://assets.imglab-cdn.net/image.jpeg?width=1638&quality=42 1638w,
+https://assets.imglab-cdn.net/image.jpeg?width=2000&quality=40 2000w
+```
+
+If you want to generate a sequence of numbers for `width` parameter with a specific number of URLs you can use `Imglab::Sequence` module helper:
+
+```ruby
+# Remember to include Imglab::Sequence module before using sequence helper
+include Imglab::Sequence
+
+# Generating a srcset string with a sequence between 100 and 2000 pixels for width parameter with a size of 5 URLs
+Imglab.srcset("assets", "image.jpeg", width: sequence(100, 2000, 5))
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=211 211w,
+https://assets.imglab-cdn.net/image.jpeg?width=447 447w,
+https://assets.imglab-cdn.net/image.jpeg?width=946 946w,
+https://assets.imglab-cdn.net/image.jpeg?width=2000 2000w
+```
+
+Using an array with specific values will generate URLs only for those widths:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: [100, 300, 500])
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=300 300w,
+https://assets.imglab-cdn.net/image.jpeg?width=500 500w
+```
+
+It is also possible to specify an array of values for `height` and `quality` parameters:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: [100, 300, 500], height: [200, 400, 600], quality: [75, 70, 65])
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100&height=200&quality=75 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=300&height=400&quality=70 300w,
+https://assets.imglab-cdn.net/image.jpeg?width=500&height=600&quality=65 500w
+```
+
+### No size
+
+When `srcset` function doesn't have information about the image output size (`width` or `height` parameters are not set) it will generate a default sequence of 16 URLs specifying a `width` value with an interval between `100` and `8192` pixels:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg")
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=134 134w,
+https://assets.imglab-cdn.net/image.jpeg?width=180 180w,
+https://assets.imglab-cdn.net/image.jpeg?width=241 241w,
+https://assets.imglab-cdn.net/image.jpeg?width=324 324w,
+https://assets.imglab-cdn.net/image.jpeg?width=434 434w,
+https://assets.imglab-cdn.net/image.jpeg?width=583 583w,
+https://assets.imglab-cdn.net/image.jpeg?width=781 781w,
+https://assets.imglab-cdn.net/image.jpeg?width=1048 1048w,
+https://assets.imglab-cdn.net/image.jpeg?width=1406 1406w,
+https://assets.imglab-cdn.net/image.jpeg?width=1886 1886w,
+https://assets.imglab-cdn.net/image.jpeg?width=2530 2530w,
+https://assets.imglab-cdn.net/image.jpeg?width=3394 3394w,
+https://assets.imglab-cdn.net/image.jpeg?width=4553 4553w,
+https://assets.imglab-cdn.net/image.jpeg?width=6107 6107w,
+https://assets.imglab-cdn.net/image.jpeg?width=8192 8192w
+```
+
+It is always possible to change this default behavior using `Imglab::Sequence` helper. In the following example we are specifying a sequence between `320` and `4096` pixels and generating 10 different URLs:
+
+```ruby
+include Imglab::Sequence
+
+Imglab.srcset("assets", "image.jpeg", width: sequence(320, 4096, 10))
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=320 320w,
+https://assets.imglab-cdn.net/image.jpeg?width=425 425w,
+https://assets.imglab-cdn.net/image.jpeg?width=564 564w,
+https://assets.imglab-cdn.net/image.jpeg?width=749 749w,
+https://assets.imglab-cdn.net/image.jpeg?width=994 994w,
+https://assets.imglab-cdn.net/image.jpeg?width=1319 1319w,
+https://assets.imglab-cdn.net/image.jpeg?width=1751 1751w,
+https://assets.imglab-cdn.net/image.jpeg?width=2324 2324w,
+https://assets.imglab-cdn.net/image.jpeg?width=3086 3086w,
+https://assets.imglab-cdn.net/image.jpeg?width=4096 4096w
+```
+
+### Image aspect ratio and srcset
+
+A usual scenario is to generate multiple URLs while maintaining the same aspect ratio for all of them. If a specific image aspect ratio is required while using `srcset` function you can set a value to `aspect-ratio` parameter along with `mode` parameter using  `crop`, `contain`, `face`, or `force` resize modes.
+
+For the following example we are using a specific value of `300` pixels for `width` and an aspect ratio of `1:1` (square), cropping the image with `crop` resize mode and setting output format to `webp`:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 300, aspect_ratio: "1:1", mode: :crop, format: :webp)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=1 1x,
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=2 2x,
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=3 3x,
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=4 4x,
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=5 5x,
+https://assets.imglab-cdn.net/image.jpeg?width=300&aspect-ratio=1%3A1&mode=crop&format=webp&dpr=6 6x
+```
+
+You can instead use `height` value. In this example we are specifying a fixed value of `300` pixels for `height` parameter, a `aspect-ratio` of `16:9` (widescreen) with `crop` resize mode, and `webp` output format:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", height: 300, aspect_ratio: "16:9", mode: :crop, format: :webp)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=1 1x,
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=2 2x,
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=3 3x,
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=4 4x,
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=5 5x,
+https://assets.imglab-cdn.net/image.jpeg?height=300&aspect-ratio=16%3A9&mode=crop&format=webp&dpr=6 6x
+```
+
+You can also use fluid values for `width` parameter while maintaining the same aspect ratio for all generated URLs. In this example, we are using a `range` value between `100` and `4096` for `width` parameter, a value of `1:1` for `aspect-ratio`, `crop` resize mode and `webp` output format:
+
+```ruby
+Imglab.srcset("assets", "image.jpeg", width: 100..4096, aspect_ratio: "1:1", mode: :crop, format: :webp)
+```
+
+```html
+https://assets.imglab-cdn.net/image.jpeg?width=100&aspect-ratio=1%3A1&mode=crop&format=webp 100w,
+https://assets.imglab-cdn.net/image.jpeg?width=128&aspect-ratio=1%3A1&mode=crop&format=webp 128w,
+https://assets.imglab-cdn.net/image.jpeg?width=164&aspect-ratio=1%3A1&mode=crop&format=webp 164w,
+https://assets.imglab-cdn.net/image.jpeg?width=210&aspect-ratio=1%3A1&mode=crop&format=webp 210w,
+https://assets.imglab-cdn.net/image.jpeg?width=269&aspect-ratio=1%3A1&mode=crop&format=webp 269w,
+https://assets.imglab-cdn.net/image.jpeg?width=345&aspect-ratio=1%3A1&mode=crop&format=webp 345w,
+https://assets.imglab-cdn.net/image.jpeg?width=442&aspect-ratio=1%3A1&mode=crop&format=webp 442w,
+https://assets.imglab-cdn.net/image.jpeg?width=566&aspect-ratio=1%3A1&mode=crop&format=webp 566w,
+https://assets.imglab-cdn.net/image.jpeg?width=724&aspect-ratio=1%3A1&mode=crop&format=webp 724w,
+https://assets.imglab-cdn.net/image.jpeg?width=928&aspect-ratio=1%3A1&mode=crop&format=webp 928w,
+https://assets.imglab-cdn.net/image.jpeg?width=1188&aspect-ratio=1%3A1&mode=crop&format=webp 1188w,
+https://assets.imglab-cdn.net/image.jpeg?width=1522&aspect-ratio=1%3A1&mode=crop&format=webp 1522w,
+https://assets.imglab-cdn.net/image.jpeg?width=1949&aspect-ratio=1%3A1&mode=crop&format=webp 1949w,
+https://assets.imglab-cdn.net/image.jpeg?width=2497&aspect-ratio=1%3A1&mode=crop&format=webp 2497w,
+https://assets.imglab-cdn.net/image.jpeg?width=3198&aspect-ratio=1%3A1&mode=crop&format=webp 3198w,
+https://assets.imglab-cdn.net/image.jpeg?width=4096&aspect-ratio=1%3A1&mode=crop&format=webp 4096w
+```
+
 ## License
 
 imglab source code is released under [MIT License](LICENSE).

data/lib/imglab/color.rb

@@ -150,7 +150,7 @@ module Imglab::Color
     whitesmoke
     yellow
     yellowgreen
-  ]
+  ].freeze
 
   # Returns a formatted color value as string.
   #
@@ -179,7 +179,7 @@ module Imglab::Color
     when args.size == 4 && valid_components?(*args)
       args.join(",")
     else
-      raise ArgumentError.new("Invalid color")
+      raise ArgumentError, "Invalid color"
     end
   end
 

data/lib/imglab/position.rb

@@ -1,12 +1,12 @@
 module Imglab::Position
   extend self
 
-  HORIZONTAL = %w[left center right]
-  VERTICAL = %w[top middle bottom]
+  HORIZONTAL = %w[left center right].freeze
+  VERTICAL = %w[top middle bottom].freeze
 
   # Returns a formatted position value as string.
   #
-  # @param args [Array<String>, String] the position with two directions or one single direction as strings.
+  # @param directions [Array<String>, String] the position with two directions or one single direction as strings.
   # @return [String] the formatted position with the specified arguments.
   # @raise [ArgumentError] when the specified arguments are not a valid position.
   #
@@ -20,24 +20,24 @@ module Imglab::Position
   #   Imglab::Position.position("left", "center") #=> ArgumentError: Invalid position
   # @example Specify an invalid single direction position (raising ArgumentError exception)
   #   Imglab::Position.position("lefts") #=> ArgumentError: Invalid position
-  def position(*args)
+  def position(*directions)
     case
-    when args.size == 1 && valid_position?(args[0])
-      args[0]
-    when args.size == 2 && valid_position?(*args)
-      args.join(",")
+    when directions.size == 1 && valid_position?(directions[0])
+      directions[0]
+    when directions.size == 2 && valid_position?(*directions)
+      directions.join(",")
     else
-      raise ArgumentError.new("Invalid position")
+      raise ArgumentError, "Invalid position"
     end
   end
 
   private
 
-  def valid_position?(*args)
+  def valid_position?(*directions)
     case
-    when args.size == 1 && valid_direction?(args[0])
+    when directions.size == 1 && valid_direction?(directions[0])
       true
-    when args.size == 2 && valid_directions?(args[0], args[1])
+    when directions.size == 2 && valid_directions?(directions[0], directions[1])
       true
     else
       false

data/lib/imglab/sequence.rb

@@ -0,0 +1,45 @@
+module Imglab::Sequence
+  extend self
+
+  DEFAULT_SIZE = 16
+
+  # Returns a geometric sequence of integer numbers inside an interval and with specific size as array.
+  #
+  # @param first [Integer] the first integer number of the sequence.
+  # @param last [Integer] the last integer number of the sequence.
+  # @param size [Integer] the size of the sequence.
+  # @return [Array<Integer>] a sequence of integer numbers as array.
+  #
+  # @example Specify an ascending sequence of default size
+  #   Imglab::Sequence.sequence(100, 8192) #=> [100, 134, 180, 241, 324, 434, 583, 781, 1048, 1406, 1886, 2530, 3394, 4553, 6107, 8192]
+  # @example Specify an ascending sequence of size 1
+  #   Imglab::Sequence.sequence(100, 8192, 1) #=> [100]
+  # @example Specify an ascending sequence of size 2
+  #   Imglab::Sequence.sequence(100, 8192, 2) #=> [100, 8192]
+  # @example Specify an ascending sequence of size 4
+  #   Imglab::Sequence.sequence(100, 8192, 4) #=> [100, 434, 1886, 8192]
+  # @example Specify a descending sequence of size 6
+  #   Imglab::Sequence.sequence(70, 60, 6) #=> [70, 68, 66, 64, 62, 60]
+  def sequence(first, last, size = DEFAULT_SIZE)
+    return [] if size <= 0
+    return [first] if size == 1
+    return [first, last] if size == 2
+
+    ratio = (last / first.to_f) ** (1 / (size - 1).to_f)
+
+    progression(first, ratio).take(size - 1).map(&:round).push(last)
+  end
+
+  private
+
+  def progression(first, ratio)
+    n = first
+
+    Enumerator.new do |y|
+      loop do
+        y << n
+        n *= ratio
+      end
+    end
+  end
+end

data/lib/imglab/signature.rb

@@ -1,22 +1,24 @@
 require "base64"
 require "openssl"
 
-class Imglab::Signature
+module Imglab::Signature
+  extend self
+
   # Returns a generated signature for a source, path and encoded parameters.
   #
   # @param source [Imglab::Source] the source used to generate the signature.
   # @param path [String] the path of the resource.
   # @param encoded_params [String] encoded query params of the URL to generate the signature.
   # @return [String]
-  def self.generate(source, path, encoded_params = nil)
+  def generate(source, path, encoded_params = nil)
     decoded_secure_key = Base64.decode64(source.secure_key)
     decoded_secure_salt = Base64.decode64(source.secure_salt)
 
     data = "#{decoded_secure_salt}/#{path}"
     data = encoded_params ? "#{data}?#{encoded_params}" : data
 
-    hmac = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), decoded_secure_key, data)
+    digest = OpenSSL::HMAC.digest(OpenSSL::Digest.new("sha256"), decoded_secure_key, data)
 
-    Base64.urlsafe_encode64(hmac).tr("=", "")
+    Base64.urlsafe_encode64(digest).tr("=", "")
   end
 end

data/lib/imglab/source.rb

@@ -1,6 +1,6 @@
 class Imglab::Source
   DEFAULT_HTTPS = true
-  DEFAULT_HOST = "imglab-cdn.net"
+  DEFAULT_HOST = "imglab-cdn.net".freeze
   DEFAULT_SUBDOMAINS = true
 
   attr_reader :name, :https, :port, :secure_key, :secure_salt, :subdomains
@@ -39,7 +39,7 @@ class Imglab::Source
     @subdomains ? "#{@name}.#{@host}" : @host
   end
 
-  # Returns a the path to be used with the source.
+  # Returns the path to be used with the source.
   #
   # @param path [String]
   # @return [String]
@@ -51,7 +51,7 @@ class Imglab::Source
   #
   # @return [Boolean]
   def is_secure?
-    @secure_key && @secure_salt
+    !!(@secure_key && @secure_salt)
   end
 
   # Overrided inspect method to don't show sensitive attributes like secure_key and secure_salt.

data/lib/imglab/srcset/utils.rb

@@ -0,0 +1,89 @@
+module Imglab::Srcset
+  module Utils
+    extend self
+
+    NORMALIZE_KEYS = %w[dpr width].freeze
+
+    SPLIT_DPR_KEYS = %w[dpr quality].freeze
+    SPLIT_WIDTH_KEYS = %w[width height quality].freeze
+
+    # Returns normalized params, rejecting values with keys included in normalized keys and with empty arrays.
+    #
+    # @param params [Hash]
+    # @return [Hash]
+    def normalize_params(params)
+      params.inject({}) do |normalized_params, (key, value)|
+        normalized_params.merge(normalize_param(key.to_s, value))
+      end
+    end
+
+    # Returns an array with the parameters to use in different URLs for a srcset split by dpr parameter.
+    #
+    # @param params [Hash]
+    # @return [Array]
+    def split_params_dpr(params)
+      split_values(params, SPLIT_DPR_KEYS, params.fetch("dpr").size).map do |dpr, quality|
+        params.merge(
+          {
+            "dpr" => dpr,
+            "quality" => quality
+          }.delete_if { |key, _value| !params.key?(key) }
+        )
+      end
+    end
+
+    # Returns an array with the parameters to use in different URLs for a srcset split by width parameter.
+    #
+    # @param params [Hash]
+    # @return [Array]
+    def split_params_width(params)
+      split_values(params, SPLIT_WIDTH_KEYS, split_size(params.fetch("width"))).map do |width, height, quality|
+        params.merge(
+          {
+            "width" => width,
+            "height" => height,
+            "quality" => quality
+          }.delete_if { |key, _value| !params.key?(key) }
+        )
+      end
+    end
+
+    private
+
+    def normalize_param(key, value)
+      case
+      when NORMALIZE_KEYS.include?(key) && value == []
+        {}
+      else
+        { key => value }
+      end
+    end
+
+    def split_size(value)
+      case value
+      when Range
+        Imglab::Sequence::DEFAULT_SIZE
+      when Array
+        value.size
+      end
+    end
+
+    def split_values(params, keys, size)
+      values = keys.map { |key| split_value(key, params[key], size) }
+      values.first.zip(*values[1..-1])
+    end
+
+    def split_value(key, value, size)
+      case
+      when key == "dpr" && value.instance_of?(Range)
+        value.to_a
+      when value.instance_of?(Range)
+        Imglab::Sequence.sequence(value.first, value.last, size)
+      when value.instance_of?(Array)
+        value
+      else
+        Array.new(size, value)
+      end
+    end
+  end
+end

data/lib/imglab/srcset.rb

@@ -0,0 +1,73 @@
+module Imglab
+  extend self
+
+  FLUID_CLASSES = [Array, Range].freeze
+
+  DEFAULT_DPRS = [1, 2, 3, 4, 5, 6].freeze
+  DEFAULT_WIDTHS = Sequence.sequence(100, 8192).freeze
+
+  # Returns a formatted srcset `string` with the specified parameters.
+  #
+  # @param source [String, Imglab::Source] the source name or source object
+  # @param path [String] the path where the resource is located
+  # @param params [Hash] the query parameters that we want to use
+  # @return [String] the srcset value as a list of formatted URLs with the specified arguments
+  # @raise [ArgumentError] when the source name or source parameter has a not expected type or params are using unexpected values
+  #
+  # @example Creating a srcset with three different device pixel ratios:
+  #   Imglab.srcset("assets", "example.jpeg", width: 500, dpr: [1, 2, 3]) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&dpr=1 1x,\n..."
+  # @example Creating a srcset with three different device pixel ratios using a range:
+  #   Imglab.srcset("assets", "example.jpeg", width: 500, dpr: 1..3) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&dpr=1 1x,\n..."
+  # @example Creating a srcset with three different width sizes:
+  #   Imglab.srcset("assets", "example.jpeg", width: [400, 800, 1200], format: "webp") #=> "https://assets.imglab-cdn.net/example.jpeg?width=400&format=webp 400w,\n..."
+  # @example Creating a srcset with a range of width sizes:
+  #   Imglab.srcset("assets", "example.jpeg", width: 400..1200, format: "webp") #=> "https://assets.imglab-cdn.net/example.jpeg?width=400&format=webp 400w,\n..."
+  def srcset(source, path, params = {})
+    params = Srcset::Utils.normalize_params(params)
+
+    width, height, dpr = params.values_at("width", "height", "dpr")
+
+    case
+    when is_fluid?(width)
+      if is_fluid?(dpr)
+        raise ArgumentError, "dpr as #{dpr.class} is not allowed when width is Array or Range"
+      end
+
+      srcset_width(source, path, params)
+    when width || height
+      if is_fluid?(height)
+        raise ArgumentError, "height as #{height.class} is not allowed when width is not an Array or Range"
+      end
+
+      srcset_dpr(source, path, params.merge("dpr" => dprs(params)))
+    else
+      if is_fluid?(dpr)
+        raise ArgumentError, "dpr as #{dpr.class} is not allowed without specifying width or height"
+      end
+
+      srcset_width(source, path, params.merge("width" => DEFAULT_WIDTHS))
+    end
+  end
+
+  private
+
+  def dprs(params)
+    is_fluid?(params["dpr"]) ? params["dpr"] : DEFAULT_DPRS
+  end
+
+  def is_fluid?(value)
+    FLUID_CLASSES.include?(value.class)
+  end
+
+  def srcset_dpr(source, path, params)
+    Srcset::Utils.split_params_dpr(params).map do |split_params|
+      "#{url(source, path, split_params)} #{split_params.fetch('dpr')}x"
+    end.join(",\n")
+  end
+
+  def srcset_width(source, path, params)
+    Srcset::Utils.split_params_width(params).map do |split_params|
+      "#{url(source, path, split_params)} #{split_params.fetch('width')}w"
+    end.join(",\n")
+  end
+end

data/lib/imglab/url/utils.rb

@@ -0,0 +1,55 @@
+module Imglab::Url
+  module Utils
+    extend self
+
+    NORMALIZE_PATH_PREFIX_REGEXP = Regexp.compile(/\A\/*/)
+    NORMALIZE_PATH_SUFFIX_REGEXP = Regexp.compile(/\/*$/)
+
+    WEB_URI_SCHEMES = %w[https http].freeze
+
+    # Returns a normalized path where suffix and prefix slashes are removed.
+    #
+    # @param path [String]
+    # @return [String]
+    def normalize_path(path)
+      path.gsub(NORMALIZE_PATH_PREFIX_REGEXP, "").gsub(NORMALIZE_PATH_SUFFIX_REGEXP, "")
+    end
+
+    # Returns normalized params, transforming keys with undercores to hyphens.
+    #
+    # @param params [Hash]
+    # @return [Hash]
+    def normalize_params(params)
+      params.inject({}) do |normalized_params, value|
+        normalized_params.merge(normalize_param(dasherize(value[0]), value[1]))
+      end
+    end
+
+    # Returns a boolean value indicating whether a string is a valid HTTP/HTTPS URI or not.
+    #
+    # @param uri [String]
+    # @return [Boolean]
+    def web_uri?(uri)
+      WEB_URI_SCHEMES.include?(URI.parse(uri).scheme)
+    rescue URI::Error
+      false
+    end
+
+    private
+
+    def dasherize(value)
+      value.to_s.gsub("_", "-")
+    end
+
+    def normalize_param(key, value)
+      case
+      when key == "expires" && value.instance_of?(Time)
+        { key => value.to_i }
+      when value == nil
+        { key => "" }
+      else
+        { key => value }
+      end
+    end
+  end
+end

data/lib/imglab/url.rb

@@ -0,0 +1,79 @@
+module Imglab
+  extend self
+
+  # Returns a formatted URL `string` with the specified arguments.
+  #
+  # @param source [String, Imglab::Source] the source name or source object
+  # @param path [String] the path where the resource is located
+  # @param params [Hash] the query parameters that we want to use
+  # @return [String] the formatted URL with the specified arguments
+  # @raise [ArgumentError] when the source name or source parameter has a not expected type
+  #
+  # @example Creating a URL specifying source name as string
+  #   Imglab.url("assets", "example.jpeg", width: 500, height: 600) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&height=600"
+  # @example Creating a URL specifying a Imglab::Source
+  #   Imglab.url(Imglab::Source.new("assets"), "example.jpeg", width: 500, height: 600) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&height=600"
+  def url(source, path, params = {})
+    case source
+    when String
+      url_for_source(Source.new(source), path, params)
+    when Source
+      url_for_source(source, path, params)
+    else
+      raise ArgumentError, "Invalid source name or source. A string or a #{Source.name} instance is expected"
+    end
+  end
+
+  private
+
+  def url_for_source(source, path, params)
+    normalized_path = Url::Utils.normalize_path(path)
+    normalized_params = Url::Utils.normalize_params(params)
+
+    URI::Generic.new(
+      source.scheme,
+      nil,
+      source.host,
+      source.port,
+      nil,
+      File.join("/", source.path(encode_path(normalized_path))),
+      nil,
+      encode_params(source, normalized_path, normalized_params),
+      nil
+    ).to_s
+  end
+
+  def encode_path(path)
+    if Url::Utils.web_uri?(path)
+      encode_path_component(path)
+    else
+      path.split("/").map do |path_component|
+        encode_path_component(path_component)
+      end.join("/")
+    end
+  end
+
+  def encode_path_component(path_component)
+    ERB::Util.url_encode(path_component)
+  end
+
+  def encode_params(source, path, params)
+    return encode_empty_params(source, path) if params.empty?
+
+    if source.is_secure?
+      signature = Signature.generate(source, path, URI.encode_www_form(params))
+
+      URI.encode_www_form(params.merge(signature: signature))
+    else
+      URI.encode_www_form(params)
+    end
+  end
+
+  def encode_empty_params(source, path)
+    return unless source.is_secure?
+
+    signature = Signature.generate(source, path)
+
+    URI.encode_www_form(signature: signature)
+  end
+end

data/lib/imglab/version.rb

@@ -1,3 +1,3 @@
 module Imglab
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/imglab.rb

@@ -5,84 +5,8 @@ require "imglab/source"
 require "imglab/signature"
 require "imglab/color"
 require "imglab/position"
-require "imglab/utils"
-
-module Imglab
-  # Returns a formatted URL `string` with the specified arguments.
-  #
-  # @param source_name_or_source [String, Imglab::Source] the source name or source object
-  # @param path [String] the path where the resource is located
-  # @param params [Hash] the query parameters that we want to use
-  # @return [String] the formatted URL with the specified arguments
-  # @raise [ArgumentError] when the source name or source parameter has a not expected type.
-  #
-  # @example Creating a URL specifying source name as string
-  #   Imglab.url("assets", "example.jpeg", width: 500, height: 600) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&height=600"
-  # @example Creating a URL specifying a Imglab::Source
-  #   Imglab.url(Imglab::Source.new("assets"), "example.jpeg", width: 500, height: 600) #=> "https://assets.imglab-cdn.net/example.jpeg?width=500&height=600"
-  def self.url(source_name_or_source, path, params = {})
-    case source_name_or_source
-    when String
-      url_for_source(Source.new(source_name_or_source), path, params)
-    when Source
-      url_for_source(source_name_or_source, path, params)
-    else
-      raise ArgumentError.new("Invalid source name or source. A string or #{Imglab::Source.name} is expected.")
-    end
-  end
-
-  private
-
-  def self.url_for_source(source, path, params)
-    normalized_path = Utils.normalize_path(path)
-    normalized_params = Utils.normalize_params(params)
-
-    URI::Generic.new(
-      source.scheme,
-      nil,
-      source.host,
-      source.port,
-      nil,
-      File.join("/", source.path(encode_path(normalized_path))),
-      nil,
-      encode_params(source, normalized_path, normalized_params),
-      nil
-    ).to_s
-  end
-
-  def self.encode_path(path)
-    if Utils.web_uri?(path)
-      encode_path_component(path)
-    else
-      path.split("/").map do |path_component|
-        encode_path_component(path_component)
-      end.join("/")
-    end
-  end
-
-  def self.encode_path_component(path_component)
-    ERB::Util.url_encode(path_component)
-  end
-
-  def self.encode_params(source, path, params)
-    return encode_empty_params(source, path) if params.empty?
-
-    if source.is_secure?
-      signature = Signature.generate(source, path, URI.encode_www_form(params))
-
-      URI.encode_www_form(params.merge(signature: signature))
-    else
-      URI.encode_www_form(params)
-    end
-  end
-
-  def self.encode_empty_params(source, path)
-    if source.is_secure?
-      signature = Signature.generate(source, path)
-
-      URI.encode_www_form(signature: signature)
-    else
-      nil
-    end
-  end
-end
+require "imglab/sequence"
+require "imglab/url/utils"
+require "imglab/url"
+require "imglab/srcset/utils"
+require "imglab/srcset"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imglab
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - imglab
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-06-06 00:00:00.000000000 Z
+date: 2023-01-13 00:00:00.000000000 Z
 dependencies: []
 description: Official Ruby library to integrate with imglab services.
 email:
@@ -29,9 +29,13 @@ files:
 - lib/imglab.rb
 - lib/imglab/color.rb
 - lib/imglab/position.rb
+- lib/imglab/sequence.rb
 - lib/imglab/signature.rb
 - lib/imglab/source.rb
-- lib/imglab/utils.rb
+- lib/imglab/srcset.rb
+- lib/imglab/srcset/utils.rb
+- lib/imglab/url.rb
+- lib/imglab/url/utils.rb
 - lib/imglab/version.rb
 homepage: https://github.com/imglab-io/imglab-rb
 licenses:

data/lib/imglab/utils.rb

@@ -1,49 +0,0 @@
-class Imglab::Utils
-  NORMALIZE_PATH_PREFIX_REGEXP = Regexp.compile(/\A\/*/)
-  NORMALIZE_PATH_SUFFIX_REGEXP = Regexp.compile(/\/*$/)
-
-  WEB_URI_SCHEMES = %w[https http]
-
-  # Returns a normalized path where suffix and prefix slashes are removed.
-  #
-  # @param path [String]
-  # @return [String]
-  def self.normalize_path(path)
-    path.gsub(NORMALIZE_PATH_PREFIX_REGEXP, "").gsub(NORMALIZE_PATH_SUFFIX_REGEXP, "")
-  end
-
-  # Returns normalized params, transforming keys with undercores to hyphens.
-  #
-  # @param params [Hash]
-  # @return [Hash]
-  def self.normalize_params(params)
-    params.inject({}) do |normalized_params, value|
-      normalized_params.merge(normalize_param(dasherize(value[0]), value[1]))
-    end
-  end
-
-  # Returns a boolean value indicating whether a string is a valid HTTP/HTTPS URI or not.
-  #
-  # @param uri [String]
-  # @return [Boolean]
-  def self.web_uri?(uri)
-    WEB_URI_SCHEMES.include?(URI.parse(uri).scheme)
-  rescue URI::Error
-    false
-  end
-
-  private
-
-  def self.dasherize(value)
-    value.to_s.gsub("_", "-")
-  end
-
-  def self.normalize_param(key, value)
-    case
-    when key == "expires" && value.instance_of?(Time)
-      {key => value.to_i}
-    else
-      {key => value}
-    end
-  end
-end