deeplink 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f08c25f1f41d07f18e26e2b357f8f171458036cb7d567f0c4bf1aa85ee16b14b
-  data.tar.gz: 80d3e34f8cd939d5abbf4e2d6069d94c8e11a1b3e998e2732bec3ab1ce11d2a1
+  metadata.gz: 5258494e8891ca8dcd0e05f5d19002c981d0d7ec213e96a2a9f446d08e9622e7
+  data.tar.gz: 6d80c29a397aa832ca8618d37b9c67dec410cf977072a1b50928aae9c5766bd1
 SHA512:
-  metadata.gz: 1d9eaa03986c02c3c2be37c4de3a7ddb28c005ce6f6259d278f19017096fdbf85c5e07bdecd3c0fc6ff6f453da7f71456c259b9a28323948b8311d4e1dcab423
-  data.tar.gz: 42a9936bd76ce3d1b92212bce9e776fb867de98d7bd30540d55172c4d8704d4973afb3f39eceef4c0c13780653250d5f13568464a43a4965f61e76d94a067631
+  metadata.gz: 897d7c31b35d1614539545155dd0403ce703ea34574868ea1ff55a8882c4fa6f203683f77c045b9a013e002cb98278ef138899a27341875416c57b4c3cdc7ef2
+  data.tar.gz: 58a3790de63fd53b4535c4ef3bdecdf9e70d13cbf2d9fb8477ccb7f51bbf4fb4b23c09a7fd987279601ba09b763963a578a45de57885904f4762eedd15018dc8

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 3.0.0 (2026-10-20)
+
+### Breaking changes
+
+- `query` returns decoded values (`a b` instead of `a+b`). Values are encoded only by `to_s`, and
+  query keys are now encoded too.
+- `add_query` with a `nil` value adds a parameter without a value (`?flag`) instead of `flag=`.
+
+### Fixes
+
+- Keep URL fragments (`deep://page#section`), available through `fragment`.
+- Keep query parameters without a value (`?flag`), stored with a `nil` value.
+- Encode query values that are not strings, such as symbols.
+- Parse links without a double slash (`deep:foo`, `deep:/foo`) instead of returning `''`.
+- Parse query values containing `{` or `}` in full.
+
+### Development
+
+- Add `changelog_uri` to the gem metadata and ship `CHANGELOG.md` with the gem.
+
+## 2.0.0 (2026-10-20)
+
+### Breaking changes
+
+- Require Ruby >= 3.2 (was >= 2.5).
+
+### Fixes
+
+- Support Ruby 4.0, which removed the CGI library. Query values are encoded exactly as before.
+- Already encoded query values are no longer double encoded (`?q=hello%20world` used to become
+  `q=hello%2520world`).
+- `remove_query` without keys returns `nil` instead of raising `NoMethodError`.
+
+### Development
+
+- CI tests Ruby 3.2, 3.3, 3.4 and 4.0, and runs RuboCop in a separate job.
+- Add Dependabot for GitHub Actions and Bundler.
+- Update development dependencies (RuboCop 1.92, RSpec 3.13, `debug` and `irb` instead of
+  `pry-byebug`).
+- `rake` runs the specs and RuboCop.
+
+## 1.1.0 (2020-05-01)
+
+- Drop support for Ruby 2.1.
+
+## 1.0.1 (2018-02-13)
+
+- Code style fixes.
+
+## 1.0.0 (2016-05-06)
+
+- First stable release.
+
+## 0.1.4 (2016-04-06)
+
+- Fix `NoMethodError` when parsing query parameters on Ruby < 2.1.
+
+## 0.1.3 (2015-12-11)
+
+- Fix parsing `nil` links.
+- Parse query parameters with unusual characters.
+- Allow removing a list of query parameters.

data/README.md

@@ -3,96 +3,123 @@
 
 # Deeplink
 
-Handle deep links in an easy way.
+Parse, inspect and build mobile deep links (`myapp://products/42?ref=email`) in an easy way.
 
-This gem needs ruby version >= 3.2
+Ruby's `URI` treats the first part after `://` as a host, so deep links like `myapp://products/42`
+end up with `products` as the host. This gem reads them the way apps do: a scheme, a path, a query
+and a fragment.
 
-## Installation
+This gem needs Ruby >= 3.2.
 
-Add this line to your application's Gemfile:
+## Installation
 
