joshbuddy-usher 0.2.1 → 0.2.2

data/README.rdoc

@@ -16,50 +16,50 @@ Tree-based router library. Useful for (specifically) for Rails and Rack, but pro
 
 From the rdoc:
 
-<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:
-   <tt>/path/:variable/path</tt> would match
-   
-   * <tt>/path/test/path</tt>
-   * <tt>/path/something_else/path</tt>
-   * <tt>/path/one_more/path</tt>
-   
-   In the above examples, 'test', 'something_else' and 'one_more' respectively would be bound to the key <tt>:variable</tt>.
-   However, <tt>/path/test/one_more/path</tt> would not be matched. 
-   
-   Example:
-   <tt>/path/*variable/path</tt> would match
-   
-   * <tt>/path/one/two/three/path</tt>
-   * <tt>/path/four/five/path</tt>
-   
-   In the above examples, ['one', 'two', 'three'] and ['four', 'five'] respectively would be bound to the key :variable.
-
-   *Static*
-   
-   Static parts of literal character sequences. For instance, <tt>/path/something.html</tt> would match only the same path.
-
-   <b>Optional sections</b>
-
-   Sections of a route can be marked as optional by surrounding it with brackets. For instance, in the above static example, <tt>/path/something(.html)</tt> would match both <tt>/path/something</tt> and <tt>/path/something.html</tt>.
-
-   <b>One and only one sections</b>
-
-   Sections of a route can be marked as "one and only one" by surrounding it with brackets and separating parts of the route with pipes. For instance, the path, <tt>/path/something(.xml|.html)</tt> would only match <tt>/path/something.xml</tt> and <tt>/path/something.html</tt>.
-
-<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 <tt>Usher::ValidationException</tt>
-   * :conditions - Accepts any of the following <tt>:protocol</tt>, <tt>:domain</tt>, <tt>:port</tt>, <tt>:query_string</tt>, <tt>:remote_ip</tt>, <tt>:user_agent</tt>, <tt>:referer</tt> and <tt>:method</tt>. This can be either a <tt>string</tt> or a <tt>regexp</tt>.
-   * any other key is interpreted as a requirement for the variable of its name.
+Creates a route from +path+ and +options+
+ 
+=== +path+
+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. 
+
+<b>Example:</b>
+<tt>/path/:variable/path</tt> would match
+
+* <tt>/path/test/path</tt>
+* <tt>/path/something_else/path</tt>
+* <tt>/path/one_more/path</tt>
+
+In the above examples, 'test', 'something_else' and 'one_more' respectively would be bound to the key <tt>:variable</tt>.
+However, <tt>/path/test/one_more/path</tt> would not be matched. 
+
+<b>Example:</b>
+<tt>/path/*variable/path</tt> would match
+
+* <tt>/path/one/two/three/path</tt>
+* <tt>/path/four/five/path</tt>
+
+In the above examples, ['one', 'two', 'three'] and ['four', 'five'] respectively would be bound to the key :variable.
+
+==== Static
+
+Static parts of literal character sequences. For instance, <tt>/path/something.html</tt> would match only the same path.
+
+==== Optional sections
+
+Sections of a route can be marked as optional by surrounding it with brackets. For instance, in the above static example, <tt>/path/something(.html)</tt> would match both <tt>/path/something</tt> and <tt>/path/something.html</tt>.
+
+==== One and only one sections
+
+Sections of a route can be marked as "one and only one" by surrounding it with brackets and separating parts of the route with pipes. For instance, the path, <tt>/path/something(.xml|.html)</tt> would only match <tt>/path/something.xml</tt> and <tt>/path/something.html</tt>.
+
+=== +options+
+* +transformers+ - Transforms a variable before it gets to the 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 <tt>Usher::ValidationException</tt>
+* +conditions+ - Accepts any of the following <tt>:protocol</tt>, <tt>:domain</tt>, <tt>:port</tt>, <tt>:query_string</tt>, <tt>:remote_ip</tt>, <tt>:user_agent</tt>, <tt>:referer</tt> and <tt>:method</tt>. This can be either a <tt>string</tt> or a regular expression.
+* Any other key is interpreted as a requirement for the variable of its name.
 
 == Rails
 

data/VERSION.yml

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

data/lib/usher.rb

@@ -61,50 +61,48 @@ class Usher
 
   # Creates a route from +path+ and +options+
   #  
-  # <tt>+path+</tt>::
-  #    A path consists a mix of dynamic and static parts delimited by <tt>/</tt>
+  # === +path+
+  # A path consists a mix of dynamic and static parts delimited by <tt>/</tt>
   #
-  #    *Dynamic*
+  # ==== Dynamic
+  # Dynamic parts are prefixed with either :, *.  :variable matches only one part of the path, whereas *variable can match one or
+  # more parts. 
   #
-  #    Dynamic parts are prefixed with either :, *.  :variable matches only one part of the path, whereas *variable can match one or
-  #    more parts. 
+  # <b>Example:</b>
+  # <tt>/path/:variable/path</tt> would match
   #
-  #    Example:
-  #    <tt>/path/:variable/path</tt> would match
+  # * <tt>/path/test/path</tt>
+  # * <tt>/path/something_else/path</tt>
+  # * <tt>/path/one_more/path</tt>
   #
-  #    * <tt>/path/test/path</tt>
-  #    * <tt>/path/something_else/path</tt>
-  #    * <tt>/path/one_more/path</tt>
+  # In the above examples, 'test', 'something_else' and 'one_more' respectively would be bound to the key <tt>:variable</tt>.
+  # However, <tt>/path/test/one_more/path</tt> would not be matched. 
   #
-  #    In the above examples, 'test', 'something_else' and 'one_more' respectively would be bound to the key <tt>:variable</tt>.
-  #    However, <tt>/path/test/one_more/path</tt> would not be matched. 
+  # <b>Example:</b>
+  # <tt>/path/*variable/path</tt> would match
   #
-  #    Example:
-  #    <tt>/path/*variable/path</tt> would match
+  # * <tt>/path/one/two/three/path</tt>
+  # * <tt>/path/four/five/path</tt>
   #
-  #    * <tt>/path/one/two/three/path</tt>
-  #    * <tt>/path/four/five/path</tt>
+  # In the above examples, ['one', 'two', 'three'] and ['four', 'five'] respectively would be bound to the key :variable.
   #
-  #    In the above examples, ['one', 'two', 'three'] and ['four', 'five'] respectively would be bound to the key :variable.
+  # ==== Static
   #
-  #    *Static*
+  # Static parts of literal character sequences. For instance, <tt>/path/something.html</tt> would match only the same path.
   #
-  #    Static parts of literal character sequences. For instance, <tt>/path/something.html</tt> would match only the same path.
+  # ==== Optional sections
   #
-  #    <b>Optional sections</b>
+  # Sections of a route can be marked as optional by surrounding it with brackets. For instance, in the above static example, <tt>/path/something(.html)</tt> would match both <tt>/path/something</tt> and <tt>/path/something.html</tt>.
   #
-  #    Sections of a route can be marked as optional by surrounding it with brackets. For instance, in the above static example, <tt>/path/something(.html)</tt> would match both <tt>/path/something</tt> and <tt>/path/something.html</tt>.
+  # ==== One and only one sections
   #
-  #    <b>One and only one sections</b>
+  # Sections of a route can be marked as "one and only one" by surrounding it with brackets and separating parts of the route with pipes. For instance, the path, <tt>/path/something(.xml|.html)</tt> would only match <tt>/path/something.xml</tt> and <tt>/path/something.html</tt>.
   #
-  #    Sections of a route can be marked as "one and only one" by surrounding it with brackets and separating parts of the route with pipes. For instance, the path, <tt>/path/something(.xml|.html)</tt> would only match <tt>/path/something.xml</tt> and <tt>/path/something.html</tt>.
-  #
-  # <tt>+options+</tt>::
-  #    --
-  #    * :transformers - Transforms a variable before it gets to the 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 <tt>Usher::ValidationException</tt>
-  #    * :conditions - Accepts any of the following <tt>:protocol</tt>, <tt>:domain</tt>, <tt>:port</tt>, <tt>:query_string</tt>, <tt>:remote_ip</tt>, <tt>:user_agent</tt>, <tt>:referer</tt> and <tt>:method</tt>. This can be either a <tt>string</tt> or a <tt>regexp</tt>.
-  #    * any other key is interpreted as a requirement for the variable of its name.
+  # === +options+
+  # * +transformers+ - Transforms a variable before it gets to the 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 <tt>Usher::ValidationException</tt>
+  # * +conditions+ - Accepts any of the following <tt>:protocol</tt>, <tt>:domain</tt>, <tt>:port</tt>, <tt>:query_string</tt>, <tt>:remote_ip</tt>, <tt>:user_agent</tt>, <tt>:referer</tt> and <tt>:method</tt>. This can be either a <tt>string</tt> or a regular expression.
+  # * Any other key is interpreted as a requirement for the variable of its name.
   def add_route(path, options = {})
     transformers = options.delete(:transformers) || {}
     conditions = options.delete(:conditions) || {}
@@ -144,14 +142,16 @@ class Usher
     @grapher.find_matching_path(options)
   end
   
-  # Generates a completed URL based on a +route+ or set of +params+
+  # Generates a completed URL based on a +route+ or set of optional +params+
   #   
   #   set = Usher.new
   #   route = set.add_named_route(:test_route, '/:controller/:action')
   #   set.generate_url(nil, {:controller => 'c', :action => 'a'}) == '/c/a' => true
   #   set.generate_url(:test_route, {:controller => 'c', :action => 'a'}) == '/c/a' => true
   #   set.generate_url(route.primary_path, {:controller => 'c', :action => 'a'}) == '/c/a' => true
-  def generate_url(route, params)
+  def generate_url(route, params = {}, options = {})
+    check_variables = options.key?(:check_variables) ? options.delete(:check_variables) : false
+
     path = case route
     when Symbol
       @named_routes[route]
@@ -181,10 +181,13 @@ class Usher
       when Route::Variable
         case p.type
         when :*
-          generated_path << '/' << param_list.shift * '/'
+          param_list.first.each {|dp| p.valid!(dp.to_s) } if check_variables
+          generated_path << '/' << param_list.shift.collect{|dp| dp.to_s} * '/'
         when :'.:'
+          p.valid!(param_list.first.to_s) if check_variables
           (dp = param_list.shift) && generated_path << '.' << dp.to_s
         else
+          p.valid!(param_list.first.to_s) if check_variables
           (dp = param_list.shift) && generated_path << '/' << dp.to_s
         end
       else

data/lib/usher/grapher.rb

@@ -1,3 +1,5 @@
+require 'set'
+
 class Usher
   class Grapher
 

data/lib/usher/interface.rb

@@ -2,17 +2,17 @@ $:.unshift File.dirname(__FILE__)
 
 class Usher
   module Interface
+    autoload :Rails2Interface, 'interface/rails2_interface'
+    autoload :MerbInterface, 'interface/merb_interface'
+    autoload :RackInterface, 'interface/rack_interface'
     
     def self.for(type)
       case type
       when :rails2
-        require 'interface/rails2_interface'
         Rails2Interface.new
       when :merb
-        require 'interface/merb_interface'
         MerbInterface.new
       when :rack
-        require 'interface/rack_interface'
         RackInterface.new
       end
     end

data/lib/usher/route.rb

@@ -9,7 +9,7 @@ class Usher
   class Route
     attr_reader :paths, :original_path, :requirements, :conditions, :params, :primary_path
     
-    def initialize(original_path, router, options = {})
+    def initialize(original_path, router, options = {}) # :nodoc:
       @original_path = original_path
       @router = router
       @requirements = options.delete(:requirements)
@@ -20,7 +20,7 @@ class Usher
     end
     
     
-    # Sets +options+ on a route
+    # Sets +options+ on a route. Returns +self+.
     #   
     #   Request = Struct.new(:path)
     #   set = Usher.new
@@ -32,6 +32,11 @@ class Usher
       self
     end
 
+    # Sets route as referenceable from +name+. Returns +self+.
+    #   
+    #   set = Usher.new
+    #   route = set.add_route('/test').name(:route)
+    #   set.generate_url(:route) => '/test'
     def name(name)
       @router.name(name, self)
     end

data/lib/usher/route/variable.rb

@@ -35,7 +35,7 @@ class Usher
           @validator === val or raise
         end if @validator
       rescue Exception => e
-        raise ValidationException.new(e, "#{val} does not conform to #{@validator}")
+        raise ValidationException.new("#{val} does not conform to #{@validator}, root cause #{e.inspect}")
       end
   
       def ==(o)

data/spec/grapher_spec.rb

@@ -0,0 +1,34 @@
+require 'lib/usher'
+
+route_set = Usher.new
+
+describe "Usher grapher" do
+
+  before(:each) do
+    route_set.reset!
+  end
+
+  it "should find a simple path" do
+    route_set.add_route('/:a/:b/:c')
+    route_set.generate_url(nil, {:a => 'A', :b => 'B', :c => 'C'}).should == '/A/B/C'
+  end
+
+  it "should pick a more specific route" do
+    route_set.add_route('/:a/:b')
+    route_set.add_route('/:a/:b/:c')
+    route_set.generate_url(nil, {:a => 'A', :b => 'B', :c => 'C'}).should == '/A/B/C'
+  end
+
+  it "should find the most specific route and append extra parts on as a query string" do
+    route_set.add_route('/:a/:b/:c')
+    route_set.add_route('/:a/:b')
+    route_set.generate_url(nil, {:a => 'A', :b => 'B', :d => 'C'}).should == '/A/B?d=C'
+  end
+  
+  it "should do a validity check against the incoming variables when asked to" do
+    route_set.add_route('/:a/:b', :b => /\d+/)
+    route_set.generate_url(nil, {:a => 'A', :b => 'B'}).should == '/A/B'
+    proc{ route_set.generate_url(nil, {:a => 'A', :b => 'B'}, :check_variables => true).should == '/A/B?d=C'}.should raise_error Usher::ValidationException
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: joshbuddy-usher
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors: 
 - Joshua Hull
@@ -58,6 +58,7 @@ files:
 - lib/usher/route.rb
 - lib/usher.rb
 - spec/generate_spec.rb
+- spec/grapher_spec.rb
 - spec/path_spec.rb
 - spec/rack
 - spec/rack/dispatch_spec.rb