joshbuddy-usher 0.1.0 → 0.1.1

data/Rakefile

@@ -7,7 +7,6 @@ begin
     s.description = s.summary = "A general purpose routing library"
     s.email = "joshbuddy@gmail.com"
     s.homepage = "http://github.com/joshbuddy/usher"
-    s.description = "TODO"
     s.authors = ["Joshua Hull"]
     s.files = FileList["[A-Z]*", "{lib,spec,rails}/**/*"]
     s.add_dependency 'joshbuddy-fuzzy_hash'    

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 1
-:patch: 0
+:patch: 1

data/lib/usher.rb

@@ -1,7 +1,5 @@
 $:.unshift File.dirname(__FILE__)
 
-require 'strscan'
-require 'set'
 require 'usher/node'
 require 'usher/route'
 require 'usher/grapher'
@@ -12,15 +10,24 @@ class Usher
   attr_reader :tree, :named_routes, :route_count, :routes
   
   SymbolArraySorter = proc {|a,b| a.hash <=> b.hash}
-    
+  
+  # Returns whether the route set is empty
+  #   
+  #   set = Usher.new
+  #   set.empty? => true
+  #   set.add_route('/test')
+  #   set.empty? => false
   def empty?
     @route_count.zero?
   end
 
-  def lookup
-    @tree.lookup
-  end
-
+  # Resets the route set back to its initial state
+  #   
+  #   set = Usher.new
+  #   set.add_route('/test')
+  #   set.empty? => false
+  #   set.reset!
+  #   set.empty? => true
   def reset!
     @tree = Node.root(self)
     @named_routes = {}
@@ -30,19 +37,60 @@ class Usher
   end
   alias clear! reset!
   
-  def initialize(mode = :rails)
-    @mode = mode
+  # Creates a route set
+  def initialize
     reset!
   end
 
+  # Adds a route referencable by +name+. Sett add_route for format +path+ and +options+.
+  #   
+  #   set = Usher.new
+  #   set.add_named_route(:test_route, '/test')
   def add_named_route(name, path, options = {})
     add_route(path, options).name(name)
   end
 
+  # Attaches a +route+ to a +name+
+  #   
+  #   set = Usher.new
+  #   route = set.add_route('/test')
+  #   set.name(:test, route)
   def name(name, route)
     @named_routes[name] = route.primary_path
   end
 
+  # Creates a route from +path+ and +options+
+  #  
+  # <tt>+path+</tt>::
+  #    A path consists a mix of dynamic and static parts delimited by <tt>/</tt>
+  # 
+  #    *Dynamic*
+  #
+  #    Dynamic parts are prefixed with either :, *.  :variable matches only one part of the path, whereas *variable can match one or
+  #    more parts. Example:
+  #    <b>/path/:variable/path</b> would match
+  #    
+  #    * /path/test/path
+  #    * /path/something_else/path
+  #    * /path/one_more/path
+  #    
+  #    In the above examples, 'test', 'something_else' and 'one_more' respectively would be bound to the key :variable.
+  #    However, /path/test/one_more/path would not be matched. 
+  #    
+  #    Example:
+  #    <b>/path/*variable/path</b> would match
+  #    
+  #    * /path/one/two/three/path
+  #    * /path/four/five/path
+  #    
+  #    In the above examples, ['one', 'two', 'three'] and ['four', 'five'] respectively would be bound to the key :variable.
+  #    
+  # <tt>+options+</tt>::
+  #    --
+  #    * :transformers - Transforms a variable before it gets to the conditions and requirements. Takes either a +proc+ or a +symbol+. If its a +symbol+, calls the method on the incoming parameter. If its a +proc+, its called with the variable.
+  #    * :requirements - After transformation, tests the condition using ===. If it returns false, it raises an +Usher::ValidationException+
+  #    * :conditions - Accepts any of the following +:protocol+, +:domain+, +:port+, +:query_string+, +:remote_ip+, +:user_agent+, +:referer+ and +:method+. This can be either a +string+ or a +regexp+.
+  #   
   def add_route(path, options = {})
     transformers = options.delete(:transformers) || {}
     conditions = options.delete(:conditions) || {}
@@ -63,6 +111,11 @@ class Usher
     route
   end
 
+  # Recognizes a +request+ and returns +nil+ or an Usher::Route::Path
+  #   
+  #   set = Usher.new
+  #   route = set.add_route('/test')
+  #   set.name(:test, route)
   def recognize(request)
     @tree.find(request)
   end

data/lib/usher/exceptions.rb

@@ -1,4 +1,4 @@
 class Usher
-  class UnrecognizedException < RuntimeError
-  end
+  class UnrecognizedException < RuntimeError; end
+  class ValidationException < RuntimeError; end
 end

data/lib/usher/node.rb

@@ -127,7 +127,7 @@ class Usher
           when Symbol
             part = part.send(t)
           end
-          raise "#{part} does not conform to #{next_part.value.validator}" if next_part.value.validator && (not next_part.value.validator === part)
+          raise ValidationException.new("#{part} does not conform to #{next_part.value.validator}") if next_part.value.validator && (not next_part.value.validator === part)
           case next_part.value.type
           when :*
             params << [next_part.value.name, []]

data/lib/usher/route/splitter.rb

@@ -2,7 +2,7 @@ class Usher
   class Route
     class Splitter
       
-      ScanRegex = /((:|\*||\.:|)[0-9a-z_]+|\/|\(|\))/
+      ScanRegex = /((:|\*||\.:|\.)[0-9a-z_]+|\/|\(|\))/
       UrlScanRegex = /\/|\.?\w+/
       
       attr_reader :paths

data/spec/recognize_spec.rb

@@ -30,6 +30,21 @@ describe "Usher route recognition" do
     target_route.paths.include?(route_set.recognize(build_request({:method => 'get', :path => '/sample', :domain => 'admin.host.com'})).first).should == true
   end
   
+  it "should recognize a format-style variable" do
+    target_route = route_set.add_route('/sample.:format', :controller => 'sample', :action => 'action')
+    route_set.recognize(build_request({:method => 'get', :path => '/sample.html', :domain => 'admin.host.com'})).should == [target_route.paths.first, [[:format , 'html']]]
+  end
+  
+  it "should recognize a format-style literal" do
+    target_route = route_set.add_route(':action.html', :controller => 'sample', :action => 'action')
+    route_set.recognize(build_request({:method => 'get', :path => '/sample.html', :domain => 'admin.host.com'})).should == [target_route.paths.first, [[:action , 'sample']]]
+  end
+  
+  it "should recognize a format-style variable along side another variable" do
+    target_route = route_set.add_route(':action.:format', :controller => 'sample', :action => 'action')
+    route_set.recognize(build_request({:method => 'get', :path => '/sample.html', :domain => 'admin.host.com'})).should == [target_route.paths.first, [[:action , 'sample'], [:format, 'html']]]
+  end
+  
   it "should recognize a specific route when several http-style restrictions are used" do
     target_route_http_admin = route_set.add_route('/sample', :controller => 'sample', :action => 'action', :conditions => {:protocol => 'http', :domain => 'admin.spec.com'})
     target_route_http_www = route_set.add_route('/sample', :controller => 'sample', :action => 'action', :conditions => {:protocol => 'http', :domain => 'www.spec.com'})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: joshbuddy-usher
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Joshua Hull
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-26 00:00:00 -07:00
+date: 2009-03-27 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,7 +22,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-description: TODO
+description: A general purpose routing library
 email: joshbuddy@gmail.com
 executables: []