uri_template 0.1.1 → 0.1.2

data/CHANGELOG

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

data/lib/uri_template/colon.rb

@@ -0,0 +1,153 @@
+# -*- 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 by Hannes Georg
+#
+
+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
+  
+class Colon
+
+  include URITemplate
+
+  VAR = /(?:\{:(?<name>[a-z]+)\}|:(?<name>[a-z]+)(?![a-z]))/
+
+  class Token
+    
+    class Variable < self
+      
+      include URITemplate::Expression
+      
+      attr_reader :name
+      
+      def initialize(name)
+        @name = name
+        @variables = [name]
+      end
+      
+      def expand(vars)
+        return Utils.pct(vars[@name])
+      end
+      
+      def to_r
+        return ['(?<', name, '>[^/]*?)'].join
+      end
+      
+    end
+    
+    class Static < self
+    
+      include URITemplate::Literal
+      
+      def initialize(str)
+        @string = str
+      end
+      
+      def expand(_)
+        return @string
+      end
+      
+      def to_r
+        return Regexp.escape(@string)
+      end
+    
+    end
+    
+  end
+
+  attr_reader :pattern
+
+  # 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}/'
+  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
+      return new( x.pattern.gsub(/\{(.*?)\}/){ "{:#{$1}}" } )
+    else
+      return nil
+    end
+  end
+
+  def initialize(pattern)
+    @pattern = pattern
+  end
+  
+  # Extracts variables from an uri.
+  #
+  # @param String uri
+  # @return nil,Hash
+  def extract(uri)
+    return self.to_r.match(uri) do |md|
+      Hash[ *self.variables.map{|v|
+        [v, Utils.dpct(md[v])]
+      }.flatten(1) ]
+    end
+  end
+  
+  def type
+    :colon
+  end
+  
+  def to_r
+    @regexp ||= Regexp.new('\A' + tokens.map(&:to_r).join + '\z')
+  end
+  
+  def tokens
+    @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!
+    RegexpEnumerator.new(VAR).each(@pattern).map{|x|
+      if x.kind_of? String
+        Token::Static.new(x)
+      else
+        Token::Variable.new(x['name'])
+      end
+    }.to_a
+  end
+
+end
+end

data/lib/uri_template/draft7.rb

@@ -109,22 +109,18 @@ __REGEXP__
   # @private
   class Literal < Token
   
-    attr_reader :string
-  
+    include URITemplate::Literal
+    
     def initialize(string)
       @string = string
     end
     
-    def size
-      0
-    end
-    
     def level
       1
     end
     
-    def expand(*_)
-      return @string
+    def arity
+      0
     end
     
     def to_r_source(*_)
@@ -139,11 +135,15 @@ __REGEXP__
 
   # @private
   class Expression < Token
+  
+    include URITemplate::Expression
     
     attr_reader :variables, :max_length
     
     def initialize(vars)
-      @variables = vars
+      @variable_specs = vars
+      @variables = vars.map(&:first)
+      @variables.uniq!
     end
     
     PREFIX = ''.freeze
@@ -158,13 +158,9 @@ __REGEXP__
     NAMED = false
     OPERATOR = ''
     
-    def size
-      @variables.size
-    end
-    
     def level
-      if @variables.none?{|_,expand,ml| expand || (ml > 0) }
-        if @variables.size == 1
+      if @variable_specs.none?{|_,expand,ml| expand || (ml > 0) }
+        if @variable_specs.size == 1
           return self.class::BASE_LEVEL
         else
           return 3
@@ -174,9 +170,13 @@ __REGEXP__
       end
     end
     
-    def expand( vars, options )
+    def arity
+      @variable_specs.size
+    end
+    
+    def expand( vars )
       result = []
-      variables.each{| var, expand , max_length |
+      @variable_specs.each{| var, expand , max_length |
         unless vars[var].nil?
           if vars[var].kind_of? Hash
             result.push( *transform_hash(var, vars[var], expand, max_length) )
@@ -199,7 +199,7 @@ __REGEXP__
     end
     
     def to_s
-      '{' + self.class::OPERATOR +  @variables.map{|name,expand,max_length| name +(expand ? '*': '') + (max_length > 0 ? ':'+max_length.to_s : '') }.join(',') + '}'
+      '{' + self.class::OPERATOR +  @variable_specs.map{|name,expand,max_length| name +(expand ? '*': '') + (max_length > 0 ? ':'+max_length.to_s : '') }.join(',') + '}'
     end
     
     #TODO: certain things after a slurpy variable will never get matched. therefore, it's pointless to add expressions for them
@@ -207,10 +207,10 @@ __REGEXP__
     def to_r_source(base_counter = 0)
       source = []
       first = true
-      vs = variables.size - 1
+      vs = @variable_specs.size - 1
       i = 0
       if self.class::NAMED
-        variables.each{| var, expand , max_length |
+        @variable_specs.each{| var, expand , max_length |
           last = (vs == i)
           value = "(?:\\g<#{self.class::CHARACTER_CLASS[:class_name]}>|,)#{(max_length > 0)?'{,'+max_length.to_s+'}':'*'}"
           if expand
@@ -240,7 +240,7 @@ __REGEXP__
           i = i+1
         }
       else
-        variables.each{| var, expand , max_length |
+        @variable_specs.each{| var, expand , max_length |
           last = (vs == i)
           if expand
             # could be list or map, too
@@ -272,12 +272,12 @@ __REGEXP__
     end
     
     def extract(position,matched)
-      name, expand, max_length = @variables[position]
+      name, expand, max_length = @variable_specs[position]
       if matched.nil?
         return [[ name , matched ]]
       end
       if expand
-        ex = self.hash_extractor(max_length)
+        ex = self.class.hash_extractor(max_length)
         rest = matched
         splitted = []
         found_value = false
@@ -310,22 +310,25 @@ __REGEXP__
       
       return [ [ name,  decode( matched ) ] ]
     end
-    
-    def variable_names
-      @variables.collect(&:first)
-    end
      
   protected
     
-    def hash_extractor(max_length)
-      value = "\\g<#{self.class::CHARACTER_CLASS[:class_name]}>#{(max_length > 0)?'{,'+max_length.to_s+'}':'*?'}"
-      
-      pair = "(?<name>\\g<c_vn_>#{Regexp.escape(self.class::PAIR_CONNECTOR)})?(?<value>#{value})"
+    module ClassMethods
       
-      return Regexp.new( CHARACTER_CLASSES[:varname][:class] + "{0}\n" + self.class::CHARACTER_CLASS[:class] + "{0}\n"  + "^#{Regexp.escape(self.class::SEPARATOR)}?" + pair + "(?<rest>$|#{Regexp.escape(self.class::SEPARATOR)}(?!#{Regexp.escape(self.class::SEPARATOR)}))" ,Regexp::EXTENDED)
+      def hash_extractor(max_length)
+        @hash_extractors ||= {}
+        @hash_extractors[max_length] ||= begin
+          value = "\\g<#{self::CHARACTER_CLASS[:class_name]}>#{(max_length > 0)?'{,'+max_length.to_s+'}':'*?'}"
+          pair = "(?<name>\\g<c_vn_>#{Regexp.escape(self::PAIR_CONNECTOR)})?(?<value>#{value})"
+        
+          Regexp.new( CHARACTER_CLASSES[:varname][:class] + "{0}\n" + self::CHARACTER_CLASS[:class] + "{0}\n"  + "^#{Regexp.escape(self::SEPARATOR)}?" + pair + "(?<rest>$|#{Regexp.escape(self::SEPARATOR)}(?!#{Regexp.escape(self::SEPARATOR)}))" ,Regexp::EXTENDED)
+        end
+      end
       
     end
     
+    extend ClassMethods
+    
     def encode(x)
       Utils.pct(Utils.object_to_param(x), self.class::CHARACTER_CLASS[:unencoded])
     end
@@ -544,6 +547,7 @@ __REGEXP__
     #   tpl = URITemplate::Draft7.new('{foo}')
     #   URITemplate::Draft7.try_convert( tpl ) #=> tpl
     #   URITemplate::Draft7.try_convert('{foo}') #=> tpl
+    #   URITemplate::Draft7.try_convert(URITemplate.new(:colon, ':foo')) #=> tpl
     #   # This pattern is invalid, so it wont be parsed:
     #   URITemplate::Draft7.try_convert('{foo') #=> nil
     #
@@ -552,6 +556,14 @@ __REGEXP__
         return x
       elsif x.kind_of? String and valid? x
         return new(x)
+      elsif x.kind_of? URITemplate::Colon
+        return new( x.tokens.map{|tk|
+          if tk.literal?
+            Literal.new(tk.string)
+          else
+            Expression.new([[tk.variables.first, false, 0]])
+          end
+        })
       else
         return nil
       end
@@ -606,6 +618,7 @@ __REGEXP__
     end
   end
   
+  # @method expand(variables = {})
   # Expands the template with the given variables.
   # The expansion should be compatible to uritemplate spec draft 7 ( http://tools.ietf.org/html/draft-gregorio-uritemplate-07 ).
   # @note
@@ -619,31 +632,6 @@ __REGEXP__
   #
   # @param variables Hash
   # @return String
-  def expand(variables = {})
-    tokens.map{|part|
-      part.expand(variables, {})
-    }.join
-  end
-  
-  # Returns an array containing all variables. Repeated variables are ignored, but the order will be kept intact.
-  # @example
-  #   URITemplate::Draft7.new('{foo}{bar}{baz}').variables #=> ['foo','bar','baz']
-  #   URITemplate::Draft7.new('{a}{c}{a}{b}').variables #=> ['c','a','b']
-  #
-  # @return Array
-  def variables
-    @variables ||= begin
-      vars = []
-      tokens.each{|token|
-        if token.respond_to? :variable_names
-          vn = token.variable_names.uniq
-          vars -= vn
-          vars.push(*vn)
-        end
-      }
-      vars
-    end
-  end
   
   # Compiles this template into a regular expression which can be used to test whether a given uri matches this template. This template is also used for {#===}.
   #
@@ -659,7 +647,7 @@ __REGEXP__
     bc = 0
     @regexp ||= Regexp.new(classes.join + '\A' + tokens.map{|part|
       r = part.to_r_source(bc)
-      bc += part.size
+      bc += part.arity
       r
     }.join + '\z' , Regexp::EXTENDED)
   end
@@ -803,7 +791,7 @@ __REGEXP__
     tokens.map(&:level).max
   end
   
-  # Tries to conatenate two templates, as if they were path segments.
+  # Tries to concatenate two templates, as if they were path segments.
   # Removes double slashes or insert one if they are missing.
   #
   # @example
@@ -886,20 +874,6 @@ __REGEXP__
     
     return false
   end
-  
-  # 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.
-  #
-  # @example
-  #   URITemplate::Draft7.new('/xy/').static_characters #=> 4
-  #   URITemplate::Draft7.new('{foo}').static_characters #=> 0
-  #   URITemplate::Draft7.new('a{foo}b').static_characters #=> 2
-  #
-  # @return Numeric
-  def static_characters
-    @static_characters ||= tokens.select{|t| t.kind_of?(Literal) }.map{|t| t.string.size }.inject(0,:+)
-  end
 
 protected
   # @private
@@ -917,7 +891,7 @@ protected
     vars = []
     tokens.each{|part|
       i = 0
-      while i < part.size
+      while i < part.arity
         vars.push(*part.extract(i, matchdata["v#{bc}"]))
         bc += 1
         i += 1

data/lib/uri_template/utils.rb

@@ -17,6 +17,41 @@
 
 module URITemplate
 
+  # An awesome little helper which helps iterating over a string.
+  # Initialize with a regexp and pass a string to :each.
+  # It will yield a string or a MatchData
+  class RegexpEnumerator
+  
+    include Enumerable
+    
+    def initialize(regexp)
+      @regexp = regexp
+    end
+    
+    def each(str)
+      return Enumerator.new(self,:each,str) unless block_given?
+      rest = str
+      loop do
+        m = @regexp.match(rest)
+        if m.nil?
+          yield rest
+          break
+        end
+        yield m.pre_match if m.pre_match.size > 0
+        yield m
+        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
+          break
+        end
+        rest = m.post_match
+      end
+      return self
+    end
+  
+  end
+
   # This error will be raised whenever an object could not be converted to a param string.
   class Unconvertable < StandardError
   

data/lib/uri_template.rb

@@ -18,8 +18,65 @@
 # A base module for all implementations of a uri template.
 module URITemplate
 
+  # 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
+    
+    def expression?
+      true
+    end
+  
+  end
+
   autoload :Utils, 'uri_template/utils'
   autoload :Draft7, 'uri_template/draft7'
+  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.
@@ -27,6 +84,7 @@ module URITemplate
   VERSIONS = {
     :draft7 => :Draft7,
     :default => :Draft7,
+    :colon => :Colon,
     :latest => :Draft7
   }
   
@@ -95,6 +153,7 @@ module URITemplate
   #
   # @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]
   def self.coerce(a,b)
     if a.kind_of? URITemplate
       if a.class == b.class
@@ -140,12 +199,15 @@ module URITemplate
   module Invalid
   end
   
-  # @abstract
   # Expands this uri template with the given variables.
   # The variables should be converted to strings using {Utils#object_to_param}.
   # @raise {Unconvertable} if a variable could not be converted to a string.
-  def expand(variables={})
-    raise "Please implement #expand on #{self.class.inspect}."
+  # @param variables Hash
+  # @return String
+  def expand(variables = {})
+    tokens.map{|part|
+      part.expand(variables)
+    }.join
   end
   
   # @abstract
@@ -153,5 +215,35 @@ module URITemplate
   def type
     raise "Please implement #type on #{self.class.inspect}."
   end
+  
+  # @abstract
+  # Returns the tokens of this templates. Tokens should include either {Static} or {Expression}.
+  def tokens
+    raise "Please implement #tokens on #{self.class.inspect}."
+  end
+  
+  # Returns an array containing all variables. Repeated variables are ignored. The concrete order of the variables may change.
+  # @example
+  #   URITemplate.new('{foo}{bar}{baz}').variables #=> ['foo','bar','baz']
+  #   URITemplate.new('{a}{c}{a}{b}').variables #=> ['a','c','b']
+  #
+  # @return Array
+  def variables
+    @variables ||= tokens.select(&:expression?).map(&:variables).flatten.uniq
+  end
+  
+  # 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.
+  #
+  # @example
+  #   URITemplate.new('/xy/').static_characters #=> 4
+  #   URITemplate.new('{foo}').static_characters #=> 0
+  #   URITemplate.new('a{foo}b').static_characters #=> 2
+  #
+  # @return Numeric
+  def static_characters
+    @static_characters ||= tokens.select(&:literal?).map{|t| t.string.size }.inject(0,:+)
+  end
 
 end

data/uri_template.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = 'uri_template'
-  s.version = '0.1.1'
-  s.date = '2011-11-04'
+  s.version = '0.1.2'
+  s.date = '2011-11-10'
   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.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-04 00:00:00.000000000Z
+date: 2011-11-10 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &17225100 !ruby/object:Gem::Requirement
+  requirement: &14750900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17225100
+  version_requirements: *14750900
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &17224520 !ruby/object:Gem::Requirement
+  requirement: &14750460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *17224520
+  version_requirements: *14750460
 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
@@ -43,6 +43,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/uri_template.rb
+- lib/uri_template/colon.rb
 - lib/uri_template/draft7.rb
 - lib/uri_template/utils.rb
 - uri_template.gemspec