uri_template 0.4.0 → 0.5.0

data/lib/uri_template/token.rb

@@ -0,0 +1,64 @@
+# -*- encoding : utf-8 -*-
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the Affero GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#    (c) 2011 - 2012 by Hannes Georg
+#
+
+# This should make it possible to do basic analysis independently from the concrete type.
+# Usually the submodules {URITemplate::Literal} and {URITemplate::Expression} are used.
+#
+# @abstract
+module URITemplate::Token
+
+  EMPTY_ARRAY = [].freeze
+
+  # The variable names used in this token.
+  #
+  # @return [Array<String>]
+  def variables
+    EMPTY_ARRAY
+  end
+
+  # Number of variables in this token
+  def size
+    variables.size
+  end
+
+  def starts_with_slash?
+    false
+  end
+
+  def ends_with_slash?
+    false
+  end
+
+  def scheme?
+    false
+  end
+
+  def host?
+    false
+  end
+
+  # @abstract
+  def expand(variables)
+    raise "Please implement #expand(variables) on #{self.class.inspect}."
+  end
+
+  # @abstract
+  def to_s
+    raise "Please implement #to_s on #{self.class.inspect}."
+  end
+
+end

data/lib/uri_template/utils.rb

@@ -24,17 +24,22 @@ module URITemplate
 
     include Enumerable
 
-    def initialize(regexp)
+    def initialize(regexp, options = {})
       @regexp = regexp
+      @rest = options.fetch(:rest){ :yield }
     end
 
     def each(str)
+      raise ArgumentError, "RegexpEnumerator#each expects a String, but got #{str.inspect}" unless str.kind_of? String
       return Enumerator.new(self,:each,str) unless block_given?
       rest = str
       loop do
         m = @regexp.match(rest)
         if m.nil?
-          yield rest
+          if rest.size > 0
+            yield rest if @rest == :yield
+            raise "Unable to match #{rest.inspect} against #{@regexp.inspect}" if @rest == :raise
+          end
           break
         end
         yield m.pre_match if m.pre_match.size > 0
@@ -42,7 +47,10 @@ module URITemplate
         if m[0].size == 0
           # obviously matches empty string, so post_match will equal rest
           # terminate or this will loop forever
-          yield m.post_match
+          if m.post_match.size > 0
+            yield m.post_match if @rest == :yield
+            raise "#{@regexp.inspect} matched an empty string. The rest is #{m.post_match.inspect}." if @rest == :raise
+          end
           break
         end
         rest = m.post_match
@@ -95,6 +103,19 @@ module URITemplate
         str.encode(Encoding::UTF_8)
       end
 
+      # @method force_utf8(str)
+      # enforces UTF8 encoding
+      # 
+      # @param str [String]
+      # @return String
+      # @visibility public
+      def force_utf8_encode(str)
+        return str if str.encoding == Encoding::UTF_8
+        str = str.dup if str.frozen?
+        return str.force_encoding(Encoding::UTF_8)
+      end
+
+
       def to_ascii_fallback(str)
         str
       end
@@ -103,16 +124,24 @@ module URITemplate
         str
       end
 
+      def force_utf8_fallback(str)
+        str
+      end
+
       if "".respond_to?(:encode)
         # @api private
         send(:alias_method, :to_ascii, :to_ascii_encode)
         # @api private
         send(:alias_method, :to_utf8, :to_utf8_encode)
+        # @api private
+        send(:alias_method, :force_utf8, :force_utf8_encode)
       else
         # @api private
         send(:alias_method, :to_ascii, :to_ascii_fallback)
         # @api private
         send(:alias_method, :to_utf8, :to_utf8_fallback)
+        # @api private
+        send(:alias_method, :force_utf8, :force_utf8_fallback)
       end
 
       public :to_ascii
@@ -150,13 +179,13 @@ module URITemplate
         end
 
         def unescape_url(s)
-          to_utf8( s.to_s.gsub('+',' ').gsub(PCT){
+          force_utf8( to_ascii(s).gsub('+',' ').gsub(PCT){
             $1.to_i(16).chr
           } )
         end
 
         def unescape_uri(s)
-          to_utf8( s.to_s.gsub(PCT){
+          force_utf8( to_ascii(s).gsub(PCT){
             $1.to_i(16).chr
           })
         end
@@ -190,11 +219,11 @@ module URITemplate
         end
 
         def unescape_url(s)
-          super(to_ascii(s))
+          force_utf8(super(to_ascii(s)))
         end
 
         def unescape_uri(s)
-          super(to_ascii(s))
+          force_utf8(super(to_ascii(s)))
         end
 
       end
@@ -235,6 +264,14 @@ module URITemplate
       raise Unconvertable.new(object)
     end
 
+    # @api private
+    # Should we use \u.... or \x.. in regexps?
+    def use_unicode?
+      return eval('Regexp.compile("\u0020")') =~ " "
+    rescue SyntaxError
+      false
+    end
+
     # Returns true when the given value is an array and it only consists of arrays with two items.
     # This useful when using a hash is not ideal, since it doesn't allow duplicate keys.
     # @example
@@ -258,14 +295,14 @@ module URITemplate
     #   URITemplate::Utils.pair_array_to_hash( [ ['a',1],['a',2],['a',3] ] ) #=> {'a'=>3}
     #
     # @example Carful vs. Ignorant
-    #   URITemplate::Utils.pair_array_to_hash( [ ['a',1],'foo','bar'], false ) #=> {'a'=>1,'foo'=>'bar'}
-    #   URITemplate::Utils.pair_array_to_hash( [ ['a',1],'foo','bar'], true ) #=> [ ['a',1],'foo','bar']
+    #   URITemplate::Utils.pair_array_to_hash( [ ['a',1],'foo','bar'], false ) #UNDEFINED!
+    #   URITemplate::Utils.pair_array_to_hash( [ ['a',1],'foo','bar'], true )  #=> [ ['a',1], 'foo', 'bar']
     #
     # @param x the value to convert
     # @param careful [true,false] wheter to check every array item. Use this when you expect array with subarrays which are not pairs. Setting this to false however improves runtime by ~30% even with comparetivly short arrays.
     def pair_array_to_hash(x, careful = false )
       if careful ? pair_array?(x) : (x.kind_of?(Array) and ( x.empty? or x.first.kind_of?(Array) ) )
-        return Hash[ *x.flatten(1) ]
+        return Hash[ x ]
       else
         return x
       end

data/lib/uri_template.rb

@@ -18,87 +18,27 @@
 # A base module for all implementations of a uri template.
 module URITemplate
 
-  # @private
-  # Should we use \u.... or \x.. in regexps?
-  SUPPORTS_UNICODE_CHARS = begin
-                             if "string".respond_to? :encoding
-                               rx = eval('Regexp.compile("\u0020")')
-                               !!(rx =~ " ")
-                             else
-                               rx = eval('/\u0020/')
-                               !!(rx =~ " ")
-                             end
-                           rescue SyntaxError
-                             false
-                           end
-
-  # This should make it possible to do basic analysis independently from the concrete type.
-  module Token
-
-    def size
-      variables.size
-    end
-
-  end
-
-  # A module which all literal tokens should include.
-  module Literal
-
-    include Token
-
-    attr_reader :string
-
-    def literal?
-      true
-    end
-
-    def expression?
-      false
-    end
-
-    def variables
-      []
-    end
-
-    def size
-      0
-    end
-
-    def expand(*_)
-      return string
-    end
-
-  end
-
-  # A module which all non-literal tokens should include.
-  module Expression
-
-    include Token
-
-    attr_reader :variables
-
-    def literal?
-      false
-    end
+  # @api private
+  SCHEME_REGEX = /\A[a-z]+:/i.freeze
 
-    def expression?
-      true
-    end
+  # @api private
+  HOST_REGEX = /\A(?:[a-z]+:)?\/\/[^\/]+/i.freeze
 
-  end
+  # @api private
+  URI_SPLIT = /\A(?:([a-z]+):)?(?:\/\/)?([^\/]+)?/i.freeze
 
   autoload :Utils, 'uri_template/utils'
-  autoload :Draft7, 'uri_template/draft7'
+  autoload :Token, 'uri_template/token'
+  autoload :Literal, 'uri_template/literal'
+  autoload :Expression, 'uri_template/expression'
   autoload :RFC6570, 'uri_template/rfc6570'
   autoload :Colon, 'uri_template/colon'
 
   # A hash with all available implementations.
-  # Currently the only implementation is :draft7. But there also aliases :default and :latest available. This should make it possible to add newer specs later.
   # @see resolve_class
   VERSIONS = {
-    :draft7 => :Draft7,
     :rfc6570 => :RFC6570,
-    :default => :Draft7,
+    :default => :RFC6570,
     :colon => :Colon,
     :latest => :RFC6570
   }
@@ -107,10 +47,11 @@ module URITemplate
   # Extracts all symbols from args and looks up the first in {VERSIONS}.
   #
   # @return Array an array of the class to use and the unused parameters.
+  # 
   # @example
-  #   URITemplate.resolve_class() #=> [ URITemplate::Draft7, [] ]
-  #   URITemplate.resolve_class(:draft7) #=> [ URITemplate::Draft7, [] ]
-  #   URITemplate.resolve_class("template",:draft7) #=> [ URITemplate::Draft7, ["template"] ]
+  #   URITemplate.resolve_class() #=> [ URITemplate::RFC6570, [] ]
+  #   URITemplate.resolve_class(:colon) #=> [ URITemplate::Colon, [] ]
+  #   URITemplate.resolve_class("template",:rfc6570) #=> [ URITemplate::RFC6570, ["template"] ]
   # 
   # @raise ArgumentError when no class was found.
   #
@@ -130,7 +71,7 @@ module URITemplate
   #   tpl.expand('x'=>'y') #=> 'y'
   #
   # @example
-  #   tpl = URITemplate.new(:draft7,'{x}') # a new template using the draft7 implementation
+  #   tpl = URITemplate.new(:colon,'/:x') # a new template using the colon implementation
   # 
   def self.new(*args)
     klass, rest = resolve_class(*args)
@@ -167,8 +108,10 @@ module URITemplate
   # Returns an array with two {URITemplate}s and two booleans indicating which of the two were converted or raises an ArgumentError.
   #
   # @example
-  #   URITemplate.coerce( URITemplate.new(:draft7,'{x}'), '{y}' ) #=> [URITemplate.new(:draft7,'{x}'), URITemplate.new(:draft7,'{y}'), false, true]
-  #   URITemplate.coerce( '{y}', URITemplate.new(:draft7,'{x}') ) #=> [URITemplate.new(:draft7,'{y}'), URITemplate.new(:draft7,'{x}'), true, false]
+  #   URITemplate.coerce( URITemplate.new(:rfc6570,'{x}'), '{y}' ) #=> [URITemplate.new(:rfc6570,'{x}'), URITemplate.new(:rfc6570,'{y}'), false, true]
+  #   URITemplate.coerce( '{y}', URITemplate.new(:rfc6570,'{x}') ) #=> [URITemplate.new(:rfc6570,'{y}'), URITemplate.new(:rfc6570,'{x}'), true, false]
+  #
+  # @return [Tuple<URITemplate,URITemplate,Bool,Bool>]
   def self.coerce(a,b)
     if a.kind_of? URITemplate
       if a.class == b.class
@@ -210,6 +153,19 @@ module URITemplate
     a.send(method,b,*args)
   end
 
+  def self.coerce_first_arg(meth)
+    alias_method( (meth.to_s + '_without_coercion').to_sym , meth )
+    class_eval(<<-RUBY)
+def #{meth}(other, *args, &block)
+  this, other, this_converted, _ = URITemplate.coerce( self, other )
+  if this_converted
+    return this.#{meth}(other,*args, &block)
+  end
+  return #{meth}_without_coercion(other,*args, &block)
+end
+RUBY
+  end
+
   # A base class for all errors which will be raised upon invalid syntax.
   module Invalid
   end
@@ -226,7 +182,9 @@ module URITemplate
   # strings in order to support the Ruby 1.9 hash syntax.
   #
   # @raise {Unconvertable} if a variable could not be converted to a string.
-  # @param variables Hash
+  # @raise {InvalidValue} if a value is not suiteable for a certain variable ( e.g. a string when a list is expected ).
+  #
+  # @param variables [#map]
   # @return String
   def expand(variables = {})
     raise ArgumentError, "Expected something that returns to :map, but got: #{variables.inspect}" unless variables.respond_to? :map
@@ -241,12 +199,16 @@ module URITemplate
 
   # @abstract
   # Returns the type of this template. The type is a symbol which can be used in {.resolve_class} to resolve the type of this template.
+  #
+  # @return [Symbol]
   def type
     raise "Please implement #type on #{self.class.inspect}."
   end
 
   # @abstract
   # Returns the tokens of this templates. Tokens should include either {Literal} or {Expression}.
+  #
+  # @return [Array<URITemplate::Token>]
   def tokens
     raise "Please implement #tokens on #{self.class.inspect}."
   end
@@ -256,9 +218,9 @@ module URITemplate
   #   URITemplate.new('{foo}{bar}{baz}').variables #=> ['foo','bar','baz']
   #   URITemplate.new('{a}{c}{a}{b}').variables #=> ['a','c','b']
   #
-  # @return Array
+  # @return [Array<String>]
   def variables
-    @variables ||= tokens.select(&:expression?).map(&:variables).flatten.uniq
+    @variables ||= tokens.map(&:variables).flatten.uniq.freeze
   end
 
   # Returns the number of static characters in this template.
@@ -275,28 +237,167 @@ module URITemplate
     @static_characters ||= tokens.select(&:literal?).map{|t| t.string.size }.inject(0,:+)
   end
 
-  # Returns whether this uri-template is absolute.
-  # This is detected by checking for "://".
+  # Returns whether this uri-template includes a host name
+  #
+  # This method is usefull to check wheter this template will generate 
+  # or match a uri with a host.
+  #
+  # @see #scheme?
   #
-  def absolute?
-    return @absolute unless @absolute.nil?
+  # @example
+  #   URITemplate.new('/foo').host? #=> false
+  #   URITemplate.new('//example.com/foo').host? #=> true
+  #   URITemplate.new('//{host}/foo').host? #=> true
+  #   URITemplate.new('http://example.com/foo').host? #=> true
+  #   URITemplate.new('{scheme}://example.com/foo').host? #=> true
+  #
+  def host?
+    return scheme_and_host[1]
+  end
+
+  # Returns whether this uri-template includes a scheme
+  #
+  # This method is usefull to check wheter this template will generate 
+  # or match a uri with a scheme.
+  # 
+  # @see #host?
+  #
+  # @example
+  #   URITemplate.new('/foo').scheme? #=> false
+  #   URITemplate.new('//example.com/foo').scheme? #=> false
+  #   URITemplate.new('http://example.com/foo').scheme? #=> true
+  #   URITemplate.new('{scheme}://example.com/foo').scheme? #=> true
+  #
+  def scheme?
+    return scheme_and_host[0]
+  end
+
+  # Returns the pattern for this template.
+  #
+  # @return String
+  def pattern
+    @pattern ||= tokens.map(&:to_s).join
+  end
+
+  alias to_s pattern
+
+  # Compares two template patterns.
+  def eq(other)
+    return self.pattern == other.pattern
+  end
+
+  coerce_first_arg :eq
+
+  alias == eq
+
+  # Tries to concatenate two templates, as if they were path segments.
+  # Removes double slashes or insert one if they are missing.
+  #
+  # @example
+  #   tpl = URITemplate::RFC6570.new('/xy/')
+  #   (tpl / '/z/' ).pattern #=> '/xy/z/'
+  #   (tpl / 'z/' ).pattern #=> '/xy/z/'
+  #   (tpl / '{/z}' ).pattern #=> '/xy{/z}'
+  #   (tpl / 'a' / 'b' ).pattern #=> '/xy/a/b'
+  #
+  # @param other [URITemplate, String, ...]
+  # @return URITemplate
+  def path_concat(other)
+    if other.host? or other.scheme?
+      raise ArgumentError, "Expected to receive a relative template but got an absoulte one: #{other.inspect}. If you think this is a bug, please report it."
+    end
+
+    return self if other.tokens.none?
+    return other if self.tokens.none?
+
+    tail = self.tokens.last
+    head = other.tokens.first
+
+    if tail.ends_with_slash?
+      if head.starts_with_slash?
+        return self.class.new( remove_double_slash(self.tokens, other.tokens) )
+      end
+    elsif !head.starts_with_slash?
+      return self.class.new( (self.tokens + ['/'] + other.tokens).join)
+    end
+    return self.class.new( (self.tokens + other.tokens).join )
+  end
+
+  coerce_first_arg :path_concat
+
+  alias / path_concat
+
+  # Concatenate two template with conversion.
+  #
+  # @example
+  #   tpl = URITemplate::RFC6570.new('foo')
+  #   (tpl + '{bar}' ).pattern #=> 'foo{bar}'
+  #
+  # @param other [URITemplate, String, ...]
+  # @return URITemplate
+  def concat(other)
+    if other.host? or other.scheme?
+      raise ArgumentError, "Expected to receive a relative template but got an absoulte one: #{other.inspect}. If you think this is a bug, please report it."
+    end
+
+    return self if other.tokens.none?
+    return other if self.tokens.none?
+    return self.class.new( self.to_s + other.to_s )
+  end
+
+  coerce_first_arg :concat
+
+  alias + concat
+  alias >> concat
+
+  # @api private
+  def remove_double_slash( first_tokens, second_tokens )
+    if first_tokens.last.literal?
+      return first_tokens[0..-2] + [ first_tokens.last.to_s[0..-2] ] + second_tokens
+    elsif second_tokens.first.literal?
+      return first_tokens + [ second_tokens.first.to_s[1..-1] ] + second_tokens[1..-1]
+    else
+      raise ArgumentError, "Cannot remove double slashes from #{first_tokens.inspect} and #{second_tokens.inspect}."
+    end
+  end
+
+  private :remove_double_slash
+
+  # @api private
+  def scheme_and_host
+    return @scheme_and_host if @scheme_and_host
     read_chars = ""
+    @scheme_and_host = [false,false]
     tokens.each do |token|
       if token.expression?
         read_chars << "x"
+        if token.scheme?
+          read_chars << ':'
+        end
+        if token.host?
+          read_chars << '//'
+        end
+        read_chars << "x"
       elsif token.literal?
         read_chars << token.string
       end
-      if read_chars =~ /^[a-z]+:\/\//i
-        return @absolute = true
+      if read_chars =~ SCHEME_REGEX
+        @scheme_and_host = [true, true]
+        break
+      elsif read_chars =~ HOST_REGEX
+        @scheme_and_host[1] = true
+        break
       elsif read_chars =~ /(^|[^:\/])\/(?!\/)/
-        return @absolute = false
+        break
       end
     end
-
-    return @absolute = false
+    return @scheme_and_host
   end
 
+  private :scheme_and_host
+
+  alias absolute? host?
+
   # Opposite of {#absolute?}
   def relative?
     !absolute?

data/uri_template.gemspec

@@ -1,16 +1,16 @@
 Gem::Specification.new do |s|
   s.name = 'uri_template'
-  s.version = '0.4.0'
-  s.date = '2012-07-06'
+  s.version = '0.5.0'
+  s.date = Time.now.strftime('%Y-%m-%d')
   s.authors = ["HannesG"]
   s.email = %q{hannes.georg@googlemail.com}
   s.summary = 'A templating system for URIs.'
   s.homepage = 'http://github.com/hannesg/uri_template'
-  s.description = 'A templating system for URIs, which implements RFC 6570: http://tools.ietf.org/html/rfc6570. An implementation of an older version of that spec is known as addressable. This gem however is intended to be extended when newer specs evolve. For now only draft 7 and a simple colon based format are supported.'
+  s.description = 'A templating system for URIs, which implements RFC6570 and Colon based URITemplates in a clean and straight forward way.'
   
   s.require_paths = ['lib']
   
-  s.files = Dir.glob('lib/**/**/*.rb') + ['uri_template.gemspec', 'README', 'CHANGELOG']
+  s.files = Dir.glob('lib/**/**/*.rb') + ['uri_template.gemspec', 'README.md', 'CHANGELOG.md']
  
   s.add_development_dependency 'multi_json'
   s.add_development_dependency 'rspec'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri_template
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-06 00:00:00.000000000 Z
+date: 2012-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -91,23 +91,27 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! 'A templating system for URIs, which implements RFC 6570: http://tools.ietf.org/html/rfc6570.
-  An implementation of an older version of that spec is known as addressable. This
-  gem however is intended to be extended when newer specs evolve. For now only draft
-  7 and a simple colon based format are supported.'
+description: A templating system for URIs, which implements RFC6570 and Colon based
+  URITemplates in a clean and straight forward way.
 email: hannes.georg@googlemail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/uri_template/utils.rb
+- lib/uri_template/rfc6570/expression.rb
+- lib/uri_template/rfc6570/regex_builder.rb
+- lib/uri_template/rfc6570/expression/named.rb
+- lib/uri_template/rfc6570/expression/unnamed.rb
 - lib/uri_template/colon.rb
+- lib/uri_template/literal.rb
+- lib/uri_template/expression.rb
+- lib/uri_template/utils.rb
 - lib/uri_template/rfc6570.rb
-- lib/uri_template/draft7.rb
+- lib/uri_template/token.rb
 - lib/uri_template.rb
 - uri_template.gemspec
-- README
-- CHANGELOG
+- README.md
+- CHANGELOG.md
 homepage: http://github.com/hannesg/uri_template
 licenses: []
 post_install_message: 

data/CHANGELOG

@@ -1,46 +0,0 @@
-# 0.4.0 - 06.07.2012
-+ expand now accepts symbols as keys
-+ expand now accepts arrays of pairs
-* fixed some testing bugs
-
-# 0.3.0 - 24.05.2012
-+ Implemented the final version. Default implementation is now RFC 6570
-* BUGFIX: variables with terminal dots were allowed
-* BUGFIX: lists of commas were parsed incorrectly
-
-# 0.2.1 - 30.12.2011
-* Compatibility: Works now with MRI 1.8.7 and REE
-
-# 0.2.0 - 03.12.2011
-* Reworked the escaping mechanism
-+ escape_utils can now be used to boost escape/unescape performance
-
-# 0.1.4 - 19.11.2011
-* Compatiblity: Works now with MRI 1.9.3, Rubinius and JRuby
-* Various (significant!) performance improvements
-
-# 0.1.3 - 15.11.2011
-* BUGFIX: Draft7./ now concatenates literals correctly
-* BUGFIX: Draft7.tokens is now public
-
-# 0.1.2 - 10.11.2011
-+ added a new template-type: Colon
-  this should allow (some day) to  rails-like routing tables
-+ made the tokens-method mandatory and added two interfaces for tokens.
-  this allows cross-type features like variable anaylisis
-
-# 0.1.1 -  4.11.2011
-+ added a bunch of useful helper methods
-
-# 0.1.0 -  2.11.2011
-- Removed Sections. They made too many headaches.
-+ Made draft7 template concatenateable. This should replace sections.
-* BUGFIX: multiline uris were matched
-* BUGFIX: variablenames were decoded when this was not appreciated
-
-# 0.0.2 -  1.11.2011
-* BUGFIX: Concatenating empty sections no more leads to catch-all templates, when an emtpy template was appreciated.
-+ The extracted variables now contains the keys :suffix and :prefix if the match didn't consume the whole uri.
-
-# 0.0.1 - 30.10.2011
-Initial version