-```ruby
-gem 'deeplink'
+```sh
+bundle add deeplink
 ```
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
+Or install it yourself:
 
-    $ gem install deeplink
+```sh
+gem install deeplink
+```
 
 ## Usage
 
 ### Parsing a deep link
 
-Just call `Deeplink.parse` with a deep link String and then you can read the scheme and path.
+Call `Deeplink.parse` with a deep link string to read its scheme and path.
+
+```ruby
+deeplink = Deeplink.parse('myshop://products/42')
+
+deeplink.scheme # => "myshop"
+deeplink.path   # => "/products/42"
+deeplink.to_s   # => "myshop://products/42"
+```
+
+Links without a double slash are supported too:
 
 ```ruby
-deeplink = Deeplink.parse('foursquare://checkins/12932')
+deeplink = Deeplink.parse('sms:+351910000000?body=hello')
 
-deeplink.scheme # => "foursquare"
-deeplink.path   # => "/checkins/12932"
-deeplink.to_s   # => "foursquare://checkins/12932"
+deeplink.scheme # => "sms"
+deeplink.path   # => "+351910000000"
+deeplink.to_s   # => "sms:+351910000000?body=hello"
 ```
 
 ### Query string
 
-To get the query parameters of a link use `query` method.
+Use `query` to read the query parameters, and `query?` to check whether there are any.
 
 ```ruby
-deeplink = Deeplink.parse('foursquare://checkins/209823?test=true')
+deeplink = Deeplink.parse('myshop://products/42?ref=email')
 
-deeplink.query # => { :test => "true" }
+deeplink.query  # => { ref: "email" }
+deeplink.query? # => true
 ```
 
-#### Adding a query parameter
-
-You can add one or more query parameters sending a Hash to `add_query`.
+Values are stored decoded and only encoded again by `to_s`. Parameters without a value get a `nil`
+value.
 
 ```ruby
-deeplink = Deeplink.parse('foursquare://checkins/20982')
+deeplink = Deeplink.parse('myshop://search?q=running%20shoes&in_stock')
+
+deeplink.query # => { q: "running shoes", in_stock: nil }
+deeplink.to_s  # => "myshop://search?q=running+shoes&in_stock"
+```
+
+#### Adding query parameters
 
-deeplink.add_query(foo: 'bar') # => { :foo => "bar" }
-deeplink.to_s                  # => "foursquare://checkins/20982?foo=bar"
+Send a Hash with one or more parameters to `add_query`. Values are converted to strings.
 
-deeplink = Deeplink.parse('foursquare://checkins/20982')
+```ruby
+deeplink = Deeplink.parse('myshop://cart')
 
-deeplink.add_query(foo: 'bar', biz: 'baz') # => { :foo => "bar", :biz => "baz" }
-deeplink.to_s                              # => "foursquare://checkins/20982?foo=bar&biz=baz"
+deeplink.add_query(coupon: 'SUMMER 10', items: 3) # => { coupon: "SUMMER 10", items: "3" }
+deeplink.to_s                                     # => "myshop://cart?coupon=SUMMER+10&items=3"
 ```
 
-#### Removing a query parameter
+#### Removing query parameters
 
-To remove query parameters call `remove_query` with the key (or list of keys) that you want to
-remove. The method will return the value of the deleted key(s).
+Call `remove_query` with the key (or list of keys) to remove. It returns the value of the deleted
+key(s).
 
 ```ruby
-deeplink = Deeplink.parse('foursquare://checkins/20982?foo=bar')
+deeplink = Deeplink.parse('myshop://products/42?ref=email&utm_source=newsletter')
+
+deeplink.remove_query(:utm_source) # => "newsletter"
+deeplink.to_s                      # => "myshop://products/42?ref=email"
 
-deeplink.remove_query(:foo) # => "bar"
-deeplink.to_s               # => "foursquare://checkins/20982"
+deeplink.remove_query(:ref, :missing) # => ["email", nil]
+deeplink.to_s                         # => "myshop://products/42"
 ```
 
+### Fragment
+
+The fragment is available through `fragment`, and is kept as given (percent-encoded).
+
 ```ruby
-deeplink = Deeplink.parse('foursquare://checkins/20982?foo=bar&fu=baz')
+deeplink = Deeplink.parse('myshop://products/42#reviews')
 
