iuri 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f823ae8478599ae553df7854ab74819fd56e1301
-  data.tar.gz: 81dc21e0b3899b2ddd6908f95fc5d0919e6ee861
+  metadata.gz: 80c50f10a15c87f8aedd47924a82bd4069c1a9e3
+  data.tar.gz: a78f253736108f72b6b27bdae2ace3563859e6d5
 SHA512:
-  metadata.gz: 131316b2a076b97a9d386651a9aa92f24f4f50506b9507b311c3956d06ddba0273836b6f7d03b6d981d9b49e2065f504404dc8f8de608e39ab7586c90668e7b5
-  data.tar.gz: 8b59b357b357509a98cf600e1e2b80133a7b3aefdf10eb27259bf73c9b67fa7f17e926e3fd6d29b90f4a7d752f8c366e63f49a6faa7b47681ab030800e974bf0
+  metadata.gz: 8c904845ebc55971e9f3d968e49b5b1b28a088d97db83ed20477f144e19e608d0057e51bbbdcebea703ce0eb1e9b05509942cac4cd7ad57494be1b92e3742500
+  data.tar.gz: 015553c5aa28b0aa769f498b33ccadb870792272a0acbcb229719aa55928dd1c48bf92fab889a6a9640cd5fa3afe437f2270dce6502e8ace1d5fdb9bc131ad04

data/.travis.yml

@@ -0,0 +1,3 @@
+rvm:
+  - "2.1.2"
+  - "2.1.3"

data/README.md

@@ -1,42 +1,158 @@
 # IURI
 
