usher 0.6.6 → 0.6.7

data/CHANGES.rdoc

@@ -1,5 +1,11 @@
 = Changelog
 
+== From 0.6.6 to 0.6.7
+
+* Added Usher::Interfaces::Rack#only_get. Convenience method for adding routes which respond to only get and not both head and get.
+* Made Usher::Interfaces::Rack take lots of configuration options and updated docs to reflect that. (As well as numerous other improved bits of docs.)
+* When route goes through Rack interface, insert Router into env. (right now its usher.router by default)
+
 == From 0.6.5 to 0.6.6
 
 * Faster recognition (~10%)

data/README.rdoc

@@ -14,6 +14,18 @@ Tree-based router library. Useful for (specifically) for Rails and Rack, but pro
 * Interface and implementation are separate, encouraging cross-pollination
 * Works in 1.9!
 
+== Projects using or other references to Usher
+
+* http://github.com/Tass/CRUDtree - RESTful resource mapper
+* http://github.com/padrino/padrino-framework - Web framework
+* http://github.com/botanicus/rango - Web framework
+* http://github.com/hassox/pancake - Web framework
+* http://github.com/eddanger/junior - Web framework
+* http://github.com/lifo/cramp - Web framework
+* 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:
@@ -139,17 +151,4 @@ In Sinatra, you get the extra method, +generate+, which lets you generate a url.
     "Hello World! #{generate(:hi)}"
   end
 
-== 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/VERSION.yml

@@ -2,4 +2,4 @@
 :build: 
 :major: 0
 :minor: 6
-:patch: 6
+:patch: 7

data/lib/usher/interface/rack.rb

@@ -7,7 +7,12 @@ class Usher
 
       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)
@@ -21,7 +26,10 @@ class Usher
         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
@@ -53,19 +61,33 @@ class Usher
         end
       end
 
-      attr_reader :router
+      attr_reader :router, :router_key
 
+      # Constructor for Rack interface for Usher. 
+      # <tt>app</tt> - the default application to route to if no matching route is found. The default is a 404 response.
+      # <tt>options</tt> - options to configure the router
+      # * <tt>use_destinations</tt> - option to disable using the destinations passed into routes. (Default <tt>true</tt>)
+      # * <tt>router_key</tt> - Key in which to put router into env. (Default <tt>usher.router</tt>)
+      # * <tt>request_methods</tt> - Request methods on <tt>Rack::Request</tt> to use in determining recognition. (Default <tt>[:request_method, :host, :port, :scheme]</tt>)
+      # * <tt>generator</tt> - Route generator to use. (Default <tt>Usher::Util::Generators::URL.new</tt>)
+      # * <tt>allow_identical_variable_names</tt> - Option to prevent routes with identical variable names to be added. eg, /:variable/:variable would raise an exception if this option is not enabled. (Default <tt>false</tt>)
       def initialize(app = nil, options = nil, &blk)
-        @_app = app || lambda { |env| ::Rack::Response.new("No route found", 404).finish }
-        @router = Usher.new(:request_methods => [:request_method, :host, :port, :scheme], :generator => Usher::Util::Generators::URL.new, :allow_identical_variable_names => false)
+        @_app = app || proc{|env| ::Rack::Response.new("No route found", 404).finish }
         @use_destinations = options && options.key?(:use_destinations) ? options[:use_destinations] : true
+        @router_key = options && options[:router_key] || ENV_KEY_DEFAULT_ROUTER
+        request_methods = options && options[:request_methods] || [:request_method, :host, :port, :scheme]
+        generator = options && options[:generator] || Usher::Util::Generators::URL.new
+        allow_identical_variable_names = options && options.key(:allow_identical_variable_names) ? options[:allow_identical_variable_names] : false
+        @router = Usher.new(:request_methods => request_methods, :generator => generator, :allow_identical_variable_names => allow_identical_variable_names)
         instance_eval(&blk) if blk
       end
-
+      
+      # Returns whether the route set has use_destinations? enabled.
       def use_destinations?
         @use_destinations
       end
 
+      # Creates a deep copy of the current route set.
       def dup
         new_one = super
         original = self
@@ -74,12 +96,16 @@ class Usher
         end
         new_one
       end
-
+      
+      # Adds a route to the route set with a +path+ and optional +options+.
+      # See <tt>Usher#add_route</tt> for more details about the format of the route and options accepted here.
       def add(path, options = nil)
         @router.add_route(path, options)
       end
       alias_method :path, :add
 
+      # Sets the default application when route matching is unsuccessful. Accepts either an application +app+ or a block to call.
+      #
       # default { |env| ... }
       # default DefaultApp
       def default(app = nil, &block)
@@ -93,20 +119,30 @@ class Usher
 
       # 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
+
+      # Convenience method for adding a route that only matches request method +GET+.
+      def only_get(path, options = {})
+        add(path, options.merge!(:conditions => {:request_method => ["GET"]}))
+      end
+
+      # Convenience method for adding a route that only matches request methods +GET+ and +HEAD+.
       def get(path, options = {})
-        self.add(path, options.merge!(:conditions => {:request_method => ["HEAD", "GET"]}))
+        add(path, options.merge!(:conditions => {:request_method => ["HEAD", "GET"]}))
       end
 
+      # Convenience method for adding a route that only matches request method +POST+.
       def post(path, options = {})
-        self.add(path, options.merge!(:conditions => {:request_method => "POST"}))
+        add(path, options.merge!(:conditions => {:request_method => "POST"}))
       end
 
+      # Convenience method for adding a route that only matches request method +PUT+.
       def put(path, options = {})
-        self.add(path, options.merge!(:conditions => {:request_method => "PUT"}))
+        add(path, options.merge!(:conditions => {:request_method => "PUT"}))
       end
 
+      # Convenience method for adding a route that only matches request method +DELETE+.
       def delete(path, options = {})
-        self.add(path, options.merge!(:conditions => {:request_method => "DELETE"}))
+        add(path, options.merge!(:conditions => {:request_method => "DELETE"}))
       end
 
       def parent_route=(route)
@@ -122,6 +158,7 @@ class Usher
       end
 
       def call(env)
+        env[router_key] = self
         request = ::Rack::Request.new(env)
         response = @router.recognize(request, request.path_info)
         after_match(request, response) if response
@@ -161,6 +198,8 @@ class Usher
       def determine_respondant(response)
         if use_destinations? && response && response.destination && response.destination.respond_to?(:call)
           response.destination
+        elsif use_destinations? && response && response.destination && response.destination.respond_to?(:args) && response.destination.args.first.respond_to?(:call)
+          response.args.first
         else
           _app
         end

data/lib/usher/interface/rails23.rb

@@ -92,45 +92,45 @@ class Usher
         Array(destinations).each do |d| d.module_eval { include Helpers }
           @router.named_routes.keys.each do |name|
             @module.module_eval <<-end_eval # We use module_eval to avoid leaks
-            def #{name}_url(options = {})
-              ActionController::Routing::UsherRoutes.generate(options, {}, :generate, :#{name})
-                                                              end
-                                                              end_eval
-                                                              end
-                                                              d.__send__(:include, @module)
-                                                              end
-                                                              end
-
-                                                              def generate(options, recall = {}, method = :generate, route_name = nil)
-                                                                route = if(route_name)
-                                                                  @router.named_routes[route_name]
-                                                                else
-                                                                  merged_options = options
-                                                                  merged_options[:controller] = recall[:controller] unless options.key?(:controller)
-                                                                  unless options.key?(:action)
-                                                                    options[:action] = ''
-                                                                  end
-                                                                  path_for_options(merged_options)
-                                                                end
-                                                                case method
-                                                                  when :generate
-                                                                    merged_options ||= recall.merge(options)
-                                                                    url = generate_url(route, merged_options)
-                                                                    url.slice!(-1) if url[-1] == ?/
-                                                                    url
-                                                                  else
-                                                                    raise "method #{method} not recognized"
-                                                                end
-                                                              end
-
-                                                              def generate_url(route, params)
-                                                                @router.generator.generate(route, params)
-                                                              end
-
-                                                              def path_for_options(options)
-                                                                @router.path_for_options(options)
-                                                              end
-
-                                                              end
-                                                              end
-                                                              end
+              def #{name}_url(options = {})
+                ActionController::Routing::UsherRoutes.generate(options, {}, :generate, :#{name})
+              end
+            end_eval
+          end
+          d.__send__(:include, @module)
+        end
+      end
+
+      def generate(options, recall = {}, method = :generate, route_name = nil)
+        route = if(route_name)
+          @router.named_routes[route_name]
+        else
+          merged_options = options
+          merged_options[:controller] = recall[:controller] unless options.key?(:controller)
+          unless options.key?(:action)
+            options[:action] = ''
+          end
+          path_for_options(merged_options)
+        end
+        case method
+          when :generate
+            merged_options ||= recall.merge(options)
+            url = generate_url(route, merged_options)
+            url.slice!(-1) if url[-1] == ?/
+            url
+          else
+            raise "method #{method} not recognized"
+        end
+      end
+
+      def generate_url(route, params)
+        @router.generator.generate(route, params)
+      end
+
+      def path_for_options(options)
+        @router.path_for_options(options)
+      end
+
+    end
+  end
+end

data/lib/usher/route/path.rb

@@ -54,7 +54,6 @@ class Usher
 
       def can_generate_from_params?(params)
         if route.router.consider_destination_keys?
-          route.destination.to_a - params.to_a
           (route.destination.to_a - params.to_a).size.zero?
         end
       end
@@ -66,10 +65,10 @@ class Usher
       end
 
       private
-        def parts=(parts)
-          @parts = parts
-          @dynamic = @parts.any?{|p| p.is_a?(Variable)}
-        end
+      def parts=(parts)
+        @parts = parts
+        @dynamic = @parts.any?{|p| p.is_a?(Variable)}
+      end
 
     end
   end

data/lib/usher/splitter.rb

@@ -10,12 +10,14 @@ class Usher
 
     class SingleCharacterSplitterInstance
     
+      attr_reader :url_split_regex
+    
       def initialize(delimiters)
-        @url_split_regex = Regexp.new("[#{delimiters.collect{|d| Regexp.quote(d)}.join}]|[^#{delimiters.collect{|d| Regexp.quote(d)}.join}]+")
+        @url_split_regex = Regexp.new("[^#{delimiters.collect{|d| Regexp.quote(d)}.join}]+|[#{delimiters.collect{|d| Regexp.quote(d)}.join}]")
       end
       
       def split(path)
-        path.scan(@url_split_regex)
+        path.scan(url_split_regex)
       end
     end
     

data/lib/usher/util.rb

@@ -2,7 +2,5 @@ class Usher
   module Util
     autoload :Generators, File.join('usher', 'util', 'generate')
     autoload :Parser,     File.join('usher', 'util', 'parser')
-    autoload :Graph,      File.join('usher', 'util', 'graph')
-    autoload :Mapper,     File.join('usher', 'util', 'mapper')
   end
 end

data/lib/usher/util/generate.rb

@@ -137,8 +137,8 @@ class Usher
             extra_params = params.last.is_a?(Hash) ? params.pop : nil
             raise MissingParameterException.new("got #{params.size}, expected #{path.dynamic_parts.size} parameters") unless path.dynamic_parts.size == params.size
           end
-          
-          result = Rack::Utils.uri_escape(generate_path_for_base_params(path, params))
+          result = generate_path_for_base_params(path, params)
+          Rack::Utils.uri_escape!(result)
           
           params = extra_params if extra_params
           

data/lib/usher/util/mapper.rb

@@ -6,6 +6,12 @@ class Usher
         @router = router
       end
       
+      def with(prefix, options = nil)
+        
+        
+        
+      end
+      
     end
   end
 end

data/lib/usher/util/rack-mixins.rb

@@ -12,6 +12,13 @@ unless Rack::Utils.respond_to?(:uri_escape)
       end
       module_function :uri_escape
 
+      def uri_escape!(s)
+        s.to_s.gsub!(/([^:\/?\[\]\-_~\.!\$&'\(\)\*\+,;=@a-zA-Z0-9]+)/n) {
+          '%'<<$1.unpack('H2'*$1.size).join('%').upcase
+        }
+      end
+      module_function :uri_escape!
+
       def uri_unescape(s)
         gsub(/((?:%[0-9a-fA-F]{2})+)/n){
           [$1.delete('%')].pack('H*')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: usher
 version: !ruby/object:Gem::Version 
-  version: 0.6.6
+  version: 0.6.7
 platform: ruby
 authors: 
 - Daniel Neighman
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-15 00:00:00 -05:00
+date: 2010-01-24 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency