usher 0.4.8

data/History.txt

@@ -0,0 +1,3 @@
+== 0.0.1
+
+Initial release as gem

data/Manifest.txt

@@ -0,0 +1,35 @@
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+lib/compat.rb
+lib/usher.rb
+lib/usher/exceptions.rb
+lib/usher/grapher.rb
+lib/usher/interface.rb
+lib/usher/interface/merb_interface.rb
+lib/usher/interface/rack_interface.rb
+lib/usher/interface/rack_interface/mapper.rb
+lib/usher/interface/rack_interface/route.rb
+lib/usher/interface/rails2_interface.rb
+lib/usher/interface/rails2_interface/mapper.rb
+lib/usher/node.rb
+lib/usher/node/lookup.rb
+lib/usher/route.rb
+lib/usher/route/http.rb
+lib/usher/route/path.rb
+lib/usher/route/separator.rb
+lib/usher/route/splitter.rb
+lib/usher/route/variable.rb
+rails/init.rb
+spec/generate_spec.rb
+spec/node/lookup_spec.rb
+spec/path_spec.rb
+spec/rack/dispatch_spec.rb
+spec/rails/generate_spec.rb
+spec/rails/path_spec.rb
+spec/rails/recognize_spec.rb
+spec/recognize_spec.rb
+spec/spec.opts
+spec/split_spec.rb
+usher.gemspec

data/README.rdoc

@@ -0,0 +1,126 @@
+= 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
+* 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
+* Interface and implementation are separate, encouraging cross-pollination
+
+== 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 <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.
+
+As well, variables can have a regex matcher.
+
+<b>Example:</b>
+<tt>/product/{:id,\d+}</tt> would match
+
+* <tt>/product/123</tt>
+* <tt>/product/4521</tt>
+
+But not
+* <tt>/product/AE-35</tt>
+
+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
+
+==== Static
+
+Static parts of literal character sequences. For instance, <tt>/path/something.html</tt> would match only the same path.
+As well, static parts can have a regex pattern in them as well, such as <tt>/path/something.{html|xml}</tt> which would match only
+<tt>/path/something.html</tt> and <tt>/path/something.xml</tt>
+
+==== 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>. 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 <tt>Usher::ValidationException</tt>
+* +conditions+ - Accepts any of the +request_methods+ specificied in the construction of Usher. 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
+
+  script/plugin install git://github.com/joshbuddy/usher.git
+
+== 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
+
+== DONE
+
+* add support for () optional parts
+* Add support for arbitrary HTTP header checks
+* Emit exceptions inline with relevant interfaces
+* More RDoc! (optionally cowbell)
+
+== TODO
+
+* Make it integrate with merb
+* Make it integrate with rails3
+* Create decent DSL for use with rack
+
+(Let me show you to your request)

data/Rakefile

@@ -0,0 +1,72 @@
+require 'lib/usher'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "usher"
+    s.description = s.summary = "A general purpose routing library"
+    s.email = "joshbuddy@gmail.com"
+    s.homepage = "http://github.com/joshbuddy/usher"
+    s.authors = ["Joshua Hull"]
+    s.files = FileList["[A-Z]*", "{lib,spec,rails}/**/*"]
+    s.add_dependency 'fuzzyhash', '>=0.0.3'
+    s.rubyforge_project = 'joshbuddy-usher' # This line would be new
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec'
+require 'spec/rake/spectask'
+task :spec => 'spec:all'
+namespace(:spec) do
+  Spec::Rake::SpecTask.new(:all) do |t|
+    t.spec_opts ||= []
+    t.spec_opts << "-rubygems"
+    t.spec_opts << "--options" << "spec/spec.opts"
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('spec_with_rcov') do |t|
+  t.spec_files = FileList['spec/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+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
+
+# These are new tasks
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/joshbuddy-usher/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end

data/VERSION.yml

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

data/lib/usher/exceptions.rb

@@ -0,0 +1,5 @@
+class Usher
+  class UnrecognizedException < RuntimeError; end
+  class ValidationException < RuntimeError; end
+  class MissingParameterException < RuntimeError; end
+end

data/lib/usher/generate.rb

@@ -0,0 +1,131 @@
+require 'rack'
+
+unless Rack::Utils.respond_to?(:uri_escape)
+  module Rack
+
+    module Utils
+
+      def uri_escape(s)
+        s.to_s.gsub(/([^:\/?\[\]\-_~\.!\$&'\(\)\*\+,;=@a-zA-Z0-9]+)/n) {
+          '%'<<$1.unpack('H2'*$1.size).join('%').upcase
+        }.tr(' ', '+')
+      end
+      module_function :uri_escape
+
+      def uri_unescape(s)
+        gsub(/((?:%[0-9a-fA-F]{2})+)/n){
+          [$1.delete('%')].pack('H*')
+        }
+      end
+      module_function :uri_unescape
+
+    end
+  end
+end
+
+class Usher
+  class Generators
+    
+    class URL
+      
+      def initialize(usher)
+        @usher = usher
+      end
+
+      def generate_full(routing_lookup, request, params = nil)
+        path = path_for_routing_lookup(routing_lookup, params)
+        result = generate_start(path, request)
+        result << generate_path(path, params)
+      end
+
+      def generate(routing_lookup, params = nil)
+        generate_path(path_for_routing_lookup(routing_lookup, params), params)
+      end
+
+      def generate_start(path, request)
+        result = (path.route.generate_with && path.route.generate_with.scheme || request.scheme).dup
+        result << '://'
+        result << (path.route.generate_with && path.route.generate_with.host) ? path.route.generate_with.host : request.host
+        port = path.route.generate_with && path.route.generate_with.port || request.port
+        if result[4] == ?s
+          result << ':' << port.to_s if port != 443
+        else
+          result << ':' << port.to_s if port != 80
+        end
+        result
+      end
+
+      def path_for_routing_lookup(routing_lookup, params)
+        path = case routing_lookup
+        when Symbol
+          route = @usher.named_routes[routing_lookup] 
+          params.is_a?(Hash) ? route.find_matching_path(params) : route.paths.first
+        when Route
+          params.is_a?(Hash) ? routing_lookup.find_matching_path(params) : routing_lookup.paths.first
+        when nil
+          params.is_a?(Hash) ? @usher.path_for_options(params) : raise
+        when Route::Path
+          routing_lookup
+        end
+      end
+    
+      # 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_path(path, params = nil)
+        raise UnrecognizedException.new unless path
+
+        params = Array(params) if params.is_a?(String)
+        if params.is_a?(Array)
+          given_size = params.size
+          extra_params = params.last.is_a?(Hash) ? params.pop : nil
+          params = Hash[*path.dynamic_parts.inject([]){|a, dynamic_part| a.concat([dynamic_part.name, params.shift || raise(MissingParameterException.new("got #{given_size}, expected #{path.dynamic_parts.size} parameters"))]); a}]
+          params.merge!(extra_params) if extra_params
+        end
+
+        result = ''
+        path.parts.each do |part|
+          case part
+          when Route::Variable
+            value = (params && params.delete(part.name)) || part.default_value || raise(MissingParameterException.new)
+            case part.type
+            when :*
+              value.each_with_index do |current_value, index|
+                current_value = current_value.to_s unless current_value.is_a?(String)
+                part.valid!(current_value)
+                result << current_value
+                result << '/' if index != value.size - 1
+              end
+            when :':'
+              value = value.to_s unless value.is_a?(String)
+              part.valid!(value)
+              result << value
+            end
+          else
+            result << part
+          end
+        end
+        result = Rack::Utils.uri_escape(result)
+
+        if params && !params.empty?
+          has_query = result[??]
+          params.each do |k,v|
+            case v
+            when Array
+              v.each do |v_part|
+                result << (has_query ? '&' : has_query = true && '?') << Rack::Utils.escape("#{k.to_s}[]") << '=' << Rack::Utils.escape(v_part.to_s)
+              end
+            else
+              result << (has_query ? '&' : has_query = true && '?') << Rack::Utils.escape(k.to_s) << '=' << Rack::Utils.escape(v.to_s)
+            end
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/usher/grapher.rb

@@ -0,0 +1,65 @@
+class Usher
+  class Grapher
+
+    def initialize
+      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 = {}
+    end
+
+    def add_route(route)
+      route.paths.each do |path|
+        unless path.dynamic_keys.size.zero?
+          path.dynamic_keys.each do |k|
+            @orders[path.dynamic_keys.size][k] << path
+            @key_count[k] += 1
+          end
+          
+          dynamic_parts_with_defaults = path.dynamic_parts.select{|part| part.default_value }.map{|dp| dp.name}
+          dynamic_parts_without_defaults = path.dynamic_parts.select{|part| !part.default_value }.map{|dp| dp.name}
+
+          (1...(2 ** (dynamic_parts_with_defaults.size))).each do |i|
+            current_set = dynamic_parts_without_defaults.dup
+            dynamic_parts_with_defaults.each_with_index do |dp, index|
+              current_set << dp unless (index & i) == 0
+            end
+
+            current_set.each do |k|
+              @orders[current_set.size][k] << path
+              @key_count[k] += 1
+            end
+          end
+        end
+      end
+    end
+
+    def significant_keys
+      @significant_keys ||= @key_count.keys.uniq
+    end
+
+    def find_matching_path(params)
+      unless params.empty?
+        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 { |r| 
+              if r.can_generate_from?(set)
+                @cache[set] = r
+                return r
+              end
+            }
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/usher/interface/email_interface.rb

@@ -0,0 +1,27 @@
+class Usher
+  module Interface
+    class EmailInterface
+      
+      def initialize(&blk)
+        @routes = Usher.new(:delimiters => ['@', '-', '.'], :valid_regex => '[\+a-zA-Z0-9]+', :globs_capture_separators => true)
+        instance_eval(&blk) if blk
+      end
+      
+      def for(path, &block)
+        @routes.add_route(path).to(block)
+      end
+
+      def reset!
+        @routes.reset!
+      end
+
+      def act(email)
+        response = @routes.recognize(email, email)
+        if response.path
+          response.path.route.destination.call(response.params.inject({}){|h,(k,v)| h[k]=v.to_s; h })
+        end
+      end
+
+    end
+  end
+end

data/lib/usher/interface/merb_interface.rb

@@ -0,0 +1,61 @@
+require 'merb-core'
+require 'merb-core/dispatch/router/behavior'
+
+class Usher
+  module Interface
+    class MerbInterface
+      
+      # merb does everything with class methods.
+
+      @root_behavior   = ::Merb::Router::Behavior.new.defaults(:action => "index")
+
+      class << self
+        attr_accessor :root_behavior
+        
+        UsherRoutes = Usher.new
+        
+        def prepare(first = [], last = [], &block)
+          @routes = []
+          root_behavior._with_proxy(&block)
+          @routes = first + @routes + last
+          compile
+          self
+        end
+        
+        def compile
+          routes.each do |r| 
+            r.segments
+          end
+          
+          #puts r.inspect; UsherRoutes.add_route(r) }
+          #routes.each {|r| }
+        end
+        
+        def named_routes
+          UsherRoutes.named_routes
+        end
+        
+        def routes
+          UsherRoutes.routes
+        end
+
+        def route_for(request)
+          p request
+          p UsherRoutes.tree
+          UsherRoutes.recognize(request)
+        end
+        
+      end
+      
+      #class BootLoader < ::Merb::BootLoader
+      #end
+
+      def load_into_merb!
+        ::Merb.send(:remove_const, "Router")
+        ::Merb.const_set("Router", Usher::Interface::MerbInterface)
+        #::Merb::BootLoader.const_set("Router", Usher::Interface::Merb::BootLoader)
+      end
+      
+    end
+  end
+end

data/lib/usher/interface/rack_interface/route.rb

@@ -0,0 +1,9 @@
+class Usher
+  module Interface
+    class RackInterface
+      module Route
+        
+      end
+    end
+  end
+end

data/lib/usher/interface/rack_interface.rb

@@ -0,0 +1,37 @@
+require 'rack'
+
+class Usher
+  module Interface
+    class RackInterface
+      
+      attr_accessor :routes
+      
+      def initialize(&blk)
+        @routes = Usher.new(:request_methods => [:method, :host, :port, :scheme])
+        @generator = Usher::Generators::URL.new(@routes)
+        instance_eval(&blk) if blk
+      end
+      
+      def add(path, options = nil)
+        @routes.add_route(path, options)
+      end
+
+      def reset!
+        @routes.reset!
+      end
+
+      def call(env)
+        response = @routes.recognize(Rack::Request.new(env))
+        params = {}
+        response.params.each{ |hk| params[hk.first] = hk.last}
+        env['usher.params'] = params
+        response.path.route.destination.call(env)
+      end
+
+      def generate(route, params = nil, options = nil)
+        @generator.generate(route, params, options)
+      end
+
+    end
+  end
+end

data/lib/usher/interface/rails2_2_interface/mapper.rb

@@ -0,0 +1,44 @@
+class Usher
+  module Interface
+    class Rails2_2Interface
+      
+      class Mapper #:doc:
+        def initialize(set) #:nodoc:
+          @set = set
+        end
+
+        def connect(path, options = nil)
+          @set.add_route(path, options)
+        end
+
+        def root(options = {})
+          if options.is_a?(Symbol)
+            if source_route = @set.named_routes[options]
+              options = source_route.conditions.blank? ? 
+                source_route.options.merge({ :conditions => source_route.conditions }) : source_route.options
+            end
+          end
+          named_route(:root, '/', options)
+        end
+
+        def named_route(name, path, options = nil)
+          @set.add_named_route(name, path, options)
+        end
+
+        def namespace(name, options = {}, &block)
+          if options[:namespace]
+            with_options({:path_prefix => "#{options.delete(:path_prefix)}/#{name}", :name_prefix => "#{options.delete(:name_prefix)}#{name}_", :namespace => "#{options.delete(:namespace)}#{name}/" }.merge(options), &block)
+          else
+            with_options({:path_prefix => name, :name_prefix => "#{name}_", :namespace => "#{name}/" }.merge(options), &block)
+          end
+        end
+
+        def method_missing(route_name, *args, &proc) #:nodoc:
+          super unless args.length >= 1 && proc.nil?
+          @set.add_named_route(route_name, *args)
+        end
+      end
+
+    end
+  end
+end