-Build complex URIs with chainability and immutability. If you're familiar
-with URI then you already know how to use it.
+[![Build Status](https://travis-ci.org/tatey/iuri.svg?branch=master)](https://travis-ci.org/tatey/iuri)
+
+Build complex URIs with chainability and immutability. No string
+concatenation required. If you're familiar with `URI` then you already know
+how to use it.
+
+First it starts like this.
+
+``` ruby
+"https://lifx.co/api/v1/devices".
+```
+
+Then you need to target different hosts in development, staging and
+production.
+
+``` ruby
+"#{ENV['API_SCHEME']}://#{ENV['API_HOST']}/api/v1/devices"
+```
+
+Then staging becomes protected by basic authentication.
+
+``` ruby
+if ENV['API_CREDENTIALS']
+  "#{ENV['API_SCHEME']}://#{ENV['API_CREDENTIALS']}@#{ENV['API_HOST']}/api/v1/devices"
+else
+  "#{ENV['API_SCHEME']}://#{ENV['API_HOST']}/api/v1/devices"
+end
+```
+
+Then you need to target different paths.
+
+``` ruby
+def devices_url
+  base_url + '/api/v1/devices'
+end
+
+def accounts_url
+  base_url + '/api/v1/accounts'
+end
+
+def base_url
+  if ENV['API_CREDENTIALS']
+    "#{ENV['API_SCHEME']}://#{ENV['API_CREDENTIALS']}@#{ENV['API_HOST']}"
+  else
+    "#{ENV['API_SCHEME']}://#{ENV['API_HOST']}"
+  end
+end
+```
+
+Now you've added three environment variables and you're vulnerable to
+developers mistyping URLs. With `IURI` there's a better way.
+
+``` ruby
+# Development
+# ENV['API_BASE_URL'] = 'http://lifx.dev'
+#
+# Staging
+# ENV['API_BASE_URL'] = 'https://user:pass@staging.lifx.co'
+#
+# Production
+# ENV['API_BASE_URL'] = 'https://lifx.co'
+
+def devices_url
+  API_BASE_URL.merge(path: "/api/v1/devices")
+end
+
+def accounts_url
+  API_BASE_URL.merge(path: "/api/v1/accounts")
+end
+
+def API_BASE_URL
+  IURI.parse(ENV['API_BASE_URL'])
+end
+```
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'iuri'
-
-And then execute:
-
-    $ bundle
+## Usage
 
-Or install it yourself as:
+Parse URL and append a path.
+
+``` ruby
+uri = IURI.parse("https://user:secret@lifx.co").merge(path: "/api/v1/devices")
+uri.to_s # => "https://user:secret@lifx.co/api/v1/devices"
+```
+
+Preferring components to strings gives you greater flexibility over the
+base URL. Here we include a query string at the end of the URL and change
+the path as required.
+
+``` ruby
+uri = IURI.parse("https://lifx.co?api_key=secret").merge(path: "/api/v1/devices")
+uri.to_s # => "https://lifx.co/api/v1/devices?api_key=secret"
+```
+
+Queries can also be built with a hash avoiding worrying about formatting
+and escaping. Deep hashes are OK.
+
+``` ruby
+uri = IURI.parse("https://lifx.co").merge(params: {api_key: 'secret'})
+uri.to_s # => "https://lifx.co/?api_key=secret"
+```
+
+Supports the same components as `URI`. Here's a sample of commonly used
+components.
+
+``` ruby
+iuri = IURI.parse("https://lifx.co").merge({
+  path: "/api/v1/devices"
+  query: "api_key=secret"
+  user: "user"
+  password: "secret"
+})
+
+iuri.path     # => "/api/v1/devices"
+iuri.query    # => "api_key=secret"
+iuri.user     # => "user"
+iuri.password # => "secret"
+```
+
+Each `merge` returns a copy guaranteeing that constants and variables
+remain unchanged.
+
+``` ruby
+uri1 = IURI.parse("https://lifx.co")
+uri2 = uri1.merge(path: "/api/v1/devices")
+uri1.to_s # => "https://lifx.co"
+uri2.to_s # => "https://lifx.co/api/v1/devices"
+```
 
-    $ gem install iuri
+## Installation
 
-## Usage
+First, add this line to your application's Gemfile.
 
-Change components of a URI using a hash. Changes are chainable and each
-one returns a new instance.
+``` ruby
+gem 'iuri'
+```
 
-Example:
+Then, then execute.
 
-    uri1 = IURI.parse("https://user:secret@lifx.co")
-    uri2 = uri1.merge(path: "/api/v1/foos")
-    uri2.to_s # => "https://user:secret@lifx.co/api/v1/foos"
+```
+$ bundle
+```
 
 ## Tests
 
 Run the entire test suite.
 
-    $ rake
+```
+$ rake
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/tatey/iuri/fork )
+1. Fork it (https://github.com/tatey/iuri/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -1,4 +1,5 @@
 require 'bundler/gem_tasks'
+require 'bundler/setup'
 require 'rake/testtask'
 
 Rake::TestTask.new :test do |test|

data/iuri.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Tate Johnson']
   spec.email         = ['tate@lifx.co']
   spec.summary       = %q{Build complex URIs with chainability and immutability.}
-  spec.description   = %q{Build complex URIs with chainability and immutability.}
-  spec.homepage      = ''
+  spec.description   = %q{Build complex URIs with chainability and immutability. No string concatenation required.}
+  spec.homepage      = 'https://github.com/tatey/iuri'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -19,5 +19,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'minitest', '~> 5.4.2'
   spec.add_development_dependency 'rake'
 end

data/lib/iuri.rb

@@ -1,40 +1,69 @@
+require 'delegate'
 require 'uri'
 require 'iuri/version'
 
-class IURI
-  def initialize(uri)
-    @uri = uri
-  end
-
+module IURI
   def self.parse(string)
     uri = URI.parse(string)
-    new(uri)
+    Generic.new(uri)
   end
 
-  # Change components of a URI using a hash. Changes are chainable and
-  # each one returns a new instance.
-  #
-  # Example:
-  #   uri1 = MergeableURI.parse("https://lifx.co")
-  #   uri2 = uri1.merge(path: "/foo/bar")
-  #   uri2.to_s # => "https://lifx.co/foo/bar"
-  #
-  # @param options [Hash] Components
-  # @return [MergeableURI] A new instance
-  def merge(options)
-    copy = @uri.dup
-    options.each do |key, value|
-      writer = :"#{key}="
-      if copy.respond_to?(writer)
-        copy.send(writer, value)
+  class Generic < SimpleDelegator
+    # Change components of a URI using a hash. Changes are chainable and
+    # each one returns a new instance.
+    #
+    # Example:
+    #   uri1 = IURI.parse("https://lifx.co")
+    #   uri2 = uri1.merge(path: "/foo/bar")
+    #   uri2.to_s # => "https://lifx.co/foo/bar"
+    #
+    # @param options [Hash] Components
+    # @return [URI] A new instance
+    def merge(components)
+      copy = clone
+      components.each do |key, value|
+        writer = :"#{key}="
+        if copy.respond_to?(writer)
+          copy.send(writer, value)
+        else
+          raise KeyError, "key not found: \"#{key}\""
+        end
+      end
+      copy
+    end
+
+    def params=(new_params)
+      self.query = build_nested_query(new_params)
+    end
+
+    def inspect
+      super.sub('#<URI', '#<IURI')
+    end
+
+    private
+
+    # A special thanks to rack for this one.
+    # See https://github.com/rack/rack/blob/e98a9f7ef0ddd9589145ea953948c73a8ce3caa9/lib/rack/utils.rb
+    def build_nested_query(value, prefix = nil)
+      case value
+      when Array
+        value.map { |v|
+          build_nested_query(v, "#{prefix}[]")
+        }.join("&")
+      when Hash
+        value.map { |k, v|
+          build_nested_query(v, prefix ? "#{prefix}[#{escape(k)}]" : escape(k))
+        }.reject(&:empty?).join('&')
+      when nil
+        prefix
       else
-        raise KeyError, "key not found: \"#{key}\""
+        raise ArgumentError, "value must be a Hash" if prefix.nil?
+        "#{prefix}=#{escape(value)}"
       end
     end
-    self.class.new(copy)
-  end
 
-  def to_s
-    @uri.to_s
+    def escape(value)
+      URI.encode_www_form_component(value)
+    end
   end
 end

data/lib/iuri/version.rb

@@ -1,3 +1,3 @@
-class IURI
-  VERSION = '1.0.0'
+module IURI
+  VERSION = '1.1.0'
 end

data/test/iuri_test.rb

@@ -2,23 +2,45 @@ require 'minitest/autorun'
 require 'iuri'
 
 class IURITest < Minitest::Test
-  def test_it_sets_known_components
+  def test_setting_known_components
     uri1 = IURI.parse('http://lifx.co')
     uri2 = uri1.merge(scheme: 'https', path: '/foo/bar', query: 'baz=true')
 
     assert_equal 'https://lifx.co/foo/bar?baz=true', uri2.to_s
   end
 
-  def test_it_raises_unknown_components
+  def test_setting_unknown_components_raises_key_error
     assert_raises(KeyError) do
       IURI.parse('http://lifx.co').merge(combobulator: 42)
     end
   end
 
-  def test_it_is_a_copy
+  def test_setting_params
+    uri1 = IURI.parse('http://lifx.co')
+    uri2 = uri1.merge(params: {a: '1', b: ['1', '2', '3'], c: {d: '1'}})
+
+    assert_equal 'http://lifx.co?a=1&b[]=1&b[]=2&b[]=3&c[d]=1', uri2.to_s
+  end
+
+  def test_getting_known_components
+    uri = IURI.parse('http://lifx.co/foo/bar?baz=true')
+
+    assert uri.scheme, 'http'
+    assert uri.host, 'lifx.co'
+    assert uri.path, '/foo/bar'
+    assert uri.query, 'baz=true'
+  end
+
+  def test_merge_returns_copy
     uri1 = IURI.parse('http://lifx.co')
     uri2 = uri1.merge(path: '/foo/bar')
 
     refute_same uri1, uri2
   end
+
+  def test_inspect
+    uri = IURI.parse('http://lifx.co')
+
+    assert_match /\A#<IURI/, uri.inspect
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iuri
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Tate Johnson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-16 00:00:00.000000000 Z
+date: 2014-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.4.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.4.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +52,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Build complex URIs with chainability and immutability.
+description: Build complex URIs with chainability and immutability. No string concatenation
+  required.
 email:
 - tate@lifx.co
 executables: []
@@ -46,6 +61,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -54,7 +70,7 @@ files:
 - lib/iuri.rb
 - lib/iuri/version.rb
 - test/iuri_test.rb
-homepage: ''
+homepage: https://github.com/tatey/iuri
 licenses:
 - MIT
 metadata: {}
@@ -80,4 +96,3 @@ specification_version: 4
 summary: Build complex URIs with chainability and immutability.
 test_files:
 - test/iuri_test.rb
-has_rdoc: