uri_template 0.4.0 → 0.5.0

data/CHANGELOG.md

@@ -0,0 +1,53 @@
+# 0.5.0 - 23.09.2012
+  - - Removed draft7
+  - - splitted absoulte? method into host? and scheme?
+  - + the URITemplate interface is now much stronger
+  - * code quality _significantly_ improved
+  - + concat method
+
+# 0.4.0 - 06.07.2012
+  - + expand now accepts symbols as keys ( thanks to @peterhellber )
+  - + expand now accepts arrays of pairs ( thanks to @peterhellber )
+  - * 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

data/README.md

@@ -0,0 +1,56 @@
+URITemplate - a uri template library
+========================
+
+[![Build Status](https://secure.travis-ci.org/hannesg/uri_template.png)](http://travis-ci.org/hannesg/uri_template)
+[![Dependency Status](https://gemnasium.com/hannesg/uri_template.png)](https://gemnasium.com/hannesg/uri_template)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/hannesg/uri_template)
+
+With URITemplate you can generate URIs based on simple templates and extract variables from URIs using the same templates. There are currently two syntaxes defined. Namely the one defined in [RFC 6570]( http://tools.ietf.org/html/rfc6570 ) and a colon based syntax, similiar to the one used by sinatra.
+
+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:
+
+    # 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'
+    
+    tpl = URITemplate.new('http://{host}{/segments*}/{file}{.extensions*}')
+    
+    # This will give: http://www.host.com/path/to/a/file.x.y
+    tpl.expand('host'=>'www.host.com','segments'=>['path','to','a'],'file'=>'file','extensions'=>['x','y'])
+    
+    # This will give: { 'host'=>'www.host.com','segments'=>['path','to','a'],'file'=>'file','extensions'=>['x','y']}
+    tpl.extract('http://www.host.com/path/to/a/file.x.y')
+    
+    # If you like colon templates more:
+    tpl2 = URITemplate.new(:colon, '/:x/y')
+    
+    # This will give: {'x' => 'z'}
+    tpl2.extract('/z/y')
+
+
+RFC 6570 Syntax
+--------------------
+
+The syntax defined by [RFC 6570]( http://tools.ietf.org/html/rfc6570 ) is pretty straight forward. Basically anything surrounded by curly brackets is interpreted as variable.
+
+    URITemplate.new('{variable}').expand('variable' => 'value') #=> "value"
+
+The way variables are inserted can be modified using operators. The operator is the first character between the curly brackets. There are seven operators defined `#`, `+`, `;`, `?`, `&`, `/` and `.`. So if you want to create a form-style query do this:
+
+    URITemplate.new('{?variable}').expand('variable' => 'value') #=> "?variable=value"
+
+Benchmarks
+-----------------------
+
+I have assembled one benchmark based on the uritemplate-test examples. You can find them in the "benchmarks" folder. The short result: uri_template is 2-10x faster than addressable on ruby 1.9.3.

data/lib/uri_template/colon.rb

@@ -20,15 +20,45 @@ require 'forwardable'
 require 'uri_template'
 require 'uri_template/utils'
 
-# A colon based template denotes variables with a colon.
-# This template type is realy basic but having just on template type was a bit weird.
 module URITemplate
 
+# A colon based template denotes variables with a colon.
+#
+# This template type is somewhat compatible with sinatra.
+#
+# @example
+#   tpl = URITemplate::Colon.new('/foo/:bar')
+#   tpl.extract('/foo/baz') #=> {'bar'=>'baz'}
+#   tpl.expand('bar'=>'boom') #=> '/foo/boom'
+#
 class Colon
 
   include URITemplate
 
-  VAR = /(?:\{:([a-z]+)\}|:([a-z]+)(?![a-z]))/u
+  VAR = /(?:\{:([a-z]+)\}|:([a-z]+)(?![a-z])|\*)/u
+
+  class InvalidValue < StandardError
+
+    include URITemplate::InvalidValue
+
+    attr_reader :variable, :value
+
+    def initialize(variable, value)
+      @variable = variable
+      @value = value
+      super(generate_message())
+    end
+
+    class SplatIsNotAnArray < self
+    end
+
+  protected
+
+    def generate_message()
+      return "The template variable " + variable.inspect + " cannot expand the given value "+ value.inspect
+    end
+
+  end
 
   class Token
 
@@ -44,11 +74,41 @@ class Colon
       end
 
       def expand(vars)
-        return Utils.escape_url(Utils.object_to_param(vars[@name]))
+        return Utils.escape_url(Utils.object_to_param(vars[name]))
+      end
+
+      def to_r
+        return '([^/]*?)'
+      end
+
+      def to_s
+        return ":#{name}"
+      end
+
+    end
+
+    class Splat < Variable
+
+      SPLAT = 'splat'.freeze
+
+      attr_reader :index
+
+      def initialize(index)
+        @index = index
+        super(SPLAT)
+      end
+
+      def expand(vars)
+        var = vars[name]
+        if Array === var
+          return Utils.escape_uri(Utils.object_to_param(var[index]))
+        else
+          raise InvalidValue::SplatIsNotAnArray.new(name,var)
+        end
       end
 
       def to_r
-        return ['([^/]*?)'].join
+        return '(.+?)'
       end
 
     end
@@ -78,13 +138,13 @@ class Colon
   # Tries to convert the value into a colon-template.
   # @example
   #   URITemplate::Colon.try_convert('/foo/:bar/').pattern #=> '/foo/:bar/'
-  #   URITemplate::Colon.try_convert(URITemplate::Draft7.new('/foo/{bar}/')).pattern #=> '/foo/{:bar}/'
+  #   URITemplate::Colon.try_convert(URITemplate.new(:rfc6570, '/foo/{bar}/')).pattern #=> '/foo/{:bar}/'
   def self.try_convert(x)
     if x.kind_of? String
       return new(x)
     elsif x.kind_of? self
       return x
-    elsif x.kind_of? URITemplate::Draft7 and x.level == 1
+    elsif x.kind_of? URITemplate::RFC6570 and x.level == 1
       return new( x.pattern.gsub(/\{(.*?)\}/u){ "{:#{$1}}" } )
     else
       return nil
@@ -92,6 +152,7 @@ class Colon
   end
 
   def initialize(pattern)
+    raise ArgumentError,"Expected a String but got #{pattern.inspect}" unless pattern.kind_of? String
     @pattern = pattern
   end
 
@@ -102,9 +163,20 @@ class Colon
   def extract(uri)
     md = self.to_r.match(uri)
     return nil unless md
-    return Hash[ *self.variables.each_with_index.map{|v,i|
-      [v, Utils.unescape_url(md[i+1])]
-    }.flatten(1) ]
+    result = {}
+    splat = []
+    self.tokens.select{|tk| tk.kind_of? URITemplate::Expression }.each_with_index do |tk,i|
+      if tk.kind_of? Token::Splat
+        splat << md[i+1]
+        result['splat'] = splat unless result.key? 'splat'
+      else
+        result[tk.name] = Utils.unescape_url( md[i+1] )
+      end
+    end
+    if block_given?
+      return yield(result)
+    end
+    return result
   end
 
   def type
@@ -119,30 +191,17 @@ class Colon
     @tokens ||= tokenize!
   end
 
-  # Tries to concatenate two templates, as if they were path segments.
-  # Removes double slashes or inserts one if they are missing.
-  #
-  # @example
-  #   tpl = URITemplate::Colon.new('/xy/')
-  #   (tpl / '/z/' ).pattern #=> '/xy/z/'
-  #   (tpl / 'z/' ).pattern #=> '/xy/z/'
-  #   (tpl / ':z' ).pattern #=> '/xy/:z'
-  #   (tpl / ':a' / 'b' ).pattern #=> '/xy/:a/b'
-  #
-  def /(o)
-    this, other, this_converted, other_converted = URITemplate.coerce( self, o )
-    if this_converted
-      return this / other
-    end
-    return self.class.new( File.join( this.pattern, other.pattern ) )
-  end
-
 protected
 
   def tokenize!
+    number_of_splats = 0
     RegexpEnumerator.new(VAR).each(@pattern).map{|x|
       if x.kind_of? String
-        Token::Static.new(x)
+        Token::Static.new(Utils.escape_uri(x))
+      elsif x[0] == '*'
+        n = number_of_splats
+        number_of_splats = number_of_splats + 1
+        Token::Splat.new(n)
       else
         # TODO: when rubinius supports ambigious names this could be replaced with x['name'] *sigh*
         Token::Variable.new(x[1] || x[2])

data/lib/uri_template/expression.rb

@@ -0,0 +1,33 @@
+# -*- 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
+#
+
+# A module which all non-literal tokens should include.
+module URITemplate::Expression
+
+  include URITemplate::Token
+
+  attr_reader :variables
+
+  def literal?
+    false
+  end
+
+  def expression?
+    true
+  end
+
+end

data/lib/uri_template/literal.rb

@@ -0,0 +1,53 @@
+# -*- 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
+#
+
+# A module which all literal tokens should include.
+module URITemplate::Literal
+
+  include URITemplate::Token
+
+  SLASH = ?/
+
+  attr_reader :string
+
+  def literal?
+    true
+  end
+
+  def expression?
+    false
+  end
+
+  def size
+    0
+  end
+
+  def expand(_)
+    return string
+  end
+
+  def starts_with_slash?
+    string[0] == SLASH
+  end
+
+  def ends_with_slash?
+    string[-1] == SLASH
+  end
+
+  alias to_s string
+
+end

data/lib/uri_template/rfc6570/expression/named.rb

@@ -0,0 +1,72 @@
+# -*- 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
+#
+
+require 'uri_template/rfc6570'
+
+class URITemplate::RFC6570::Expression::Named < URITemplate::RFC6570::Expression
+
+  alias self_pair pair
+
+  def to_r_source
+    source = regex_builder
+    source.group do
+      source.escaped_prefix
+      first = true
+      @variable_specs.each do | var, expand , max_length |
+        if expand
+          source.capture do
+            source.separated_list(first) do
+              source.character_class('+')\
+                .escaped_pair_connector\
+                .character_class_with_comma(max_length)
+            end
+          end
+        else
+          source.group do
+            source.escaped_separator unless first
+            source << Regexp.escape(var)
+            source.group do
+              source.escaped_pair_connector
+              source.capture do
+                source.character_class_with_comma(max_length)
+              end
+              source << '|' unless self.class::PAIR_IF_EMPTY
+            end
+          end.length('?')
+        end
+        first = false
+      end
+    end.length('?')
+    return source.join
+  end
+
+private
+
+  def extracted_nil
+    self.class::PAIR_IF_EMPTY ? nil : ""
+  end
+
+  def after_expand(name, splitted)
+    result = URITemplate::Utils.pair_array_to_hash2( splitted )
+    if result.size == 1 && result[0][0] == name
+      return result
+    else
+      return [ [ name , result ] ]
+    end
+  end
+
+end

data/lib/uri_template/rfc6570/expression/unnamed.rb

@@ -0,0 +1,76 @@
+# -*- 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
+#
+
+require 'uri_template/rfc6570'
+
+class URITemplate::RFC6570::Expression::Unnamed < URITemplate::RFC6570::Expression
+
+  def self_pair(_, value, max_length = 0,&block)
+    if block
+      ev = value.map(&block).join(self.class::LIST_CONNECTOR) 
+    else
+      ev = escape(value)
+    end
+    cut( ev, max_length ,&block)
+  end
+
+  def to_r_source
+    vs = @variable_specs.size - 1
+    i = 0
+    source = regex_builder
+    source.group do
+      source.escaped_prefix
+      @variable_specs.each do | var, expand , max_length |
+        last = (vs == i)
+        first = (i == 0)
+        if expand
+          source.group(true) do
+            source.separated_list(first) do
+              source.group do
+                source.character_class('+').reluctant
+                source.escaped_pair_connector
+              end.length('?')
+              source.character_class(max_length)
+            end
+          end
+        else
+          source.escaped_separator unless first
+          source.group(true) do
+            if last
+              source.character_class_with_comma(max_length)
+            else
+              source.character_class(max_length)
+            end
+          end
+        end
+        i = i+1
+      end
+    end.length('?')
+    return source.join
+  end
+
+private
+
+  def after_expand(name, splitted)
+    if splitted.none?{|_,b| b }
+      return [ [ name, splitted.map{|a,_| a } ] ]
+    else
+      return [ [ name, splitted ] ]
+    end
+  end
+
+end