-deeplink.remove_query(:foo, :fu) # => ["bar", "baz"]
-deeplink.to_s                    # => "foursquare://checkins/20982"
+deeplink.fragment # => "reviews"
+deeplink.to_s     # => "myshop://products/42#reviews"
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the tests and RuboCop. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake`
+to run the tests and RuboCop. You can also run `bin/console` for an interactive prompt that will
+allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb` and `CHANGELOG.md`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push git commits and tags,
+and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rikas/deeplink.
 
-
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/deeplink/link.rb

@@ -11,9 +11,11 @@ end
 
 module Deeplink
   class Link
-    attr_accessor :scheme, :path
+    # The fragment is kept as given, so it should already be percent-encoded.
+    attr_accessor :scheme, :path, :fragment
 
-    # To add and remove items to the query string use #add_query and #remove_query
+    # Query values are stored decoded and only encoded by #to_s. To add and remove items to the
+    # query string use #add_query and #remove_query.
     attr_reader :query
 
     def initialize(uri)
@@ -22,9 +24,12 @@ module Deeplink
       uri = parse(uri)
 
       self.scheme = uri.scheme
-      self.path = uri.path
+      self.fragment = uri.fragment
 
-      @query = sanitize(parse_query(uri.query)) if uri.query
+      # Links without "//" (e.g. "deep:foo?a=1") are opaque, and URI leaves the query in there.
+      self.path, query_string = uri.opaque ? uri.opaque.split('?', 2) : [uri.path, uri.query]
+
+      @query = parse_query(query_string) if query_string
     end
 
     # Add query parameters to the link. You can add one or more parameters since this method
@@ -37,6 +42,8 @@ module Deeplink
     #   deeplink.add_query(lat: 38.7179233, lon: -9.150129)
     #
     #   deeplink.to_s # => "link://directions?lat=38.7179233&lon=-9.150129"
+    #
+    # Values are converted to strings. A nil value adds a parameter without a value ("?flag").
     def add_query(hash)
       @query ||= {}
 
@@ -84,13 +91,9 @@ module Deeplink
     def to_s
       return '' unless scheme && path
 
-      uri = "#{scheme}:/#{path}"
-
-      if query?
-        query_string = query.map { |key, value| "#{key}=#{value}" }.join('&')
-
-        uri += "?#{query_string}"
-      end
+      uri = @double_slash ? "#{scheme}:/#{path}" : "#{scheme}:#{path}"
+      uri += "?#{query_string}" if query?
+      uri += "##{fragment}" if fragment
 
       uri
     end
@@ -98,31 +101,34 @@ module Deeplink
     private
 
     def parse(original_uri)
+      @double_slash = original_uri.match?(%r{\A[^:/?#]+://})
+
       # Because URI is dumb and thinks that every uri needs to have a host. Adding an extra slash
       # we are basically tricking URI to think that host is nil (and avoid errors).
-      uri = original_uri.sub(%r{://}, ':///')
+      uri = @double_slash ? original_uri.sub('://', ':///') : original_uri
 
       URI.parse(uri)
     end
 
     def sanitize(hash)
-      sanitized = {}
+      hash.to_h { |key, value| [key.to_sym, value&.to_s] }
+    end
 
-      hash.each_key do |key|
-        value = hash[key].is_a?(String) ? CGI.escape(hash[key]) : hash[key].to_s
+    def parse_query(query_str)
+      query_str.split('&').each_with_object({}) do |pair, params|
+        key, value = pair.split('=', 2)
+        next if key.nil? || key.empty?
 
-        sanitized[key.to_sym] = value
+        params[CGI.unescape(key).to_sym] = value && CGI.unescape(value)
       end
-
-      sanitized
     end
 
-    def parse_query(query_str)
-      return unless query_str
+    def query_string
+      query.map do |key, value|
+        key = CGI.escape(key.to_s)
 
-      # Values are unescaped here because #sanitize escapes them again; otherwise already encoded
-      # values (e.g. "%20") would end up double encoded.
-      query_str.scan(/([^&=]+)=([^&{}#]*)/).to_h { |key, value| [key, CGI.unescape(value)] }
+        value.nil? ? key : "#{key}=#{CGI.escape(value)}"
+      end.join('&')
     end
   end
 end

data/lib/deeplink/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Deeplink
-  VERSION = '2.0.0'
+  VERSION = '3.0.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deeplink
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Ricardo Otero
@@ -16,6 +16,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - lib/deeplink.rb
@@ -27,6 +28,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/rikas/deeplink
   bug_tracker_uri: https://github.com/rikas/deeplink/issues
+  changelog_uri: https://github.com/rikas/deeplink/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: