uri_template 0.1.4 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,7 @@
+# 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

data/README

@@ -6,6 +6,19 @@ It's currently planed to add newer versions of that spec when they emerge. There
 
 Some implementations might be able to extract variables, too ( Draft 7 is! ).
 
+From version 0.2.0, it will use escape_utils if available. This will significantly boost uri-escape/unescape performance if more characters need to be escaped ( may be slightly slower in trivial cases. working on that ... ), but does not run everywhere. To enable this, do the following:
+
+````ruby
+  # escape_utils has to be loaded when uri_templates is loaded
+  gem 'escape_utils'
+  require 'escape_utils'
+  
+  gem 'uri_template'
+  require 'uri_template'
+  
+  UriTemplate::Utils.using_escape_utils? #=> true
+
+
 == Examples
 
   require 'uri_template'

data/lib/uri_template.rb

@@ -149,7 +149,7 @@ module URITemplate
   end
   
   # Tries to coerce two URITemplates into a common representation.
-  # Returns an array with two {URITemplate}s and two booleans indicating which of the two were converted or raises an {ArgumentError}.
+  # 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]
@@ -217,7 +217,7 @@ module URITemplate
   end
   
   # @abstract
-  # Returns the tokens of this templates. Tokens should include either {Static} or {Expression}.
+  # Returns the tokens of this templates. Tokens should include either {Literal} or {Expression}.
   def tokens
     raise "Please implement #tokens on #{self.class.inspect}."
   end
@@ -234,7 +234,7 @@ module URITemplate
   
   # Returns the number of static characters in this template.
   # This method is useful for routing, since it's often pointful to use the url with fewer variable characters.
-  # For example 'static' and 'sta\{var\}' both match 'static', but in most cases 'static' should be prefered over 'sta{var}' since it's more specific.
+  # For example 'static' and 'sta\\{var\\}' both match 'static', but in most cases 'static' should be prefered over 'sta\\{var\\}' since it's more specific.
   #
   # @example
   #   URITemplate.new('/xy/').static_characters #=> 4

data/lib/uri_template/colon.rb

@@ -44,7 +44,7 @@ class Colon
       end
       
       def expand(vars)
-        return Utils.pct(vars[@name])
+        return Utils.escape_url(Utils.object_to_param(vars[@name]))
       end
       
       def to_r
@@ -103,7 +103,7 @@ class Colon
     md = self.to_r.match(uri)
     return nil unless md
     return Hash[ *self.variables.each_with_index.map{|v,i|
-      [v, Utils.dpct(md[i+1])]
+      [v, Utils.unescape_url(md[i+1])]
     }.flatten(1) ]
   end
   

data/lib/uri_template/draft7.rb

@@ -178,7 +178,7 @@ __REGEXP__
             if self.class::NAMED
               result.push( pair(var, vars[var], max_length) )
             else
-              result.push( cut( encode(vars[var]), max_length ) )
+              result.push( cut( escape(vars[var]), max_length ) )
             end
           end
         end
@@ -203,7 +203,6 @@ __REGEXP__
       i = 0
       if self.class::NAMED
         @variable_specs.each{| var, expand , max_length |
-          last = (vs == i)
           value = "(?:#{self.class::CHARACTER_CLASS[:class]}|,)#{(max_length > 0)?'{,'+max_length.to_s+'}':'*'}"
           if expand
             #if self.class::PAIR_IF_EMPTY
@@ -269,6 +268,7 @@ __REGEXP__
         return [[ name , matched ]]
       end
       if expand
+        #TODO: do we really need this? - this could be stolen from rack
         ex = self.class.hash_extractor(max_length)
         rest = matched
         splitted = []
@@ -324,8 +324,12 @@ __REGEXP__
     
     extend ClassMethods
     
-    def encode(x)
-      Utils.pct(Utils.object_to_param(x), self.class::CHARACTER_CLASS[:unencoded])
+    def escape(x)
+      Utils.escape_url(Utils.object_to_param(x))
+    end
+    
+    def unescape(x)
+      Utils.unescape_url(x)
     end
     
     SPLITTER = /^(?:,(,*)|([^,]+))/
@@ -345,7 +349,7 @@ __REGEXP__
           if m[1] and m[1].size > 0
             r << m[1]
           elsif m[2]
-            r << Utils.dpct(m[2])
+            r << unescape(m[2])
           end
           v = m.post_match
         end
@@ -355,7 +359,7 @@ __REGEXP__
           else r
         end
       else
-        Utils.dpct(x)
+        unescape(x)
       end
     end
     
@@ -370,8 +374,8 @@ __REGEXP__
     end
     
     def pair(key, value, max_length = 0)
-      ek = encode(key)
-      ev = encode(value)
+      ek = escape(key)
+      ev = escape(value)
       if !self.class::PAIR_IF_EMPTY and ev.size == 0
         return ek
       else
@@ -385,17 +389,17 @@ __REGEXP__
       elsif hsh.none?
         []
       else
-        [ (self.class::NAMED ? encode(name)+self.class::PAIR_CONNECTOR : '' ) + hsh.map{|key,value| encode(key)+self.class::LIST_CONNECTOR+encode(value) }.join(self.class::LIST_CONNECTOR) ]
+        [ (self.class::NAMED ? escape(name)+self.class::PAIR_CONNECTOR : '' ) + hsh.map{|key,value| escape(key)+self.class::LIST_CONNECTOR+escape(value) }.join(self.class::LIST_CONNECTOR) ]
       end
     end
     
     def transform_array(name, ary, expand , max_length)
       if expand
-        ary.map{|value| encode(value) }
+        ary.map{|value| escape(value) }
       elsif ary.none?
         []
       else
-        [ (self.class::NAMED ? encode(name)+self.class::PAIR_CONNECTOR : '' ) + ary.map{|value| encode(value) }.join(self.class::LIST_CONNECTOR) ]
+        [ (self.class::NAMED ? escape(name)+self.class::PAIR_CONNECTOR : '' ) + ary.map{|value| escape(value) }.join(self.class::LIST_CONNECTOR) ]
       end
     end
     
@@ -404,6 +408,14 @@ __REGEXP__
       CHARACTER_CLASS = CHARACTER_CLASSES[:unreserved_reserved_pct]
       OPERATOR = '+'.freeze
       BASE_LEVEL = 2
+      
+      def escape(x)
+        Utils.escape_uri(Utils.object_to_param(x))
+      end
+      
+      def unescape(x)
+        Utils.unescape_uri(x)
+      end
     
     end
     
@@ -413,6 +425,14 @@ __REGEXP__
       PREFIX = '#'.freeze
       OPERATOR = '#'.freeze
       BASE_LEVEL = 2
+      
+      def escape(x)
+        Utils.escape_uri(Utils.object_to_param(x))
+      end
+      
+      def unescape(x)
+        Utils.unescape_uri(x)
+      end
     
     end
     
@@ -593,8 +613,6 @@ __REGEXP__
   
   extend ClassMethods
   
-  attr_reader :pattern
-  
   attr_reader :options
   
   # @param String,Array either a pattern as String or an Array of tokens
@@ -642,8 +660,6 @@ __REGEXP__
   # @return Regexp
   def to_r
     @regexp ||= begin
-      #classes = CHARACTER_CLASSES.map{|_,v| v[:class]+"{0}\n" }
-      bc = 0
       source = tokens.map(&:to_r_source)
       source.unshift('\A')
       source.push('\z')
@@ -729,7 +745,7 @@ __REGEXP__
   
   # Compares two template patterns.
   def ==(o)
-    this, other, this_converted, other_converted = URITemplate.coerce( self, o )
+    this, other, this_converted, _ = URITemplate.coerce( self, o )
     if this_converted
       return this == other
     end
@@ -793,7 +809,7 @@ __REGEXP__
   #   (tpl / 'a' / 'b' ).pattern #=> '/xy/a/b'
   #
   def /(o)
-    this, other, this_converted, other_converted = URITemplate.coerce( self, o )
+    this, other, this_converted, _ = URITemplate.coerce( self, o )
     if this_converted
       return this / other
     end

data/lib/uri_template/utils.rb

@@ -64,81 +64,156 @@ module URITemplate
   
   end
 
-  # A collection of some utility methods
+  # A collection of some utility methods.
+  # The most methods are used to parse or generate uri-parameters.
+  # I will use the escape_utils library if available, but runs happily without.
+  #
   module Utils
   
     KCODE_UTF8 = (Regexp::KCODE_UTF8 rescue 0)
-  
-    # @private
-    PCT = /%(\h\h)/.freeze
     
-    # A regexp which match all non-simple characters.
-    NOT_SIMPLE_CHARS = /([^A-Za-z0-9\-\._])/.freeze
+    # Bundles some string encoding methods.
+    module StringEncoding
+      
+      # @method to_ascii(string)
+      # converts a string to ascii
+      # 
+      # This method checks which encoding method is available.
+      # @param String
+      # @return String
+      # @visibility public
+      def to_ascii_encode(str)
+        str.encode(Encoding::ASCII)
+      end
+      
+      # @method to_utf8(string)
+      # converts a string to utf8
+      # 
+      # This method checks which encoding method is available.
+      # @param String
+      # @return String
+      # @visibility public
+      def to_utf8_encode(str)
+        str.encode(Encoding::UTF_8)
+      end
+      
+      def to_ascii_fallback(str)
+        str
+      end
+      
+      def to_utf8_fallback(str)
+        str
+      end
+      
+      if "".respond_to?(:encode)
+        # @private
+        alias_method :to_ascii, :to_ascii_encode
+        # @private
+        alias_method :to_utf8, :to_utf8_encode
+      else
+        # @private
+        alias_method :to_ascii, :to_ascii_fallback
+        # @private
+        alias_method :to_utf8, :to_utf8_fallback
+      end
+      
+      public :to_ascii
+      public :to_utf8
+      
+    end
     
-    ASCII = 'ASCII'.freeze
-    UTF8 = 'UTF-8'.freeze
+    module Escaping
     
-    def to_ascii_force_encoding(str)
-      str.force_encoding(ASCII)
-    end
+      # A pure escaping module, which implements escaping methods in pure ruby.
+      # The performance is acceptable, but could be better with escape_utils.
+      module Pure
     
-    def to_utf8_force_encoding(str)
-      str.force_encoding(UTF8)
-    end
+        include StringEncoding
     
-    def to_ascii_encode(str)
-      str.encode(ASCII)
-    end
+        # @private
+        URL_ESCAPED = /([^A-Za-z0-9\-\._])/.freeze
+        
+        # @private
+        URI_ESCAPED = /([^A-Za-z0-9!$&'()*+,.\/:;=?@\[\]_~])/.freeze
+        
+        # @private
+        PCT = /%(\h\h)/.freeze
+        
+        def escape_url(s)
+          to_utf8(s.to_s).gsub(URL_ESCAPED){
+            '%'+$1.unpack('H2'*$1.bytesize).join('%').upcase
+          }
+        end
+        
+        def escape_uri(s)
+          to_utf8(s.to_s).gsub(URI_ESCAPED){
+            '%'+$1.unpack('H2'*$1.bytesize).join('%').upcase
+          }
+        end
+        
+        def unescape_url(s)
+          to_utf8( s.to_s.gsub('+',' ').gsub(PCT){
+            $1.to_i(16).chr
+          } )
+        end
+        
+        def unescape_uri(s)
+          to_utf8( s.to_s.gsub(PCT){
+            $1.to_i(16).chr
+          })
+        end
+        
+        def using_escape_utils?
+          false
+        end
+        
+      end
+      
+    if defined? EscapeUtils
+      
+      # A escaping module, which is backed by escape_utils.
+      # The performance is good, espacially for strings with many escaped characters.
+      module EscapeUtils
+      
+        include StringEncoding
+      
+        include ::EscapeUtils
     
-    def to_utf8_encode(str)
-      str.encode(UTF8)
-    end
+        def using_escape_utils?
+          true
+        end
+        
+        def escape_url(s)
+          super(to_utf8(s)).gsub('+','%20')
+        end
+        
+        def escape_uri(s)
+          super(to_utf8(s))
+        end
+        
+        def unescape_url(s)
+          super(to_ascii(s))
+        end
+        
+        def unescape_uri(s)
+          super(to_ascii(s))
+        end
+      
+      end
     
-    def to_ascii_fallback(str)
-      str
     end
     
-    def to_utf8_fallback(str)
-      str
-    end
     
-    if "".respond_to?(:force_encoding)
-      alias_method :to_ascii, :to_ascii_force_encoding
-      alias_method :to_utf8, :to_utf8_force_encoding
-    elsif "".respond_to?(:encode)
-      alias_method :to_ascii, :to_ascii_encode
-      alias_method :to_utf8, :to_utf8_encode
-    else
-      alias_method :to_ascii, :to_ascii_fallback
-      alias_method :to_utf8, :to_utf8_fallback
     end
     
-    # Encodes the given string into a pct-encoded string.
-    # @param s The string to be encoded.
-    # @param m A regexp matching all characters, which need to be encoded.
-    #
-    # @example
-    #   URITemplate::Utils.pct("abc") #=> "abc"
-    #   URITemplate::Utils.pct("%") #=> "%25"
-    #
-    #TODO: is encoding as utf8/ascii really needed?
-    def pct(s, m=NOT_SIMPLE_CHARS)
-      to_ascii( s.to_s.gsub(m){
-        '%'+$1.unpack('H2'*$1.bytesize).join('%').upcase
-      } )
-    end
+    include StringEncoding
     
-    # Decodes the given pct-encoded string into a utf-8 string.
-    # Should be the opposite of #pct.
-    #
-    # @example
-    #   URITemplate::Utils.dpct("abc") #=> "abc"
-    #   URITemplate::Utils.dpct("%25") #=> "%"
-    #
-    def dpct(s)
-      to_utf8(s.to_s.gsub(PCT){
-        $1.to_i(16).chr
-      })
+    if Escaping.const_defined? :EscapeUtils
+      include Escaping::EscapeUtils
+      puts "Using escape_utils." if $VERBOSE
+    else
+      include Escaping::Pure
+      puts "Not using escape_utils." if $VERBOSE
     end
     
     # Converts an object to a param value.

data/uri_template.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = 'uri_template'
-  s.version = '0.1.4'
-  s.date = '2011-11-19'
+  s.version = '0.2.0'
+  s.date = '2011-12-03'
   s.authors = ["HannesG"]
   s.email = %q{hannes.georg@googlemail.com}
   s.summary = 'A templating system for URIs.'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri_template
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-19 00:00:00.000000000Z
+date: 2011-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &16477840 !ruby/object:Gem::Requirement
+  requirement: &17186480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *16477840
+  version_requirements: *17186480
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &16477400 !ruby/object:Gem::Requirement
+  requirement: &17185740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *16477400
+  version_requirements: *17185740
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &16476980 !ruby/object:Gem::Requirement
+  requirement: &17184760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *16476980
+  version_requirements: *17184760
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &16476560 !ruby/object:Gem::Requirement
+  requirement: &17195720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *16476560
+  version_requirements: *17195720
 description: ! 'A templating system for URIs, which implements http://tools.ietf.org/html/draft-gregorio-uritemplate-07
   . 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