usher 0.7.1 → 0.7.2

data/Gemfile

@@ -0,0 +1,10 @@
+# Generated from /Users/joshua/Development/usher/usher.gemspec
+source :gemcutter
+gem "fuzzyhash", ">= 0.0.11"
+
+group :development do
+  gem "yard", ">= 0"
+  gem "rspec", ">= 0"
+  gem "code_stats", ">= 0"
+  gem "rake", ">= 0"
+end

data/README.markdown

@@ -0,0 +1,158 @@
+# Usher
+
+Tree-based router library. Useful for (specifically) for Rails and Rack, but probably generally useful for anyone interested in doing routing. Based on Ilya Grigorik suggestion, turns out looking up in a hash and following a tree is faster than Krauter's massive regex approach.
+
+## Features
+
+* Understands single and path-globbing variables
+* Understands arbitrary regex variables
+* Arbitrary HTTP header requirements
+* No optimization phase, so routes are always alterable after the fact
+* Understands Proc and Regex transformations, validations
+* Really, really fast
+* Relatively light and happy code-base, should be easy and fun to alter (it hovers around 1,000 LOC, 800 for the core)
+* Interface and implementation are separate, encouraging cross-pollination
+* Works in 1.9!
+
+## Projects using or other references to Usher
+
+* [http://github.com/Tass/CRUDtree](http://github.com/Tass/CRUDtree) - RESTful resource mapper
+* [http://github.com/padrino/padrino-framework](http://github.com/padrino/padrino-framework) - Web framework
+* [http://github.com/botanicus/rango](http://github.com/botanicus/rango) - Web framework
+* [http://github.com/hassox/pancake](http://github.com/hassox/pancake) - Web framework
+* [http://github.com/eddanger/junior](http://github.com/eddanger/junior) - Web framework
+* [http://github.com/lifo/cramp](http://github.com/lifo/cramp) - Web framework
+* [http://yehudakatz.com/2009/08/26/how-to-build-sinatra-on-rails-3/](http://yehudakatz.com/2009/08/26/how-to-build-sinatra-on-rails-3/) - How to Build Sinatra on Rails 3
+
+Any probably more!
+
+## Route format
+
+From the rdoc:
+
+Creates a route from +path+ and +options+
+
+### `path`
+A path consists a mix of dynamic and static parts delimited by `/`
+
+#### 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>
+`/path/:variable/path` 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.
+
+<b>Example:</b>
+`/path/*variable/path` 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`.
+
+As well, variables can have a regex matcher.
+
+<b>Example:</b>
+`/product/{:id,\d+}` would match
+
+* `/product/123`
+* `/product/4521`
+
+But not
+* `/product/AE-35`
+
+As well, the same logic applies for * variables as well, where only parts matchable by the supplied regex will
+actually be bound to the variable
+
+Variables can also have a greedy regex matcher. These matchers ignore all delimiters, and continue matching for as long as much as their
+regex allows.
+
+<b>Example:</b>
+`/product/{!id,hello/world|hello}` would match
+
+* `/product/hello/world`
+* `/product/hello`
+
+
+#### Static
+
+Static parts of literal character sequences. For instance, `/path/something.html` would match only the same path.
+As well, static parts can have a regex pattern in them as well, such as `/path/something.{html|xml}` which would match only
+`/path/something.html` and `/path/something.xml`
+
+#### Optional sections
+
+Sections of a route can be marked as optional by surrounding it with brackets. For instance, in the above static example, `/path/something(.html)` would match both `/path/something` and `/path/something.html`.
+
+#### 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, `/path/something(.xml|.html)` would only match `/path/something.xml` and
+`/path/something.html`. Generally its more efficent to use one and only sections over using regex.
+
+### `options`
+* `requirements` - After transformation, tests the condition using #===. If it returns false, it raises an `Usher::ValidationException`
+* `conditions` - Accepts any of the `request_methods` specificied in the construction of Usher. This can be either a `string` or a regular expression.
+* `default_values` - Provides values for variables in your route for generation. If you're using URL generation, then any values supplied here that aren't included in your path will be appended to the query string.
+* `priority` - If there are two routes which equally match, the route with the highest priority will match first.
+* Any other key is interpreted as a requirement for the variable of its name.
+
+## Rails
+
+    script/plugin install git://github.com/joshbuddy/usher.git
+
+In your config/initializers/usher.rb (create if it doesn't exist) add:
+
+    Usher::Util::Rails.activate
+
+## Rack
+
+### `config.ru`
+
+    require 'usher'
+    app # proc do |env|
+      body # "Hi there #{env['usher.params'][:name]}"
+      [
+        200,          # Status code
+        {             # Response headers
+          'Content-Type' #> 'text/plain',
+          'Content-Length' #> body.size.to_s,
+        },
+        [body]        # Response body
+      ]
+    end
+   
+    routes # Usher::Interface.for(:rack) do
+      add('/hello/:name').to(app)
+    end
+   
+    run routes
+
+------------
+
+    >> curl http://127.0.0.1:3000/hello/samueltanders
+    << Hi there samueltanders
+
+
+## Sinatra
+
+In Sinatra, you get the extra method, +generate+, which lets you generate a url. Name your routes with `:name` when you define them.
+
+    require 'rubygems'
+    require 'usher'
+    require 'sinatra'
+    
+    Usher::Interface.for(:sinatra)
+    
+    get '/hi', :name #> :hi do
+      "Hello World! #{generate(:hi)}"
+    end
+
+(Let me show you to your request)

data/Rakefile

@@ -2,7 +2,14 @@
 
 require 'spec'
 require 'spec/rake/spectask'
-task :spec => ['spec:private', 'spec:rails2_2', 'spec:rails2_3']
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']   # optional
+  t.options = ['--markup=markdown'] # optional
+end
+
+task :spec => ['spec:private', 'spec:rails2_2:cleanup', 'spec:rails2_3:cleanup']
 namespace(:spec) do
   Spec::Rake::SpecTask.new(:private) do |t|
     t.spec_opts ||= []
@@ -11,20 +18,48 @@ namespace(:spec) do
     t.spec_files = FileList['spec/private/**/*_spec.rb']
   end
 
-  Spec::Rake::SpecTask.new(:rails2_2) do |t|
-    t.spec_opts ||= []
-    t.spec_opts << "-rubygems"
-    t.spec_opts << "--options" << "spec/spec.opts"
-    t.spec_files = FileList['spec/rails2_2/**/*_spec.rb']
-  end
+  namespace(:rails2_2) do
+    task :unzip do
+      sh('rm -rf spec/rails2_2/vendor')
+      sh('unzip -qq spec/rails2_2/vendor.zip -dspec/rails2_2')
+    end
 
-  Spec::Rake::SpecTask.new(:rails2_3) do |t|
-    t.spec_opts ||= []
-    t.spec_opts << "-rubygems"
-    t.spec_opts << "--options" << "spec/spec.opts"
-    t.spec_files = FileList['spec/rails2_3/**/*_spec.rb']
+    Spec::Rake::SpecTask.new(:spec) do |t|
+      t.spec_opts ||= []
+      t.spec_opts << "-rubygems"
+      t.spec_opts << "--options" << "spec/spec.opts"
+      t.spec_files = FileList['spec/rails2_2/**/*_spec.rb']
+    end
+    
+    task :cleanup do
+      sh('rm -rf spec/rails2_2/vendor')
+    end
+    
+    task :spec => :unzip
+    task :cleanup => :spec
   end
 
+  namespace(:rails2_3) do
+    task :unzip do
+      sh('rm -rf spec/rails2_3/vendor')
+      sh('unzip -qq spec/rails2_3/vendor.zip -dspec/rails2_3')
+    end
+
+    Spec::Rake::SpecTask.new(:spec) do |t|
+      t.spec_opts ||= []
+      t.spec_opts << "-rubygems"
+      t.spec_opts << "--options" << "spec/spec.opts"
+      t.spec_files = FileList['spec/rails2_3/**/*_spec.rb']
+    end
+    task :cleanup do
+      sh('rm -rf spec/rails2_3/vendor')
+    end
+
+    task :spec => :unzip
+    task :cleanup => :spec
+  end
+  
+  
 end
 
 desc "Run all examples with RCov"

data/benchmarks/rack_recognition_bm.rb

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rbench'
+require 'lib/usher'
+
+u = Usher::Interface.for(:rack)
+u.add('/simple').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+u.add('/simple/again').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+u.add('/simple/again/and/again').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+u.add('/dynamic/:variable').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+u.add('/rails/:controller/:action/:id').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+u.add('/greedy/{!:greed,.*}').to(proc{|env| [200, {'Content-type'=>'text/html'}, []]})
+
+TIMES = 50_000
+
+simple_env = Rack::MockRequest.env_for('/simple')
+simple2_env = Rack::MockRequest.env_for('/simple/again')
+simple3_env = Rack::MockRequest.env_for('/simple/again/and/again')
+simple_and_dynamic_env = Rack::MockRequest.env_for('/simple/anything')
+simple_and_dynamic_env1 = Rack::MockRequest.env_for('/rails/controller/action/id')
+simple_and_dynamic_env2 = Rack::MockRequest.env_for('/greedy/controller/action/id')
+
+RBench.run(TIMES) do
+
+  report "2 levels, static" do
+    u.call(simple_env)
+  end
+
+  report "4 levels, static" do
+    u.call(simple2_env)
+  end
+  
+  report "8 levels, static" do
+    u.call(simple3_env)
+  end
+  
+  report "4 levels, 1 dynamic" do
+    u.call(simple_and_dynamic_env)
+  end
+  
+  report "8 levels, 3 dynamic" do
+    u.call(simple_and_dynamic_env1)
+  end
+  
+  report "4 levels, 1 greedy" do
+    u.call(simple_and_dynamic_env2)
+  end
+
+end

data/lib/usher/delimiters.rb

@@ -1,8 +1,11 @@
 class Usher
+  # Array of delimiters with convenience methods.
   class Delimiters < Array
 
     attr_reader :unescaped
-  
+    
+    # Creates a list of delimiters
+    # @param arr [Array<String>] delimters to use
     def initialize(ary)
       super ary
       @unescaped = self.map do |delimiter|
@@ -10,15 +13,24 @@ class Usher
       end
     end
   
+    # Finds the first occurrance of a delimiter in an array
+    # @param array [Array<String>] Array to search through
+    # @return [nil, String] The delimiter matched, or nil if none was found.
     def first_in(array)
-      # TODO: should we optimize this O(n*m)? hash or modified or KNP or at leaset sort + b-search. But they are so short
-
-      array.each do |element|
-        return element if self.unescaped.any? { |delimiter| delimiter == element }
-      end
-      nil    
+      array.find { |e| e if unescaped.any? { |delimiter| delimiter == e } }
     end
 
-    # TODO: Delimiters#regex and so on  
+    # The regular expression to find the delimiters.
+    # @return [Regexp] The regular expression
+    def regexp
+      @regexp ||= Regexp.new("(#{unescaped.collect{|d| Regexp.quote(d)}.join('|')})")
+    end
+    
+    # The regular expression expressed as a character class.
+    # @return [String] The regular expression as a string.
+    def regexp_char_class
+      @regexp_char_class ||= collect{|d| Regexp.quote(d)}.join
+    end
+    
   end
 end

data/lib/usher/exceptions.rb

@@ -1,6 +1,10 @@
 class Usher
+  # Exception raised when generation is attempted and the route cannot be determined
   class UnrecognizedException < RuntimeError; end
+  # Raised when a validator fails during recognition
   class ValidationException < RuntimeError; end
+  # Raised when generation attempts to create a route and a parameter is missing
   class MissingParameterException < RuntimeError; end
+  # Raised when a route is added with identical variable names and allow_identical_variable_names? is false
   class MultipleParameterException < RuntimeError; end
 end

data/lib/usher/grapher.rb

@@ -1,4 +1,5 @@
 class Usher
+  # Find nearest matching routes based on parameter keys.
   class Grapher
 
     attr_reader :routes, :router, :orders, :key_count, :cache
@@ -8,20 +9,39 @@ class Usher
       reset!
     end
 
-    def reset!
-      @significant_keys = nil
-      @orders = Hash.new{|h,k| h[k] = Hash.new{|h2, k2| h2[k2] = []}}
-      @key_count = Hash.new(0)
-      @cache = {}
-      @routes = []
-    end
-
+    # Add route for matching
     def add_route(route)
+      reset! if @processed
       routes << route
     end
 
+    # Finds a matching path based on params hash
+    def find_matching_path(params)
+      unless params.empty?
+        process_routes
+        set = params.keys & significant_keys
+        if cached = cache[set] 
+          return cached
+        end
+        set.size.downto(1) do |o|
+          set.each do |k|
+            orders[o][k].each do |r| 
+              if r.can_generate_from_keys?(set)
+                cache[set] = r
+                return r
+              elsif router.consider_destination_keys? && r.can_generate_from_params?(params)
+                return r
+              end
+            end
+          end
+        end
+      end
+      nil
+    end
+    
+    private
     def process_routes
-      return if @processed 
+      return if @processed
       routes.each do |route|
         route.paths.each do |path|
           if path.dynamic?
@@ -57,33 +77,19 @@ class Usher
       end
       @processed = true
     end
-
+    
     def significant_keys
       @significant_keys ||= key_count.keys.uniq
     end
 
-    def find_matching_path(params)
-      unless params.empty?
-        process_routes
-        set = params.keys & significant_keys
-        if cached = cache[set] 
-          return cached
-        end
-        set.size.downto(1) do |o|
-          set.each do |k|
-            orders[o][k].each do |r| 
-              if r.can_generate_from_keys?(set)
-                cache[set] = r
-                return r
-              elsif router.consider_destination_keys? && r.can_generate_from_params?(params)
-                return r
-              end
-            end
-          end
-        end
-      end
-      nil
+    def reset!
+      @significant_keys = nil
+      @orders = Hash.new{|h,k| h[k] = Hash.new{|h2, k2| h2[k2] = []}}
+      @key_count = Hash.new(0)
+      @cache = {}
+      @routes = []
+      @processed = false
     end
-    
+
   end
 end

data/lib/usher/interface/rack/builder.rb

@@ -0,0 +1,39 @@
+class Usher
+  module Interface
+    class Rack
+      # Replacement for <tt>Rack::Builder</tt> which using Usher to map requests instead of a simple Hash.
+      # As well, add convenience methods for the request methods.
+      #
+      class Builder < ::Rack::Builder
+        def initialize(&block)
+          @usher = Usher::Interface::Rack.new
+          super
+        end
+
+        def map(path, options = nil, &block)
+          @usher.add(path, options).to(&block)
+          @ins << @usher unless @ins.last == @usher
+        end
+
+        # it returns route, and because you may want to work with the route,
+        # for example give it a name, we returns the route with GET request
+        def get(path, options = nil, &block)
+          self.map(path, options.merge!(:conditions => {:request_method => "HEAD"}), &block)
+          self.map(path, options.merge!(:conditions => {:request_method => "GET"}), &block)
+        end
+
+        def post(path, options = nil, &block)
+          self.map(path, options.merge!(:conditions => {:request_method => "POST"}), &block)
+        end
+
+        def put(path, options = nil, &block)
+          self.map(path, options.merge!(:conditions => {:request_method => "PUT"}), &block)
+        end
+
+        def delete(path, options = nil, &block)
+          self.map(path, options.merge!(:conditions => {:request_method => "DELETE"}), &block)
+        end
+      end
+    end
+  end
+end

data/lib/usher/interface/rack/middleware.rb

@@ -0,0 +1,22 @@
+class Usher
+  module Interface
+    class Rack
+      # Middleware for using Usher's rack interface to recognize the request, then, pass on to the next application.
+      # Values are stored in <tt>env</tt> normally.
+      #
+      class Middleware
+
+        def initialize(app, router)
+          @app = app
+          @router = router
+        end
+
+        def call(env)
+          @router.call(env)
+          @app.call(env)
+        end
+
+      end
+    end
+  end
+end

data/lib/usher/interface/rack.rb

@@ -1,64 +1,15 @@
-require "rack"
+require 'rack'
 require File.join('usher', 'interface', 'rack', 'route')
+require File.join('usher', 'interface', 'rack', 'middleware')
+require File.join('usher', 'interface', 'rack', 'builder')
 
 class Usher
   module Interface
     class Rack
       
-      ENV_KEY_RESPONSE = 'usher.response'
-      ENV_KEY_PARAMS = 'usher.params'
-      ENV_KEY_DEFAULT_ROUTER = 'usher.router'
-
-      # Middleware for using Usher's rack interface to recognize the request, then, pass on to the next application.
-      # Values are stored in <tt>env</tt> normally.
-      #
-      class Middleware
-
-        def initialize(app, router)
-          @app = app
-          @router = router
-        end
-
-        def call(env)
-          @router.call(env)
-          @app.call(env)
-        end
-
-      end
-      
-      # Replacement for <tt>Rack::Builder</tt> which using Usher to map requests instead of a simple Hash.
-      # As well, add convenience methods for the request methods.
-      #
-      class Builder < ::Rack::Builder
-        def initialize(&block)
-          @usher = Usher::Interface::Rack.new
-          super
-        end
-
-        def map(path, options = nil, &block)
-          @usher.add(path, options).to(&block)
-          @ins << @usher unless @ins.last == @usher
-        end
-
-        # it returns route, and because you may want to work with the route,
-        # for example give it a name, we returns the route with GET request
-        def get(path, options = nil, &block)
-          self.map(path, options.merge!(:conditions => {:request_method => "HEAD"}), &block)
-          self.map(path, options.merge!(:conditions => {:request_method => "GET"}), &block)
-        end
-
-        def post(path, options = nil, &block)
-          self.map(path, options.merge!(:conditions => {:request_method => "POST"}), &block)
-        end
-
-        def put(path, options = nil, &block)
-          self.map(path, options.merge!(:conditions => {:request_method => "PUT"}), &block)
-        end
-
-        def delete(path, options = nil, &block)
-          self.map(path, options.merge!(:conditions => {:request_method => "DELETE"}), &block)
-        end
-      end
+      ENV_KEY_RESPONSE       = 'usher.response'.freeze
+      ENV_KEY_PARAMS         = 'usher.params'.freeze
+      ENV_KEY_DEFAULT_ROUTER = 'usher.router'.freeze
 
       attr_reader :router, :router_key
       attr_accessor :redirect_on_trailing_delimiters