http_router 0.1.4 → 0.1.5

data/README.rdoc

@@ -15,12 +15,12 @@ This is very new code. Lots of stuff probably doesn't work right. I will likely
 * Request condition support.
 * Partial matches.
 * Supports interstitial variables (e.g. /my-:variable-brings.all.the.boys/yard).
-* Very fast and small code base (~600 loc).
+* Very fast and small code base (~1,000 loc).
 * Sinatra compatibility.
 
 == Usage
 
-Please see the examples directory for a bunch of awesome rackup file examples, with tonnes of commentary.
+Please see the examples directory for a bunch of awesome rackup file examples, with tonnes of commentary. As well, the rdocs should provide a lot of useful specifics and exact usage.
 
 === <tt>HttpRouter.new</tt>
 
@@ -29,6 +29,7 @@ Takes the following options:
 * <tt>:default_app</tt> - The default #call made on non-matches. Defaults to a 404 generator.
 * <tt>:ignore_trailing_slash</tt> - Ignores the trailing slash when matching. Defaults to true.
 * <tt>:redirect_trailing_slash</tt> - Redirect on trailing slash matches to non-trailing slash paths. Defaults to false.
+* <tt>:middleware</tt> - Perform matching without deferring to matched route. Defaults to false.
 
 === <tt>#add(name, options)</tt>
 

data/Rakefile

@@ -15,3 +15,11 @@ begin
   CodeStats::Tasks.new
 rescue LoadError
 end
+
+require 'rake/rdoctask'
+desc "Generate documentation"
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'rdoc'
+end

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/examples/middleware.ru

@@ -0,0 +1,46 @@
+require 'http_router'
+
+use(HttpRouter, :middleware => true) {
+  add('/test').name(:test)
+  add('/:variable').name(:var)
+  add('/more/*glob').name(:glob)
+  add('/get/:id').matching(:id => /\d+/).name(:get)
+}
+
+run proc {|env|
+  [
+    200,
+    {'Content-type' => 'text/plain'},
+    [<<-HEREDOC
+We matched? #{env['router.response'] && env['router.response'].matched? ? 'yes!' : 'no'}      
+Params are #{env['router.response'] && env['router.response'].matched? ? env['router.response'].params_as_hash.inspect : 'we had no params'}
+That was fun
+    HEREDOC
+    ]
+  ]
+}
+
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/hi
+# We matched? yes!      
+# Params are {:variable=>"hi"}
+# That was fun
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/test
+# We matched? yes!      
+# Params are {}
+# That was fun
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/hey
+# We matched? yes!      
+# Params are {:variable=>"hey"}
+# That was fun
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/more/fun/in/the/sun
+# We matched? yes!      
+# Params are {:glob=>["fun", "in", "the", "sun"]}
+# That was fun
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/get/what
+# We matched? no      
+# Params are we had no params
+# That was fun
+# crapbook-pro:polleverywhere joshua$ curl http://127.0.0.1:3000/get/123
+# We matched? yes!      
+# Params are {:id=>"123"}
+# That was fun

data/examples/rack_mapper.ru

@@ -0,0 +1,22 @@
+require 'http_router'
+HttpRouter.override_rack_mapper!
+
+map('/get/:id') { |env|
+  [200, {'Content-type' => 'text/plain'}, ["My id is #{env['router.params'][:id]}\n"]]
+}
+
+# you have post, get, head, put and delete.
+post('/get/:id') { |env|
+  [200, {'Content-type' => 'text/plain'}, ["My id is #{env['router.params'][:id]} and you posted!\n"]]
+}
+
+map('/get/:id', :matching => {:id => /\d+/}) { |env|
+  [200, {'Content-type' => 'text/plain'}, ["My id is #{env['router.params'][:id]}, which is a number\n"]]
+}
+
+# crapbook-pro:~ joshua$ curl http://127.0.0.1:3000/get/foo
+# My id is foo
+# crapbook-pro:~ joshua$ curl -X POST http://127.0.0.1:3000/get/foo
+# My id is foo and you posted!
+# crapbook-pro:~ joshua$ curl -X POST http://127.0.0.1:3000/get/123
+# My id is 123, which is a number

data/lib/http_router/glob.rb

@@ -1,12 +1,13 @@
 class HttpRouter
   class Glob < Variable
-    def matches(env, parts, whole_path)
-      if @matches_with && match = @matches_with.match(parts.first)
+    def matches?(parts, whole_path)
+      @matches_with.nil? or (!parts.empty? and match = @matches_with.match(parts.first) and match.begin(0))
+    end
+
+    def consume(parts, whole_path)
+      if @matches_with
         params = [parts.shift]
-        while !parts.empty? and match = @matches_with.match(parts.first)
-          params << parts.shift
-        end
-        whole_path.replace(parts.join('/'))
+        params << parts.shift while matches?(parts, whole_path)
         params
       else
         params = parts.dup

data/lib/http_router/node.rb

@@ -3,19 +3,17 @@ class HttpRouter
     attr_accessor :value, :variable, :catchall
     attr_reader :linear, :lookup, :request_node, :arbitrary_node
 
-    def initialize(base)
-      @router = base
+    def initialize(router)
+      @router = router
       reset!
     end
 
     def reset!
-      @linear = nil
-      @lookup = nil
-      @catchall = nil
+      @linear, @lookup, @catchall = nil, nil, nil
     end
 
     def add(val)
-      if val.is_a?(Variable)
+      if val.respond_to?(:matches?)
         if val.matches_with
           add_to_linear(val)
         else
@@ -140,31 +138,30 @@ class HttpRouter
     end
 
     def find_on_parts(request, parts, params)
-      if !parts.empty?
+      unless parts.empty?
+        whole_path = parts.join('/')
         if @linear && !@linear.empty?
-          whole_path = parts.join('/')
+          response = nil
+          dupped_parts = nil
           next_node = @linear.find do |(tester, node)|
-            if tester.is_a?(Regexp) and match = tester.match(whole_path) #and match.index == 0 TODO
-              whole_path.slice!(0,match[0].size)
-              parts.replace(router.split(whole_path))
-              node
-            elsif tester.respond_to?(:matches) and new_params = tester.matches(request.env, parts, whole_path)
-              params << new_params
-              node
+            if tester.respond_to?(:matches?) and tester.matches?(parts, whole_path)
+              dupped_parts = parts.dup
+              params << tester.consume(dupped_parts, whole_path)
+              parts.replace(dupped_parts) if response = node.find_on_parts(request, dupped_parts, params)
+            elsif tester.respond_to?(:match) and match = tester.match(whole_path) and match.begin(0) == 0
+              dupped_parts = router.split(whole_path[match[0].size, whole_path.size])
+              parts.replace(dupped_parts) if response = node.find_on_parts(request, dupped_parts, params)
             else
               nil
             end
           end
-          if next_node and match = next_node.last.find_on_parts(request, parts, params)
-            return match
-          end
+          return response if response
         end
         if match = @lookup && @lookup[parts.first]
           parts.shift
           return match.find_on_parts(request, parts, params)
         elsif @catchall
-          params << @catchall.variable.matches(request.env, parts, whole_path)
-          parts.shift
+          params << @catchall.variable.consume(parts, whole_path)
           return @catchall.find_on_parts(request, parts, params)
         elsif parts.size == 1 && parts.first == '' && (value && value.route.trailing_slash_ignore? || router.ignore_trailing_slash?)
           parts.shift

data/lib/http_router/optional_compiler.rb

@@ -0,0 +1,35 @@
+class HttpRouter
+  class OptionalCompiler
+    attr_reader :paths
+    def initialize(path)
+      @start_index = 0
+      @end_index = 1
+      @paths = [""]
+      @chars = path.chars.to_a
+      while !@chars.empty?
+        case @chars.first
+          when '('  then @chars.shift and double_paths
+          when ')'  then @chars.shift and half_paths
+          when '\\' then @chars.shift and add_to_current_set(@chars.shift)
+          else           add_to_current_set(@chars.shift)
+        end
+      end
+      @paths
+    end
+    
+    def add_to_current_set(c)
+      (@start_index...@end_index).each { |path_index| @paths[path_index] << c }
+    end
+    
+    # over current working set, double @paths
+    def double_paths 
+      (@start_index...@end_index).each { |path_index| @paths << @paths[path_index].dup }
+      @start_index = @end_index
+      @end_index = @paths.size
+    end
+
+    def half_paths
+      @start_index -= @end_index - @start_index
+    end
+  end
+end

data/lib/http_router/path.rb

@@ -1,14 +1,23 @@
 require 'cgi'
 class HttpRouter
   class Path
-    attr_reader :parts
-    attr_accessor :route
-    def initialize(path, parts)
-      @path, @parts = path, parts
+    attr_reader :parts, :route
+    def initialize(route, path, parts)
+      @route, @path, @parts = route, path, parts
       if duplicate_variable_names = variable_names.dup.uniq!
         raise AmbiguousVariableException.new("You have duplicate variable name present: #{duplicate_variable_names.join(', ')}")
       end
 
+      @path_validation_regex = path.split(/([:\*][a-zA-Z0-9_]+)/).map{ |part|
+        case part[0]
+        when ?:, ?*
+          route.matches_with[part[1, part.size].to_sym] || '.*?' 
+        else
+          Regexp.quote(part)
+        end
+      }.join
+      @path_validation_regex = Regexp.new("^#{@path_validation_regex}$")
+
       eval_path = path.gsub(/[:\*]([a-zA-Z0-9_]+)/) {"\#{args.shift || (options && options.delete(:#{$1})) || raise(MissingParameterException.new(\"missing parameter #{$1}\"))}" }
       instance_eval "
       def raw_url(args,options)
@@ -36,6 +45,7 @@ class HttpRouter
 
     def url(args, options)
       path = raw_url(args, options)
+      raise InvalidRouteException.new if path !~ @path_validation_regex
       raise TooManyParametersException.new unless args.empty?
       Rack::Utils.uri_escape!(path)
       generate_querystring(path, options)

data/lib/http_router/route.rb

@@ -1,10 +1,11 @@
 class HttpRouter
   class Route
-    attr_reader :dest, :paths
-    attr_accessor :trailing_slash_ignore, :partially_match, :default_values, :router
+    attr_reader :dest, :paths, :path, :matches_with
+    attr_accessor :trailing_slash_ignore, :partially_match, :default_values
 
-    def initialize(base, path)
-      @router = base
+    def initialize(router, path)
+      @router = router
+      path[0,0] = '/' unless path[0] == ?/
       @path = path
       @original_path = path.dup
       @partially_match = extract_partial_match(path)
@@ -15,15 +16,6 @@ class HttpRouter
       @default_values = {}
     end
 
-    def significant_variable_names
-      unless @significant_variable_names
-        @significant_variable_names = @paths.map { |p| p.variable_names }
-        @significant_variable_names.flatten!
-        @significant_variable_names.uniq!
-      end
-      @significant_variable_names
-    end
-
     def method_missing(method, *args, &block)
       if RequestNode::RequestMethods.include?(method)
         condition(method => args)
@@ -32,54 +24,89 @@ class HttpRouter
       end
     end
 
+    # Returns the options used to create this route.
+    def as_options
+      {:matching => @matches_with, :conditions => @conditions, :default_values => @default_values, :name => @name}
+    end
+
+    # Creates a deep uncompiled copy of this route.
+    def clone
+      Route.new(@router, @original_path.dup).with_options(as_options)
+    end
+
+    # Uses an option hash to apply conditions to a Route.
+    # The following keys are supported.
+    # *name -- Maps to #name method.
+    # *matching -- Maps to #matching method.
+    # *conditions -- Maps to #conditions method.
+    # *default_value -- Maps to #default_value method.
     def with_options(options)
-      if options && options[:matching]
-        default(options[:matching])
-      end
-      if options && options[:conditions]
-        condition(options[:conditions])
-      end
-      if options && options[:default_values]
-        default(options[:default_values])
-      end
+      name(options[:name]) if options && options[:name]
+      matching(options[:matching]) if options && options[:matching]
+      condition(options[:conditions]) if options && options[:conditions]
+      default(options[:default_values]) if options && options[:default_values]
       self
     end
 
+    # Sets the name of the route
+    # Returns +self+.
     def name(name)
       @name = name
       router.named_routes[@name] = self if @name && compiled?
       self
     end
 
+    # Sets a default value for the route
+    # Returns +self+.
+    #
+    # Example
+    #   router = HttpRouter.new
+    #   router.add("/:test").default(:test => 'foo').name(:test).compile
+    #   router.url(:test)
+    #   # ==> "/foo"
+    #   router.url(:test, 'override')
+    #   # ==> "/override"
     def default(v)
       @default_values.merge!(v)
       self
     end
 
+    # Causes this route to recognize the GET and HEAD request methods. Returns +self+.
     def get
       request_method('GET', 'HEAD')
     end
     
+    # Causes this route to recognize the POST request method. Returns +self+.
     def post
       request_method('POST')
     end
     
+    # Causes this route to recognize the HEAD request method. Returns +self+.
     def head
       request_method('HEAD')
     end
     
+    # Causes this route to recognize the PUT request method. Returns +self+.
     def put
       request_method('PUT')
     end
     
+    # Causes this route to recognize the DELETE request method. Returns +self+.
     def delete
       request_method('DELETE')
     end
     
+    # Causes this route to recognize the GET request method. Returns +self+.
     def only_get
-      request_method('DELETE')
+      request_method('GET')
     end
       
+    # Sets a request condition for the route
+    # Returns +self+.
+    #
+    # Example
+    #   router = HttpRouter.new
+    #   router.add("/:test").condition(:host => 'www.example.org').name(:test).compile
     def condition(conditions)
       guard_compiled
       conditions.each do |k,v|
@@ -91,45 +118,63 @@ class HttpRouter
     end
     alias_method :conditions, :condition
 
+    # Sets a regex matcher for a variable
+    # Returns +self+.
+    #
+    # Example
+    #   router = HttpRouter.new
+    #   router.add("/:test").matching(:test => /\d+/).name(:test).compile
     def matching(match)
       guard_compiled
       match.each do |var_name, matchers|
         matchers = Array(matchers)
         matchers.each do |m|
-          @matches_with.key?(var_name) ?
-            raise :
-            @matches_with[var_name] = m
+          @matches_with.key?(var_name) ? raise : @matches_with[var_name] = m
         end
       end
       self
     end
 
+    # Returns the current route's name.
     def named
       @name
     end
 
+    # Sets the destination of the route. Receives either a block, or a proc.
+    # Returns +self+.
+    #
+    # Example
+    #   router = HttpRouter.new
+    #   router.add("/:test").matching(:test => /\d+/).name(:test).to(proc{ |env| Rack::Response.new("hi there").finish })
+    # Or
+    #   router.add("/:test").matching(:test => /\d+/).name(:test).to { |env| Rack::Response.new("hi there").finish }
     def to(dest = nil, &block)
       compile
       @dest = dest || block
       self
     end
 
+    # Sets partial matching on this route. Defaults to +true+. Returns +self+.
     def partial(match = true)
       @partially_match = match
       self
     end
 
+    # Adds an arbitrary proc matcher to a Route. Receives either a block, or a proc. The proc will receive a Rack::Request object and must return true for the Route to be matched. Returns +self+.
     def arbitrary(proc = nil, &block)
       @arbitrary << (proc || block)
       self
     end
   
+    # Compile state for route. Returns +true+ or +false+.
     def compiled?
       !@paths.nil?
     end
   
-    def compile(force = false)
-      if force || @paths.nil?
+    # Compiles the route and inserts it into the tree. This is called automatically when you add a destination via #to to the route. Until a route
+    # is compiled, it will not be recognized.
+    def compile
+      if @paths.nil?
         router.named_routes[@name] = self if @name
         @paths = compile_paths
         @paths.each_with_index do |p1, i|
@@ -138,7 +183,6 @@ class HttpRouter
           end
         end
         @paths.each do |path|
-          path.route = self
           current_node = router.root.add_path(path)
           working_set = current_node.add_request_methods(@conditions)
           working_set.map!{|node| node.add_arbitrary(@arbitrary)}
@@ -150,8 +194,8 @@ class HttpRouter
       self
     end
   
+    # Sets the destination of this route to redirect to an arbitrary URL.
     def redirect(path, status = 302)
-      guard_compiled
       raise(ArgumentError, "Status has to be an integer between 300 and 399") unless (300..399).include?(status)
       to { |env|
         params = env['router.params']
@@ -162,9 +206,8 @@ class HttpRouter
       self
     end
     
+    # Sets the destination of this route to serve static files from either a directory or a single file.
     def static(root)
-      guard_compiled
-      raise AlreadyCompiledException.new if compiled?
       if File.directory?(root)
         partial.to ::Rack::File.new(root)
       else
@@ -173,14 +216,17 @@ class HttpRouter
       self
     end
 
+    # The current state of trailing / ignoring on this route. Returns +true+ or +false+.
     def trailing_slash_ignore?
       @trailing_slash_ignore
     end
 
+    # The current state of partial matching on this route. Returns +true+ or +false+.
     def partially_match?
       @partially_match
     end
 
+    # Generates a URL for this route. See HttpRouter#url for how the arguments for this are structured.
     def url(*args)
       options = args.last.is_a?(Hash) ? args.pop : nil
       options ||= {} if default_values
@@ -229,41 +275,12 @@ class HttpRouter
       path[-2, 2] == '/?' && path.slice!(-2, 2)
     end
 
-    def compile_optionals(path)
-      start_index = 0
-      end_index = 1
-
-      paths = [""]
-      chars = path.split('')
-
-      chars.each do |c|
-        case c
-          when '('
-            # over current working set, double paths
-            (start_index...end_index).each do |path_index|
-              paths << paths[path_index].dup
-            end
-            start_index = end_index
-            end_index = paths.size
-          when ')'
-            start_index -= end_index - start_index
-          else
-            (start_index...end_index).each do |path_index|
-              paths[path_index] << c
-            end
-        end
-      end
-      paths
-    end
-
     def compile_paths
-      paths = compile_optionals(@path)
+      paths = HttpRouter::OptionalCompiler.new(@path).paths
       paths.map do |path|
         original_path = path.dup
-        index = -1
         split_path = router.split(path)
         new_path = split_path.map do |part|
-          index += 1
           case part
           when /^:([a-zA-Z_0-9]+)$/
             v_name = $1.to_sym
@@ -276,7 +293,7 @@ class HttpRouter
           end
         end
         new_path.flatten!
-        Path.new(original_path, new_path)
+        Path.new(self, original_path, new_path)
       end
     end
 
@@ -309,5 +326,14 @@ class HttpRouter
     def guard_compiled
       raise AlreadyCompiledException.new if compiled?
     end
+
+    def significant_variable_names
+      unless @significant_variable_names
+        @significant_variable_names = @paths.map { |p| p.variable_names }
+        @significant_variable_names.flatten!
+        @significant_variable_names.uniq!
+      end
+      @significant_variable_names
+    end
   end
 end

data/lib/http_router/variable.rb

@@ -2,19 +2,23 @@ class HttpRouter
   class Variable
     attr_reader :name, :matches_with
 
-    def initialize(base, name, matches_with = nil)
-      @router = base
+    def initialize(router, name, matches_with = nil)
+      @router = router
       @name = name
       @matches_with = matches_with
     end
 
-    def matches(env, parts, whole_path)
-      if @matches_with.nil?
-        parts.first
-      elsif @matches_with and match = @matches_with.match(whole_path)
-        whole_path.slice!(0, match[0].size)
-        parts.replace(router.split(whole_path))
+    def matches?(parts, whole_path)
+      @matches_with.nil? or (@matches_with and match = @matches_with.match(whole_path) and match.begin(0) == 0)
+    end
+
+    def consume(parts, whole_path)
+      if @matches_with
+        match = @matches_with.match(whole_path)
+        parts.replace(router.split(whole_path[match.end(0), whole_path.size]))
         match[0]
+      else
+        parts.shift
       end
     end
 

data/lib/http_router.rb

@@ -3,93 +3,167 @@ require 'rack'
 require 'ext/rack/uri_escape'
 
 class HttpRouter
-  autoload :Node,     'http_router/node'
-  autoload :Root,     'http_router/root'
-  autoload :Variable, 'http_router/variable'
-  autoload :Glob,     'http_router/glob'
-  autoload :Route,    'http_router/route'
-  autoload :Response, 'http_router/response'
-  autoload :Path,     'http_router/path'
+  autoload :Node,             'http_router/node'
+  autoload :Root,             'http_router/root'
+  autoload :Variable,         'http_router/variable'
+  autoload :Glob,             'http_router/glob'
+  autoload :Route,            'http_router/route'
+  autoload :Response,         'http_router/response'
+  autoload :Path,             'http_router/path'
+  autoload :OptionalCompiler, 'http_router/optional_compiler'
 
+  # Raised when a Route is not able to be generated.
   UngeneratableRouteException      = Class.new(RuntimeError)
+  # Raised when a Route is not able to be generated due to a missing parameter.
   MissingParameterException        = Class.new(RuntimeError)
+  # Raised when a Route is generated that isn't valid.
+  InvalidRouteException            = Class.new(RuntimeError)
+  # Raised when a Route is not able to be generated due to too many parameters being passed in.
   TooManyParametersException       = Class.new(RuntimeError)
+  # Raised when an already inserted Route has more conditions added.
   AlreadyCompiledException         = Class.new(RuntimeError)
+  # Raised when an ambiguous Route is added. For example, this will be raised if you attempt to add "/foo(/:bar)(/:baz)".
   AmbiguousRouteException          = Class.new(RuntimeError)
+  # Raised when a request condition is added that is not recognized.
   UnsupportedRequestConditionError = Class.new(RuntimeError)
+  # Raised when there is a potential conflict of variable names within your Route.
   AmbiguousVariableException       = Class.new(RuntimeError)
 
   attr_reader :named_routes, :routes, :root
 
+  # Monkey-patches Rack::Builder to use HttpRouter.
+  # See examples/rack_mapper.rb
   def self.override_rack_mapper!
     require File.join('ext', 'rack', 'rack_mapper')
   end
 
-  def initialize(options = nil, &block)
-    @options = options
-    @default_app = options && options[:default_app] || proc{|env| ::Rack::Response.new("Not Found", 404).finish }
+  # Creates a new HttpRouter.
+  # Can be called with either <tt>HttpRouter.new(proc{|env| ... }, { .. options .. })</tt> or with the first argument omitted.
+  # If there is a proc first, then it's used as the default app in the case of a non-match.
+  # Supported options are
+  # * :default_app -- Default application used if there is a non-match on #call. Defaults to 404 generator.
+  # * :ignore_trailing_slash -- Ignore a trailing / when attempting to match. Defaults to +true+.
+  # * :redirect_trailing_slash -- On trailing /, redirect to the same path without the /. Defaults to +false+.
+  # * :middleware -- On recognition, store the route Response in env['router.response'] and always call the default app. Defaults to +false+.
+  def initialize(*args, &block)
+    default_app, options = args.first.is_a?(Hash) ? [nil, args.first] : [args.first, args[1]]
+
+    @options                 = options
+    @default_app             = default_app || options && options[:default_app] || proc{|env| Rack::Response.new("Not Found", 404).finish }
     @ignore_trailing_slash   = options && options.key?(:ignore_trailing_slash) ? options[:ignore_trailing_slash] : true
     @redirect_trailing_slash = options && options.key?(:redirect_trailing_slash) ? options[:redirect_trailing_slash] : false
-    @routes = []
-    @named_routes = {}
-    @init_block = block
+    @middleware              = options && options.key?(:middleware) ? options[:middleware] : false
+    @routes                  = []
+    @named_routes            = {}
+    @init_block              = block
     reset!
-    instance_eval(&block) if block
+    if block
+      instance_eval(&block)
+      @routes.each {|r| r.compile}
+    end
   end
 
+  # Ignore trailing slash feature enabled? See #initialize for details.
   def ignore_trailing_slash?
     @ignore_trailing_slash
   end
 
+  # Redirect trailing slash feature enabled? See #initialize for details.
   def redirect_trailing_slash?
     @redirect_trailing_slash
   end
 
+  # Resets the router to a clean state.
   def reset!
     @root = Root.new(self)
     @routes.clear
     @named_routes.clear
   end
 
+  # Assigns the default application.
   def default(app)
     @default_app = app
   end
   
-  def split(path)
-    (path[0] == ?/ ? path[1, path.size] : path).split('/')
+  # Adds a path to be recognized.
+  #
+  # To assign a part of the path to a specific variable, use :variable_name within the route.
+  # For example, <tt>add('/path/:id')</tt> would match <tt>/path/test</tt>, with the variable <tt>:id</tt> having the value <tt>"test"</tt>.
+  #
+  # You can receive mulitple parts into a single variable by using the glob syntax.
+  # For example, <tt>add('/path/*id')</tt> would match <tt>/path/123/456/789</tt>, with the variable <tt>:id</tt> having the value <tt>["123", "456", "789"]</tt>.
+  #
+  # As well, paths can end with two optional parts, <tt>*</tt> and <tt>/?</tt>. If it ends with a <tt>*</tt>, it will match partially, returning the part of the path unmatched in the PATH_INFO value of the env. The part matched to will be returned in the SCRIPT_NAME. If it ends with <tt>/?</tt>, then a trailing / on the path will be optionally matched for that specific route. As trailing /'s are ignored by default, you probably don't actually want to use this option that frequently.
+  # 
+  # Routes can also contain optional parts. There are surrounded with <tt>( )</tt>'s. If you need to match on a bracket in the route itself, you can escape the parentheses with a backslash.
+  #
+  # The second argument, options, is an optional hash that can modify the route in further ways. See HttpRouter::Route#with_options for details. Typically, you want to add further options to the route by calling additional methods on it. See HttpRouter::Route for further details.
+  #
+  # Returns the route object.
+  def add(path, options = nil)
+    add_route Route.new(self, path.dup).with_options(options)
   end
 
-  def add(path, options = nil)
-    route = Route.new(self, path.dup).with_options(options)
+  # Adds a route to be recognized. This must be a HttpRouter::Route object. Returns the route just added.
+  def add_route(route)
     @routes << route
     route
   end
 
+  # Adds a path that only responds to the request methods +GET+ and +HEAD+.
+  #
+  # Returns the route object.
   def get(path, options = nil)
     add(path, options).get
   end
 
+  # Adds a path that only responds to the request method +POST+.
+  #
+  # Returns the route object.
   def post(path, options = nil)
     add(path, options).post
   end
 
+  # Adds a path that only responds to the request method +PUT+.
+  #
+  # Returns the route object.
   def put(path, options = nil)
     add(path, options).put
   end
 
+  # Adds a path that only responds to the request method +DELETE+.
+  #
+  # Returns the route object.
   def delete(path, options = nil)
     add(path, options).delete
   end
 
+  # Adds a path that only responds to the request method +GET+.
+  #
+  # Returns the route object.
   def only_get(path, options = nil)
     add(path, options).only_get
   end
 
+  # Returns the HttpRouter::Response object if the env is matched, otherwise, returns +nil+.
   def recognize(env)
     response = @root.find(env.is_a?(Hash) ? Rack::Request.new(env) : env)
   end
 
-  # Generate a URL for a specified route.
+  # Generate a URL for a specified route. This will accept a list of variable values plus any other variable names named as a hash.
+  # This first value must be either the Route object or the name of the route.
+  # 
+  # Example:
+  #   router = HttpRouter.new
+  #   router.add('/:foo.:format).name(:test).compile
+  #   router.url(:test, 123, 'html')
+  #   # ==> "/123.html"
+  #   router.url(:test, 123, :format => 'html')
+  #   # ==> "/123.html"
+  #   router.url(:test, :foo => 123, :format => 'html')
+  #   # ==> "/123.html"
+  #   router.url(:test, :foo => 123, :format => 'html', :fun => 'inthesun')
+  #   # ==> "/123.html?fun=inthesun"
   def url(route, *args)
     case route
       when Symbol
@@ -101,7 +175,10 @@ class HttpRouter
     end
   end
 
-  # Allow the router to be called via Rake / Middleware.
+  # Rack compatible #call. If matching route is found, and +dest+ value responds to #call, processing will pass to the matched route. Otherwise, 
+  # the default application will be called. The router will be available in the env under the key <tt>router</tt>. And parameters matched will
+  # be available under the key <tt>router.params</tt>. The HttpRouter::Response object will be available under the key <tt>router.response</tt> if
+  # a response is available.
   def call(env)
     request = Rack::Request.new(env)
     if redirect_trailing_slash? && (request.head? || request.get?) && request.path_info[-1] == ?/
@@ -110,7 +187,7 @@ class HttpRouter
       response.finish
     else
       env['router'] = self
-      if response = recognize(request)
+      if response = recognize(request) and !@middleware
         if response.matched? && response.route.dest && response.route.dest.respond_to?(:call)
           process_params(env, response)
           consume_path!(request, response) if response.partial_match?
@@ -119,6 +196,7 @@ class HttpRouter
           return [response.status, response.headers, []]
         end
       end
+      env['router.response'] = response
       @default_app.call(env)
     end
   end
@@ -147,15 +225,18 @@ class HttpRouter
     Glob.new(self, *args)
   end
 
-  def dup
-    dup_router = HttpRouter.new(@options, &@init_block)
-    @routes.each do |r|
-      new_route = r.dup
-      new_route.router = dup_router
-      dup_router.routes << new_route
-      new_route.compile(true)
+  # Creates a deep-copy of the router.
+  def clone
+    cloned_router = HttpRouter.new(@default_app, @options, &@init_block)
+    @routes.each do |route|
+      new_route = route.clone
+      new_route.instance_variable_set(:@router, cloned_router)
     end
-    dup_router
+    cloned_router
+  end
+
+  def split(path)
+    (path[0] == ?/ ? path[1, path.size] : path).split('/')
   end
 
   private

data/spec/generate_spec.rb

@@ -129,5 +129,13 @@ describe "HttpRouter#generate" do
         @router.url(:test, 123).should == "/123?page=1"
       end
     end
+
+    context "with a matching" do
+      it "should raise an exception when the route is invalid" do
+        @router.add("/:var").matching(:var => /\d+/).name(:test).compile
+        proc{@router.url(:test, 'asd')}.should raise_error(HttpRouter::InvalidRouteException)
+      end
+    end
+
   end
 end

data/spec/misc_spec.rb

@@ -5,12 +5,13 @@ describe "HttpRouter" do
 
   context "route adding" do
     it "should work with options too" do
-      route = @router.add('/:test', :conditions => {:request_method => %w{HEAD GET}, :host => 'host1'}, :default_values => {:page => 1}, :matching => {:test => /^\d+/}).to :test
-      @router.recognize(Rack::MockRequest.env_for('http://host2/variable', :method => 'POST')).matched?.should be_false
-      @router.recognize(Rack::MockRequest.env_for('http://host1/variable', :method => 'POST')).matched?.should be_false
-      @router.recognize(Rack::MockRequest.env_for('http://host2/123', :method => 'POST')).matched?.should be_false
-      @router.recognize(Rack::MockRequest.env_for('http://host1/123', :method => 'POST')).matched?.should be_false
-      @router.recognize(Rack::MockRequest.env_for('http://host1/123', :method => 'GET')).route.dest.should == :test
+      route = @router.add('/:test', :conditions => {:request_method => %w{HEAD GET}, :host => 'host1'}, :default_values => {:page => 1}, :matching => {:test => /\d+/}, :name => :foobar).to :test
+      @router.recognize(Rack::MockRequest.env_for('http://host2/variable', :method => 'POST')).should be_nil
+      @router.recognize(Rack::MockRequest.env_for('http://host1/variable', :method => 'POST')).should be_nil
+      @router.recognize(Rack::MockRequest.env_for('http://host2/123',      :method => 'POST')).matched?.should be_false
+      @router.recognize(Rack::MockRequest.env_for('http://host1/123',      :method => 'POST')).matched?.should be_false
+      @router.recognize(Rack::MockRequest.env_for('http://host1/123',      :method => 'GET' )).route.dest.should == :test
+      @router.url(:foobar, '123').should == '/123?page=1'
     end
   end
 
@@ -34,24 +35,30 @@ describe "HttpRouter" do
     it "should raise on unsupported request methods" do
       proc {@router.add("/").condition(:flibberty => 'gibet').compile}.should raise_error(HttpRouter::UnsupportedRequestConditionError)
     end
-
   end
 
-  context "dupping" do
-    it "run the routes" do
-      pending
+  context "cloning" do
+    it "clone the routes" do
       r1 = HttpRouter.new {
         add('/test').name(:test_route).to :test
       }
-      r2 = r1.dup
-      r2.add('/test2').to(:test2)
+      r2 = r1.clone
+      
+      r2.add('/test2').name(:test).to(:test2)
+      r2.routes.size.should == 2
+      
       r1.recognize(Rack::MockRequest.env_for('/test2')).should be_nil
       r2.recognize(Rack::MockRequest.env_for('/test2')).should_not be_nil
-      
       r1.named_routes[:test_route].should == r1.routes.first
       r2.named_routes[:test_route].should == r2.routes.first
+
+      r1.add('/another').name(:test).to(:test2)
+      
+      r1.routes.size.should == r2.routes.size
+      r1.url(:test).should == '/another'
+      r2.url(:test).should == '/test2'
+      r1.routes.first.dest.should == :test
+      r2.routes.first.dest.should == :test
     end
   end
-
-
 end

data/spec/rack/middleware_spec.rb

@@ -0,0 +1,20 @@
+describe "HttpRouter as middleware" do
+  before(:each) do
+    @builder = Rack::Builder.new do
+      use(HttpRouter, :middleware => true) {
+        add('/test').name(:test).to(:test)
+      }
+    end
+  end
+
+  it "should always have the router" do
+    @builder.run proc{|env| [200, {}, [env['router'].url(:test)]]}
+    @builder.call(Rack::MockRequest.env_for('/some-path')).last.join.should == '/test'
+  end
+
+  it "should stash the match if it exists" do
+    @builder.run proc{|env| [200, {}, [env['router.response'].dest.to_s]]}
+    @builder.call(Rack::MockRequest.env_for('/test')).last.join.should == 'test'
+  end
+end
+  

data/spec/recognize_spec.rb

@@ -3,14 +3,14 @@ describe "HttpRouter#recognize" do
     @router = HttpRouter.new
   end
 
-  context("static paths") do
+  context("with static paths") do
     ['/', '/test', '/test/time', '/one/more/what', '/test.html'].each do |path|
       it "should recognize #{path.inspect}" do
         route = @router.add(path).to(path)
         @router.recognize(Rack::MockRequest.env_for(path)).route.should == route
       end
     end
-
+    
     context("with optional parts") do
       it "work either way" do
         route = @router.add("/test(/optional)").to(:test)
@@ -19,7 +19,16 @@ describe "HttpRouter#recognize" do
       end
     end
 
-    context("partial matching") do
+    context("with escaped ()'s") do
+      it "should recognize ()" do
+        route = @router.add('/test\(:variable\)').to(:test)
+        response = @router.recognize(Rack::MockRequest.env_for('/test(hello)'))
+        response.route.should == route
+        response.params.first.should == 'hello'
+      end
+    end
+
+    context("with partial matching") do
       it "should match partially or completely" do
         route = @router.add("/test*").to(:test)
         @router.recognize(Rack::MockRequest.env_for('/test')).route.should == route
@@ -29,8 +38,8 @@ describe "HttpRouter#recognize" do
       end
     end
 
-    context("proc acceptance") do
-      it "should match optionally with a proc" do
+    context("with proc acceptance") do
+      it "should match" do
         @router.add("/test").arbitrary(Proc.new{|req| req.host == 'hellodooly' }).to(:test1)
         @router.add("/test").arbitrary(Proc.new{|req| req.host == 'lovelove' }).arbitrary{|req| req.port == 80}.to(:test2)
         @router.add("/test").arbitrary(Proc.new{|req| req.host == 'lovelove' }).arbitrary{|req| req.port == 8080}.to(:test3)
@@ -47,7 +56,7 @@ describe "HttpRouter#recognize" do
         response.dest.should == :test4
       end
 
-      it "should match optionally with a proc and request conditions" do
+      it "should match with request conditions" do
         @router.add("/test").get.arbitrary(Proc.new{|req| req.host == 'lovelove' }).arbitrary{|req| req.port == 80}.to(:test1)
         @router.add("/test").get.arbitrary(Proc.new{|req| req.host == 'lovelove' }).arbitrary{|req| req.port == 8080}.to(:test2)
         response = @router.recognize(Rack::MockRequest.env_for('http://lovelove:8080/test'))
@@ -64,33 +73,32 @@ describe "HttpRouter#recognize" do
 
     end
 
-    context("trailing slashes") do
-      it "should ignore a trailing slash" do
+    context("with trailing slashes") do
+      it "should ignore" do
         route = @router.add("/test").to(:test)
         @router.recognize(Rack::MockRequest.env_for('/test/')).route.should == route
       end
 
-      it "should not recognize a trailing slash when used with the /? syntax and ignore_trailing_slash disabled" do
+      it "should not recognize when used with the /? syntax and ignore_trailing_slash disabled" do
         @router = HttpRouter.new(:ignore_trailing_slash => false)
         route = @router.add("/test/?").to(:test)
         @router.recognize(Rack::MockRequest.env_for('/test/')).route.should == route
       end
 
-      it "should recognize a trailing slash when used with the /? syntax and ignore_trailing_slash enabled" do
+      it "should recognize when used with the /? syntax and ignore_trailing_slash enabled" do
         @router = HttpRouter.new(:ignore_trailing_slash => false)
         route = @router.add("/test").to(:test)
         @router.recognize(Rack::MockRequest.env_for('/test/')).should be_nil
       end
-      it "should not capture the trailing slash in a variable normally" do
+      it "should not capture normally" do
         route = @router.add("/:test").to(:test)
         @router.recognize(Rack::MockRequest.env_for('/test/')).params.first.should == 'test'
       end
     end
-
   end
 
-  context "variables" do
-    it "should recognize a simple variable" do
+  context "with variables" do
+    it "should recognize" do
       @router.add("/foo").to(:test1)
       @router.add("/foo/:id").to(:test2)
       @router.recognize(Rack::MockRequest.env_for('/foo')).dest.should == :test1
@@ -98,15 +106,24 @@ describe "HttpRouter#recognize" do
     end
   end
 
-  context "request methods" do
-    it "should pick a specific request_method" do
+  context "with missing leading /" do
+    it "should recognize" do
+      @router.add("foo").to(:test1)
+      @router.add("foo.html").to(:test2)
+      @router.recognize(Rack::MockRequest.env_for('/foo')).dest.should == :test1
+      @router.recognize(Rack::MockRequest.env_for('/foo.html')).dest.should == :test2
+    end
+  end
+
+  context "with request methods" do
+    it "should recognize" do
       route = @router.post("/test").to(:test)
       @router.recognize(Rack::MockRequest.env_for('/test', :method => 'POST')).route.should == route
       @router.recognize(Rack::MockRequest.env_for('/test', :method => 'GET')).status.should == 405
       @router.recognize(Rack::MockRequest.env_for('/test', :method => 'GET')).headers['Allow'].should == "POST"
     end
 
-    it "should pick a specific request_method with other paths all through it" do
+    it "should recognize deeply" do
       @router.post("/test").to(:test_post)
       @router.post("/test/post").to(:test_post_post)
       @router.get("/test").to(:test_get)
@@ -136,7 +153,7 @@ describe "HttpRouter#recognize" do
 
   end
 
-  context("dynamic paths") do
+  context("with dynamic paths") do
     it "should recognize '/:variable'" do
       route = @router.add('/:variable').to(:test)
       response = @router.recognize(Rack::MockRequest.env_for('/value'))
@@ -183,15 +200,15 @@ describe "HttpRouter#recognize" do
       response.params_as_hash[:test].should == 'hey'
     end
     
-    context "globs" do
-      it "should recognize a glob" do
+    context "with globs" do
+      it "should recognize" do
         route = @router.add('/test/*variable').to(:test)
         response = @router.recognize(Rack::MockRequest.env_for('/test/one/two/three'))
         response.route.should == route
         response.params.should == [['one', 'two', 'three']]
       end
-      it "should recognize a glob with a regexp" do
-        route = @router.add('/test/*variable/anymore').matching(:variable => /^\d+$/).to(:test)
+      it "should recognize with a regexp" do
+        route = @router.add('/test/*variable/anymore').matching(:variable => /\d+/).to(:test)
         response = @router.recognize(Rack::MockRequest.env_for('/test/123/345/567/anymore'))
         response.route.should == route
         response.params.should == [['123', '345', '567']]
@@ -202,23 +219,23 @@ describe "HttpRouter#recognize" do
     
   end
   
-  context("interstitial variables") do
-    it "should recognize interstitial variables" do
+  context("with interstitial variables") do
+    it "should recognize" do
       route = @router.add('/one-:variable-time').to(:test)
       response = @router.recognize(Rack::MockRequest.env_for('/one-value-time'))
       response.route.should == route
       response.params_as_hash[:variable].should == 'value'
     end
 
-    it "should recognize interstitial variables with a regex" do
-      route = @router.add('/one-:variable-time').matching(:variable => /^\d+/).to(:test)
+    it "should recognize with a regex" do
+      route = @router.add('/one-:variable-time').matching(:variable => /\d+/).to(:test)
       @router.recognize(Rack::MockRequest.env_for('/one-value-time')).should be_nil
       response = @router.recognize(Rack::MockRequest.env_for('/one-123-time'))
       response.route.should == route
       response.params_as_hash[:variable].should == '123'
     end
     
-    it "should recognize interstitial variable when there is an extension" do
+    it "should recognize when there is an extension" do
       route = @router.add('/hey.:greed.html').to(:test)
       response = @router.recognize(Rack::MockRequest.env_for('/hey.greedyboy.html'))
       response.route.should == route
@@ -227,8 +244,8 @@ describe "HttpRouter#recognize" do
     
   end
 
-  context("dynamic greedy paths") do
-    it "should recognize greedy variables" do
+  context("with dynamic greedy paths") do
+    it "should recognize" do
       route = @router.add('/:variable').matching(:variable => /\d+/).to(:test)
       response = @router.recognize(Rack::MockRequest.env_for('/123'))
       response.route.should == route
@@ -238,12 +255,23 @@ describe "HttpRouter#recognize" do
       response.should be_nil
     end
 
-    it "should capture the trailing slash in a greedy variable" do
+    it "should continue on with normal if regex fails to match" do
+      @router.add("/:test/number").matching(:test => /\d+/).to(:test_number)
+      target = @router.add("/:test/anything").to(:test_anything)
+      @router.recognize(Rack::MockRequest.env_for('/123/anything')).route.should == target
+    end
+
+    it "should capture the trailing slash" do
       route = @router.add("/:test").matching(:test => /.*/).to(:test)
       @router.recognize(Rack::MockRequest.env_for('/test/')).params.first.should == 'test/'
     end
 
-    it "should capture the extension in a greedy variable" do
+    it "should require the match to begin at the beginning" do
+      route = @router.add("/:test").matching(:test => /\d+/).to(:test)
+      @router.recognize(Rack::MockRequest.env_for('/a123')).should be_nil
+    end
+
+    it "should capture the extension" do
       route = @router.add("/:test").matching(:test => /.*/).to(:test)
       @router.recognize(Rack::MockRequest.env_for('/test.html')).params.first.should == 'test.html'
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: http_router
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 17
   prerelease: false
   segments: 
   - 0
   - 1
-  - 4
-  version: 0.1.4
+  - 5
+  version: 0.1.5
 platform: ruby
 authors: 
 - Joshua Hull
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-30 00:00:00 -04:00
+date: 2010-05-30 00:00:00 +09:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -54,8 +54,9 @@ files:
 - benchmarks/rec2.rb
 - benchmarks/recognition_bm.rb
 - examples/glob.ru
+- examples/middleware.ru
+- examples/rack_mapper.ru
 - examples/simple.ru
-- examples/simple_with_mapper.ru
 - examples/variable.ru
 - examples/variable_with_regex.ru
 - http_router.gemspec
@@ -65,6 +66,7 @@ files:
 - lib/http_router/glob.rb
 - lib/http_router/interface/sinatra.rb
 - lib/http_router/node.rb
+- lib/http_router/optional_compiler.rb
 - lib/http_router/path.rb
 - lib/http_router/response.rb
 - lib/http_router/root.rb
@@ -74,6 +76,7 @@ files:
 - spec/misc_spec.rb
 - spec/rack/dispatch_spec.rb
 - spec/rack/generate_spec.rb
+- spec/rack/middleware_spec.rb
 - spec/rack/route_spec.rb
 - spec/recognize_spec.rb
 - spec/sinatra/recognize_spec.rb
@@ -118,6 +121,7 @@ test_files:
 - spec/misc_spec.rb
 - spec/rack/dispatch_spec.rb
 - spec/rack/generate_spec.rb
+- spec/rack/middleware_spec.rb
 - spec/rack/route_spec.rb
 - spec/recognize_spec.rb
 - spec/sinatra/recognize_spec.rb

data/examples/simple_with_mapper.ru

@@ -1,15 +0,0 @@
-require 'http_router'
-HttpRouter.override_rack_mapper!
-
-map('/get/:id') { |env|
-  [200, {'Content-type' => 'text/plain'}, ["My id is #{env['router.params'][:id]}\n"]]
-}
-
-post('/get/:id') { |env|
-  [200, {'Content-type' => 'text/plain'}, ["My id is #{env['router.params'][:id]} and you posted!\n"]]
-}
-
-# crapbook-pro:~ joshua$ curl http://127.0.0.1:3000/get/123
-# My id is 123
-# crapbook-pro:~ joshua$ curl -X POST http://127.0.0.1:3000/get/123
-# My id is 123 and you posted!