roda 1.0.0 → 1.1.0

data/lib/roda/plugins/error_email.rb

@@ -0,0 +1,112 @@
+require 'net/smtp'
+
+class Roda
+  module RodaPlugins
+    # The error_email plugin adds an +error_email+ instance method that
+    # send an email related to the exception.  This is most useful if you are
+    # also using the error_handler plugin:
+    #
+    #   plugin :error_email, :to=>'to@example.com', :from=>'from@example.com'
+    #   plugin :error_handler do |e|
+    #     error_email(e)
+    #     'Internal Server Error'
+    #   end
+    #
+    # Options:
+    #
+    # :from :: The From address to use in the email (required)
+    # :headers :: A hash of additional headers to use in the email (default: empty hash)
+    # :host :: The SMTP server to use to send the email (default: localhost)
+    # :prefix :: A prefix to use in the email's subject line (default: no prefix)
+    # :to :: The To address to use in the email (required)
+    #
+    # The subject of the error email shows the exception class and message.
+    # The body of the error email shows the backtrace of the error and the
+    # request environment, as well the request params and session variables (if any).
+    #
+    # Note that emailing on every error as shown above is only appropriate
+    # for low traffic web applications.  For high traffic web applications,
+    # use an error reporting service instead of this plugin.
+    module ErrorEmail
+      DEFAULTS = {
+        :headers=>{},
+        :host=>'localhost',
+        # :nocov:
+        :emailer=>lambda{|h| Net::SMTP.start(h[:host]){|s| s.send_message(h[:message], h[:from], h[:to])}},
+        # :nocov:
+        :default_headers=>lambda do |h, e|
+          {'From'=>h[:from], 'To'=>h[:to], 'Subject'=>"#{h[:prefix]}#{e.class}: #{e.message}"}
+        end,
+        :body=>lambda do |s, e|
+          format = lambda{|h| h.map{|k, v| "#{k.inspect} => #{v.inspect}"}.sort.join("\n")}
+
+          message = <<END
+Path: #{s.request.full_path_info}
+
+Backtrace:
+
+#{e.backtrace.join("\n")}
+
+ENV:
+
+#{format[s.env]}
+END
+          unless s.request.params.empty?
+            message << <<END
+
+Params:
+
+#{format[s.request.params]}
+END
+          end
+
+          if s.env['rack.session']
+            message << <<END
+
+Session:
+
+#{format[s.session]}
+END
+          end
+
+          message
+        end
+      }
+
+      # Set default opts for plugin.  See ErrorEmail module RDoc for options.
+      def self.configure(app, opts={})
+        email_opts = app.opts[:error_email] ||= DEFAULTS
+        email_opts = email_opts.merge(opts)
+        unless email_opts[:to] && email_opts[:from]
+          raise RodaError, "must provide :to and :from options to error_email plugin"
+        end
+        app.opts[:error_email] = email_opts
+      end
+
+      module ClassMethods
+        # Dup the error email opts in the subclass so changes to the subclass do not affect
+        # the superclass.
+        def inherited(subclass)
+          super
+          subclass.opts[:error_email] = subclass.opts[:error_email].dup
+          subclass.opts[:error_email][:headers] = subclass.opts[:error_email][:headers].dup
+        end
+      end
+
+      module InstanceMethods
+        # Send an email for the given error.
+        def error_email(e)
+          email_opts = self.class.opts[:error_email].dup
+          headers = email_opts[:default_headers].call(email_opts, e)
+          headers = headers.merge(email_opts[:headers])
+          headers = headers.map{|k,v| "#{k}: #{v.gsub(/\r?\n/m, "\r\n ")}"}.sort.join("\r\n")
+          body = email_opts[:body].call(self, e)
+          email_opts[:message] = "#{headers}\r\n\r\n#{body}"
+          email_opts[:emailer].call(email_opts)
+        end
+      end
+    end
+
+    register_plugin(:error_email, ErrorEmail)
+  end
+end

data/lib/roda/plugins/flash.rb

@@ -26,6 +26,9 @@ class Roda
     #     end
     #   end
     module Flash
+      # The internal session key used to store the flash.
+      KEY = :_flash
+
       # Simple flash hash, where assiging to the hash updates the flash
       # used in the following request.
       class FlashHash < DelegateClass(Hash)
@@ -78,9 +81,6 @@ class Roda
       end
 
       module InstanceMethods
-        # The internal session key used to store the flash.
-        KEY = :_flash
-
         # Access the flash hash for the current request, loading
         # it from the session if it is not already loaded.
         def flash

data/lib/roda/plugins/hooks.rb

@@ -30,7 +30,7 @@ class Roda
     # handle cases where before hooks are added after the route block.
     module Hooks
       def self.configure(app)
-        @app.instance_exec do
+        app.instance_exec do
           @after ||= nil
           @before ||= nil
         end

data/lib/roda/plugins/indifferent_params.rb

@@ -30,9 +30,9 @@ class Roda
         def indifferent_params(params)
           case params 
           when Hash
-            h = Hash.new{|h, k| h[k.to_s] if Symbol === k}
-            params.each{|k, v| h[k] = indifferent_params(v)}
-            h
+            hash = Hash.new{|h, k| h[k.to_s] if Symbol === k}
+            params.each{|k, v| hash[k] = indifferent_params(v)}
+            hash
           when Array
             params.map{|x| indifferent_params(x)}
           else

data/lib/roda/plugins/middleware.rb

@@ -62,14 +62,9 @@ class Roda
       end
 
       module ClassMethods
-        # If an argument is given, this is a middleware app, so create a Forwarder.
-        # Otherwise, this is a usual instance creation, so call super.
-        def new(app=nil)
-          if app
-            Forwarder.new(self, app)
-          else
-            super()
-          end
+        # Create a Forwarder instead of a new instance.
+        def new(app)
+          Forwarder.new(self, app)
         end
 
         # Override the route block so that if no route matches, we throw so

data/lib/roda/plugins/multi_route.rb

@@ -51,35 +51,113 @@ class Roda
     #   r.multi_route do
     #     "default body"
     #   end
+    # 
+    # If a block is not provided to multi_route, the return value of the named
+    # route block will be used.
+    #
+    # == Routing Files
+    #
+    # The convention when using the multi_route plugin is to have a single
+    # named route per file, and these routing files should be stored in
+    # a routes subdirectory in your application.  So for the above example, you
+    # would use the following files:
+    #
+    #   routes/bar.rb
+    #   routes/foo.rb
+    #
+    # == Namespace Support
+    #
+    # The multi_route plugin also has support for namespaces, allowing you to
+    # use r.multi_route at multiple levels in your routing tree.  Example:
+    #
+    #   route('foo') do |r|
+    #     r.multi_route('foo')
+    #   end
+    #
+    #   route('bar') do |r|
+    #     r.multi_route('bar')
+    #   end
+    #
+    #   route('baz', 'foo') do |r|
+    #     # handles /foo/baz prefix
+    #   end
+    #
+    #   route('quux', 'foo') do |r|
+    #     # handles /foo/quux prefix
+    #   end
+    #
+    #   route('baz', 'bar') do |r|
+    #     # handles /bar/baz prefix
+    #   end
+    #
+    #   route('quux', 'bar') do |r|
+    #     # handles /bar/quux prefix
+    #   end
+    #
+    #   route do |r|
+    #     r.multi_route
+    #
+    #     # or
+    #
+    #     r.on "foo" do
+    #       r.on("baz"){r.route("baz", "foo")}
+    #       r.on("quux"){r.route("quux", "foo")}
+    #     end
+    #
+    #     r.on "bar" do
+    #       r.on("baz"){r.route("baz", "bar")}
+    #       r.on("quux"){r.route("quux", "bar")}
+    #     end
+    #   end
+    #
+    # === Routing Files
+    #
+    # The convention when using namespaces with the multi_route plugin is to
+    # store the routing files in subdirectories per namespace. So for the
+    # above example, you would have the following routing files:
+    #
+    #   routes/bar.rb
+    #   routes/bar/baz.rb
+    #   routes/bar/quux.rb
+    #   routes/foo.rb
+    #   routes/foo/baz.rb
+    #   routes/foo/quux.rb
     module MultiRoute
       # Initialize storage for the named routes.
       def self.configure(app)
-        app.instance_exec{@named_routes ||= {}}
+        app.instance_exec do
+          @namespaced_routes ||= {}
+          app::RodaRequest.instance_variable_set(:@namespaced_route_regexps, {})
+        end
       end
 
       module ClassMethods
         # Copy the named routes into the subclass when inheriting.
         def inherited(subclass)
           super
-          subclass.instance_variable_set(:@named_routes, @named_routes.dup)
+          nsr = subclass.instance_variable_set(:@namespaced_routes, {})
+          @namespaced_routes.each{|k, v| nsr[k] = v.dup}
+          subclass::RodaRequest.instance_variable_set(:@namespaced_route_regexps, {})
         end
 
-        # An names for the currently stored named routes
-        def named_routes
-          @named_routes.keys
+        # The names for the currently stored named routes
+        def named_routes(namespace=nil)
+          @namespaced_routes[namespace].keys
         end
 
         # Return the named route with the given name.
-        def named_route(name)
-          @named_routes[name]
+        def named_route(name, namespace=nil)
+          @namespaced_routes[namespace][name]
         end
 
-        # If the given route has a named, treat it as a named route and
+        # If the given route has a name, treat it as a named route and
         # store the route block.  Otherwise, this is the main route, so
         # call super.
-        def route(name=nil, &block)
+        def route(name=nil, namespace=nil, &block)
           if name
-            @named_routes[name] = block
+            @namespaced_routes[namespace] ||= {}
+            @namespaced_routes[namespace][name] = block
+            self::RodaRequest.clear_named_route_regexp!(namespace)
           else
             super(&block)
           end
@@ -87,9 +165,19 @@ class Roda
       end
 
       module RequestClassMethods
+        # Clear cached regexp for named routes, it will be regenerated
+        # the next time it is needed.
+        #
+        # This shouldn't be an issue in production applications, but
+        # during development it's useful to support new named routes
+        # being added while the application is running.
+        def clear_named_route_regexp!(namespace=nil)
+          @namespaced_route_regexps.delete(namespace)
+        end
+
         # A regexp matching any of the current named routes.
-        def named_route_regexp
-          @named_route_regexp ||= /(#{Regexp.union(roda_class.named_routes)})/
+        def named_route_regexp(namespace=nil)
+          @namespaced_route_regexps[namespace] ||= /(#{Regexp.union(roda_class.named_routes(namespace).select{|s| s.is_a?(String)}.sort.reverse)})/
         end
       end
 
@@ -98,16 +186,20 @@ class Roda
         # named routes.  If so, call that named route.  If not, do nothing.
         # If the named route does not handle the request, and a block
         # is given, yield to the block.
-        def multi_route
-          on self.class.named_route_regexp do |section|
-            route(section)
-            yield if block_given?
+        def multi_route(namespace=nil)
+          on self.class.named_route_regexp(namespace) do |section|
+            r = route(section, namespace)
+            if block_given?
+              yield
+            else
+              r
+            end
           end
         end
 
         # Dispatch to the named route with the given name.
-        def route(name)
-          scope.instance_exec(self, &self.class.roda_class.named_route(name))
+        def route(name, namespace=nil)
+          scope.instance_exec(self, &self.class.roda_class.named_route(name, namespace))
         end
       end
     end

data/lib/roda/plugins/not_allowed.rb

@@ -84,13 +84,13 @@ class Roda
           mod.class_eval(<<-END, __FILE__, __LINE__+1)
             def #{verb}(*args, &block)
               if args.empty?
-                @_is_verbs << "#{verb.to_s.upcase}" if @_is_verbs
+                @_is_verbs << "#{verb.to_s.upcase}" if defined?(@_is_verbs)
                 always(&block) if #{verb == :get ? :is_get : verb}?
               else
                 args << ::Roda::RodaPlugins::Base::RequestMethods::TERM
-                if_match(args) do |*args|
+                if_match(args) do |*a|
                   if #{verb == :get ? :is_get : verb}?
-                    block_result(yield(*args))
+                    block_result(yield(*a))
                     throw :halt, response.finish
                   end
                   response.status = 405

data/lib/roda/plugins/path.rb

@@ -0,0 +1,38 @@
+class Roda
+  module RodaPlugins
+    # The path plugin adds support for named paths.  Using the +path+ class method, you can
+    # easily create <tt>*_path</tt> instance methods for each named path.  Those instance
+    # methods can then be called if you need to get the path for a form action, link,
+    # redirect, or anything else.  Example:
+    #
+    #   plugin :path
+    #   path :foo, '/foo'
+    #   path :bar do |bar|
+    #     "/bar/#{bar.id}"
+    #   end
+    #
+    #   route do |r|
+    #     r.post 'bar' do
+    #       bar = Bar.create(r.params['bar'])
+    #       r.redirect bar_path(bar)
+    #     end
+    #   end
+    module Path
+      module ClassMethods
+        def path(name, path=nil, &block)
+          raise RodaError,  "cannot provide both path and block to Roda.path" if path && block
+          raise RodaError,  "must provide either path or block to Roda.path" unless path || block
+
+          if path
+            path = path.dup.freeze
+            block = lambda{path}
+          end
+
+          define_method("#{name}_path", &block)
+        end
+      end
+    end
+
+    register_plugin(:path, Path)
+  end
+end

data/lib/roda/plugins/render.rb

@@ -18,20 +18,18 @@ class Roda
     #     end
     #   end
     #
-    # You can provide options to the plugin method, or later by modifying
-    # +render_opts+.
+    # You can provide options to the plugin method:
     #
-    #   plugin :render, :engine=>'haml'
-    #
-    #   render_opts[:views] = 'admin_views'
+    #   plugin :render, :engine=>'haml', :views=>'admin_views'
     #
     # The following options are supported:
     #
     # :cache :: nil/false to not cache templates (useful for development), defaults
     #           to true to automatically use the default template cache.
     # :engine :: The tilt engine to use for rendering, defaults to 'erb'.
-    # :escape :: Use Roda's Erubis escaping support, which handles postfix
-    #            conditions inside <%= %> tags.
+    # :escape :: Use Roda's Erubis escaping support, which makes <%= %> escape output,
+    #            <%== %> not escape output, and handles postfix conditions inside
+    #            <%= %> tags.
     # :ext :: The file extension to assume for view files, defaults to the :engine
     #         option.
     # :layout :: The base name of the layout file, defaults to 'layout'.
@@ -69,23 +67,25 @@ class Roda
     # If you pass a hash as the first argument to +view+ or +render+, it should
     # have either +:inline+ or +:path+ as one of the keys.
     module Render
-      def self.load_dependencies(app, opts={})
+      OPTS={}.freeze
+
+      def self.load_dependencies(app, opts=OPTS)
         if opts[:escape]
           app.plugin :_erubis_escaping
         end
       end
 
       # Setup default rendering options.  See Render for details.
-      def self.configure(app, opts={})
+      def self.configure(app, opts=OPTS)
         if app.opts[:render]
           app.opts[:render].merge!(opts)
-        else 
+        else
           app.opts[:render] = opts.dup
         end
 
         opts = app.opts[:render]
         opts[:engine] ||= "erb"
-        opts[:ext] = nil unless opts.has_key?(:ext) 
+        opts[:ext] = nil unless opts.has_key?(:ext)
         opts[:views] ||= File.expand_path("views", Dir.pwd)
         opts[:layout] = "layout" unless opts.has_key?(:layout)
         opts[:layout_opts] ||= (opts[:layout_opts] || {}).dup
@@ -120,7 +120,7 @@ class Roda
 
       module InstanceMethods
         # Render the given template. See Render for details.
-        def render(template, opts = {}, &block)
+        def render(template, opts = OPTS, &block)
           if template.is_a?(Hash)
             if opts.empty?
               opts = template
@@ -143,10 +143,12 @@ class Roda
 
           cached_template(path) do
             template_class.new(path, 1, render_opts[:opts].merge(opts), &template_block)
-          end.render(self, opts[:locals], &block)
+          end.render(self, (opts[:locals]||OPTS), &block)
         end
 
-        # Return the render options for the instance's class.
+        # Return the render options for the instance's class. While this
+        # is not currently frozen, it may be frozen in a future version,
+        # so you should not attempt to modify it.
         def render_opts
           self.class.render_opts
         end
@@ -154,7 +156,7 @@ class Roda
         # Render the given template.  If there is a default layout
         # for the class, take the result of the template rendering
         # and render it inside the layout.  See Render for details.
-        def view(template, opts={})
+        def view(template, opts=OPTS)
           if template.is_a?(Hash)
             if opts.empty?
               opts = template
@@ -170,7 +172,7 @@ class Roda
               layout_opts = render_opts[:layout_opts].merge(layout_opts)
             end
 
-            content = render(layout, layout_opts||{}){content}
+            content = render(layout, layout_opts||OPTS){content}
           end
 
           content