roda 2.2.0 → 2.3.0

data/lib/roda/plugins/mailer.rb

@@ -87,6 +87,14 @@ class Roda
     #     ""
     #   end
     #
+    # If while preparing the email you figure out you don't want to send an
+    # email, call +no_mail!+:
+    #
+    #  r.mail '/welcome/:d' do |id| 
+    #    no_mail! unless user = User[id]
+    #    # ...
+    #  end
+    #
     # By default, the mailer uses text/plain as the Content-Type for emails.
     # You can override the default by specifying a :content_type option when
     # loading the plugin:
@@ -128,15 +136,19 @@ class Roda
         # calling +deliver+ to send the mail.
         def mail(path, *args)
           mail = ::Mail.new
-          unless mail.equal?(new(PATH_INFO=>path, SCRIPT_NAME=>EMPTY_STRING, REQUEST_METHOD=>MAIL, RACK_INPUT=>StringIO.new, RODA_MAIL=>mail, RODA_MAIL_ARGS=>args).call(&route_block))
-            raise Error, "route did not return mail instance for #{path.inspect}, #{args.inspect}"
+          catch(:no_mail) do
+            unless mail.equal?(new(PATH_INFO=>path, SCRIPT_NAME=>EMPTY_STRING, REQUEST_METHOD=>MAIL, RACK_INPUT=>StringIO.new, RODA_MAIL=>mail, RODA_MAIL_ARGS=>args).call(&route_block))
+              raise Error, "route did not return mail instance for #{path.inspect}, #{args.inspect}"
+            end
+            mail
           end
-          mail
         end
 
         # Calls +mail+ and immediately sends the resulting mail.
         def sendmail(*args)
-          mail(*args).deliver
+          if m = mail(*args)
+            m.deliver
+          end
         end
       end
 
@@ -149,7 +161,7 @@ class Roda
         def mail(*args)
           if @env[REQUEST_METHOD] == MAIL
             if_match(args) do |*vs|
-              yield *(vs + @env[RODA_MAIL_ARGS])
+              yield(*(vs + @env[RODA_MAIL_ARGS]))
             end
           end
         end
@@ -232,6 +244,11 @@ class Roda
           nil
         end
 
+        # Signal that no mail should be sent for this request.
+        def no_mail!
+          throw :no_mail
+        end
+
         private
 
         # Set the text_part or html_part (depending on the method) in the related email,

data/lib/roda/plugins/named_templates.rb

@@ -79,9 +79,9 @@ class Roda
         def find_template(options)
           if options[:template] && (template_opts, block = opts[:named_templates][template_name(options)]; block)
             if template_opts
-              options = template_opts.merge(options)
+              options = Hash[template_opts].merge!(options)
             else
-              options = options.dup
+              options = Hash[options]
             end
 
             options[:inline] = instance_exec(&block)

data/lib/roda/plugins/path_rewriter.rb

@@ -0,0 +1,82 @@
+class Roda
+  module RodaPlugins
+    # The path_rewriter plugin allows you to rewrite the remaining path
+    # or the path info for requests.  This is useful if you want to
+    # transparently treat some paths the same as other paths.
+    #
+    # By default, +rewrite_path+ will rewrite just the remaining path.  So
+    # only routing in the current Roda app will be affected.  This is useful
+    # if you have other code in your app that uses PATH_INFO and needs to
+    # see the original PATH_INFO (for example, when using relative links).
+    #
+    #   rewrite_path '/a', '/b'
+    #   # PATH_INFO '/a' => remaining_path '/b'
+    #   # PATH_INFO '/a/c' => remaining_path '/b/c'
+    #
+    # In some cases, you may want to override PATH_INFO for the rewritten
+    # paths, such as when you are passing the request to another Rack app.
+    # For those cases, you can use the <tt>:path_info => true</tt> option to
+    # +rewrite_path+.
+    #
+    #   rewrite_path '/a', '/b', :path_info => true
+    #   # PATH_INFO '/a' => PATH_INFO '/b'
+    #   # PATH_INFO '/a/c' => PATH_INFO '/b/c'
+    #
+    # If you pass a string to +rewrite_path+, it will rewrite all paths starting
+    # with that string.  You can provide a regexp if you want more complete control,
+    # such as only matching exact paths.
+    #
+    #   rewrite_path /\A\/a\z/, '/b'
+    #   # PATH_INFO '/a' => remaining_path '/b'
+    #   # PATH_INFO '/a/c' => remaining_path '/a/c', no change
+    #
+    # All path rewrites are applied in order, so if a path is rewritten by one rewrite,
+    # it can be rewritten again by a later rewrite.  Note that PATH_INFO rewrites are
+    # processed before remaining_path rewrites.
+    module PathRewriter
+      PATH_INFO = 'PATH_INFO'.freeze
+      OPTS={}.freeze
+
+      def self.configure(app)
+        app.instance_exec do
+          app.opts[:remaining_path_rewrites] ||= []
+          app.opts[:path_info_rewrites] ||= []
+        end
+      end
+
+      module ClassMethods
+        # Freeze the path rewrite metadata.
+        def freeze
+          opts[:remaining_path_rewrites].freeze
+          opts[:path_info_rewrites].freeze
+          super
+        end
+
+        # Record a path rewrite from path +was+ to path +is+.  Options:
+        # :path_info :: Modify PATH_INFO, not just remaining path.
+        def rewrite_path(was, is, opts=OPTS)
+          was = /\A#{Regexp.escape(was)}/ unless was.is_a?(Regexp)
+          array = @opts[opts[:path_info] ? :path_info_rewrites : :remaining_path_rewrites]
+          array << [was, is.dup.freeze].freeze
+        end
+      end
+
+      module RequestMethods
+        # Rewrite remaining_path and/or PATH_INFO based on the path rewrites.
+        def initialize(scope, env)
+          path_info = env[PATH_INFO]
+          scope.class.opts[:path_info_rewrites].each do |was, is|
+            path_info.sub!(was, is)
+          end
+          super
+          remaining_path = @remaining_path = @remaining_path.dup
+          scope.class.opts[:remaining_path_rewrites].each do |was, is|
+            remaining_path.sub!(was, is)
+          end
+        end
+      end
+    end
+
+    register_plugin(:path_rewriter, PathRewriter)
+  end
+end

data/lib/roda/plugins/precompile_templates.rb

@@ -0,0 +1,87 @@
+class Roda
+  module RodaPlugins
+    # The precompile_templates plugin adds support for precompiling template code.
+    # This can result in a large memory savings for applications that have large
+    # templates or a large number of small templates if the application uses a
+    # forking webserver.  By default, template compilation is lazy, so all the
+    # child processes in a forking webserver will have their own copy of the
+    # compiled template.  By using the precompile_templates plugin, you can
+    # precompile the templates in the parent process before forking, and then
+    # all of the child processes can use the same precompiled templates, which
+    # saves memory.
+    #
+    # After loading the plugin, you can call +precompile_templates+ with
+    # the pattern of templates you would like to precompile:
+    #
+    #   plugin :precompile_templates
+    #   precompile_templates "views/\*\*/*.erb"
+    #
+    # That will precompile all erb template files in the views directory or
+    # any subdirectory.
+    #
+    # If the templates use local variables, you need to specify which local
+    # variables to precompile, which should be an array of symbols:
+    #
+    #   precompile_templates 'views/users/_*.erb', :locals=>[:user]
+    #
+    # Note that if you have multiple local variables and are not using a Tilt
+    # version greater than 2.0.1, you should specify the :locals option in the
+    # same order as the keys in the :locals hash you pass to render/view.  Since
+    # hashes are not ordered in ruby 1.8, you should not attempt to precompile
+    # templates that use :locals on ruby 1.8 unless you are using a Tilt version
+    # greater than 2.0.1.  If you are running the Tilt master branch, you can
+    # force sorting of locals using the +:sort_locals+ option when loading the
+    # plugin.
+    #
+    # You can specify other render options when calling +precompile_templates+,
+    # including +:cache_key+, +:template_class+, and +:template_opts+.  If you
+    # are passing any of those options to render/view for the template, you
+    # should pass the same options when precompiling the template.
+    #
+    # To compile inline templates, just pass a single hash containing an :inline
+    # to +precompile_templates+:
+    #
+    #   precompile_templates :inline=>some_template_string
+    module PrecompileTemplates
+      OPTS = {}.freeze
+
+      # Load the render plugin as precompile_templates depends on it.
+      # Default to sorting the locals if the Tilt version is greater than 2.0.1.
+      def self.load_dependencies(app, opts=OPTS)
+        app.plugin :render
+        app.opts[:precompile_templates_sort] = opts.fetch(:sort_locals, Tilt::VERSION > '2.0.1')
+      end
+
+      module ClassMethods
+        # Precompile the templates using the given options.  See PrecompileTemplates
+        # for details.
+        def precompile_templates(pattern, opts=OPTS)
+          if pattern.is_a?(Hash)
+            opts = pattern.merge(opts)
+          end
+
+          locals = opts[:locals] || []
+          if locals && self.opts[:precompile_templates_sort]
+            locals = locals.sort{|x,y| x.to_s <=> y.to_s}
+          end
+
+          compile_opts = if pattern.is_a?(Hash)
+            [opts]
+          else
+            Dir[pattern].map{|file| opts.merge(:path=>File.expand_path(file))}
+          end
+
+          instance = allocate
+          compile_opts.each do |compile_opt|
+            template = instance.send(:retrieve_template, compile_opt)
+            template.send(:compiled_method, locals)
+          end
+
+          nil
+        end
+      end
+    end
+
+    register_plugin(:precompile_templates, PrecompileTemplates)
+  end
+end

data/lib/roda/plugins/render.rb

@@ -22,12 +22,15 @@ class Roda
     #
     #   plugin :render, :engine=>'haml', :views=>'admin_views'
     #
-    # The following options are supported:
+    # = Plugin Options
+    #
+    # The following plugin options are supported:
     #
     # :cache :: nil/false to not cache templates (useful for development), defaults
     #           to true unless RACK_ENV is development to automatically use the
     #           default template cache.
-    # :engine :: The tilt engine to use for rendering, defaults to 'erb'.
+    # :engine :: The tilt engine to use for rendering, also the default file extension for
+    #            templates, defaults to 'erb'.
     # :escape :: Use Roda's Erubis escaping support, which makes <tt><%= %></tt> escape output,
     #            <tt><%== %></tt> not escape output, and handles postfix conditions inside
     #            <tt><%= %></tt> tags.
@@ -36,25 +39,32 @@ class Roda
     # :escaper :: Object used for escaping output of <tt><%= %></tt>, when :escape is used,
     #             overriding the default.  If given, object should respond to +escape_xml+ with
     #             a single argument and return an output string.
-    # :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'.
     # :layout_opts :: The options to use when rendering the layout, if different
     #                 from the default options.
-    # :template_opts :: The tilt options used when rendering templates, defaults to
-    #                   <tt>{:outvar=>'@_out_buf', :default_encoding=>Encoding.default_external}</tt>.
+    # :template_opts :: The tilt options used when rendering all templates. defaults to:
+    #                 <tt>{:outvar=>'@_out_buf', :default_encoding=>Encoding.default_external}</tt>.
+    # :engine_opts :: The tilt options to use per template engine.  Keys are
+    #                 engine strings, values are hashes of template options.
     # :views :: The directory holding the view files, defaults to the 'views' subdirectory of the
     #           application's :root option (the process's working directory by default).
     #
+    # = Render/View Method Options
+    #
     # Most of these options can be overridden at runtime by passing options
     # to the +view+ or +render+ methods:
     #
-    #   view('foo', :ext=>'html.erb')
+    #   view('foo', :engine=>'html.erb')
     #   render('foo', :views=>'admin_views')
     #
-    # There are a couple of additional options to +view+ and +render+ that are
+    # There are additional options to +view+ and +render+ that are
     # available at runtime:
     #
+    # :cache :: Set to false to not cache this template, even when
+    #           caching is on by default.  Set to true to force caching for
+    #           this template, even when the default is to not cache (e.g.
+    #           when using the :template_block option).
+    # :cache_key :: Explicitly set the hash key to use when caching.
     # :content :: Only respected by +view+, provides the content to render
     #             inside the layout, instead of rendering a template to get
     #             the content.
@@ -62,13 +72,14 @@ class Roda
     #            for template code in a file.
     # :locals :: Hash of local variables to make available inside the template.
     # :path :: Use the value given as the full pathname for the file, instead
-    #          of using the :views and :ext option in combination with the
+    #          of using the :views and :engine option in combination with the
     #          template name.
     # :template :: Provides the name of the template to use.  This allows you
     #              pass a single options hash to the render/view method, while
     #              still allowing you to specify the template name.
     # :template_block :: Pass this block when creating the underlying template,
-    #                    ignored when using :inline.
+    #                    ignored when using :inline.  Disables caching of the
+    #                    template by default.
     # :template_class :: Provides the template class to use, inside of using
     #                    Tilt or <tt>Tilt[:engine]</tt>.
     #
@@ -80,6 +91,27 @@ class Roda
     # If you pass a hash as the first argument to +view+ or +render+, it should
     # have either +:template+, +:inline+, +:path+, or +:content+ (for +view+) as
     # one of the keys.
+    #
+    # = Speeding Up Template Rendering
+    #
+    # By default, determining the cache key to use for the template can be a lot
+    # of work.  If you specify the +:cache_key+ option, you can save Roda from
+    # having to do that work, which will make your application faster.  However,
+    # if you do this, you need to make sure you choose a correct key.
+    #
+    # If your application uses a unique template per path, in that the same
+    # path never uses more than one template, you can use the +view_options+ plugin
+    # and do:
+    #
+    #   set_view_options :cache_key=>r.path_info
+    #
+    # at the top of your route block.  You can even do this if you do have paths
+    # that use more than one template, as long as you specify +:cache_key+
+    # specifically when rendering in those paths.
+    #
+    # If you use a single layout in your application, you can also make layout
+    # rendering faster by specifying +:cache_key+ inside the +:layout_opts+
+    # plugin option.
     module Render
       OPTS={}.freeze
 
@@ -98,12 +130,12 @@ class Roda
         app.opts[:render][:orig_opts] = opts
 
         opts = app.opts[:render]
-        opts[:engine] ||= "erb"
-        opts[:ext] = nil unless opts.has_key?(:ext)
-        opts[:views] = File.expand_path(opts[:views]||"views", app.opts[:root])
+        opts[:engine] = (opts[:engine] || opts[:ext] || "erb").dup.freeze
+        opts[:views] = File.expand_path(opts[:views]||"views", app.opts[:root]).freeze
+        opts[:cache] = app.thread_safe_cache if opts.fetch(:cache, ENV['RACK_ENV'] != 'development')
+
         opts[:layout_opts] = (opts[:layout_opts] || {}).dup
         opts[:layout_opts][:_is_layout] = true
-
         if layout = opts.fetch(:layout, true)
           opts[:layout] = true unless opts.has_key?(:layout)
 
@@ -116,6 +148,7 @@ class Roda
             opts[:layout_opts][:template] = layout
           end
         end
+        opts[:layout_opts].freeze
 
         template_opts = opts[:template_opts] = (opts[:template_opts] || {}).dup
         template_opts[:outvar] ||= '@_out_buf'
@@ -131,9 +164,14 @@ class Roda
             ::Erubis::XmlHelper
           end
         end
-        opts[:cache] = app.thread_safe_cache if opts.fetch(:cache, ENV['RACK_ENV'] != 'development')
-        opts[:layout_opts].freeze
-        opts[:template_opts].freeze
+        template_opts.freeze
+
+        engine_opts = opts[:engine_opts] = (opts[:engine_opts] || {}).dup
+        engine_opts.to_a.each do |k,v|
+          engine_opts[k] = v.dup.freeze
+        end
+        engine_opts.freeze
+
         opts.freeze
       end
 
@@ -157,13 +195,9 @@ class Roda
       module InstanceMethods
         # Render the given template. See Render for details.
         def render(template, opts = OPTS, &block)
-          opts = find_template(parse_template_opts(template, opts))
-          cached_template(opts) do
-            template_opts = render_opts[:template_opts]
-            current_template_opts = opts[:template_opts]
-            template_opts = template_opts.merge(current_template_opts) if current_template_opts
-            opts[:template_class].new(opts[:path], 1, template_opts, &opts[:template_block])
-          end.render(self, (opts[:locals]||OPTS), &block)
+          opts = parse_template_opts(template, opts)
+          merge_render_locals(opts)
+          retrieve_template(opts).render(self, (opts[:locals]||OPTS), &block)
         end
 
         # Return the render options for the instance's class. While this
@@ -196,8 +230,7 @@ class Roda
         # If caching templates, attempt to retrieve the template from the cache.  Otherwise, just yield
         # to get the template.
         def cached_template(opts, &block)
-          if cache = render_opts[:cache]
-            key = opts[:key]
+          if (cache = render_opts[:cache]) && (key = opts[:cache_key])
             unless template = cache[key]
               template = cache[key] = yield
             end
@@ -210,49 +243,86 @@ class Roda
         # Given the template name and options, set the template class, template path/content,
         # template block, and locals to use for the render in the passed options.
         def find_template(opts)
+          render_opts = render_opts()
+          engine_override = opts[:engine] ||= opts[:ext]
+          engine = opts[:engine] ||= render_opts[:engine]
           if content = opts[:inline]
             path = opts[:path] = content
-            template_class = opts[:template_class] ||= ::Tilt[opts[:engine] || render_opts[:engine]]
+            template_class = opts[:template_class] ||= ::Tilt[engine]
             opts[:template_block] = Proc.new{content}
           else
+            opts[:views] ||= render_opts[:views]
             path = opts[:path] ||= template_path(opts)
             template_class = opts[:template_class]
             opts[:template_class] ||= ::Tilt
           end
 
           if render_opts[:cache]
-            template_opts = opts[:template_opts]
-            template_block = opts[:template_block] if !content
+            if (cache = opts[:cache]).nil?
+              cache = content || !opts[:template_block]
+            end
+
+            if cache
+              template_block = opts[:template_block] unless content
+              template_opts = opts[:template_opts]
 
-            key = if template_class || template_opts || template_block
-              [path, template_class, template_opts, template_block]
+              opts[:cache_key] ||= if template_class || engine_override || template_opts || template_block
+                [path, template_class, engine_override, template_opts, template_block]
+              else
+                path
+              end
             else
-              path
+              opts.delete(:cache_key)
             end
-            opts[:key] = key
           end
 
+          opts
+        end
+
+        # Merge any :locals specified in the render_opts into the :locals option given.
+        def merge_render_locals(opts)
           if !opts[:_is_layout] && (r_locals = render_opts[:locals])
             opts[:locals] = if locals = opts[:locals]
-              r_locals.merge(locals)
+              Hash[r_locals].merge!(locals)
             else
               r_locals
             end
           end
-
-          opts
         end
 
         # Return a single hash combining the template and opts arguments.
         def parse_template_opts(template, opts)
-          template = {:template=>template} unless template.is_a?(Hash)
-          opts.merge(template)
+          opts = Hash[opts]
+          if template.is_a?(Hash)
+            opts.merge!(template)
+          else
+            opts[:template] = template
+            opts
+          end
         end
 
         # The default render options to use.  These set defaults that can be overridden by
         # providing a :layout_opts option to the view/render method.
         def render_layout_opts
-          render_opts[:layout_opts].dup
+          Hash[render_opts[:layout_opts]]
+        end
+
+        # Retrieve the Tilt::Template object for the given template and opts.
+        def retrieve_template(opts)
+          unless opts[:cache_key] && opts[:cache] != false
+            found_template_opts = opts = find_template(opts)
+          end
+          cached_template(opts) do
+            opts = found_template_opts || find_template(opts)
+            template_opts = render_opts[:template_opts]
+            if engine_opts = render_opts[:engine_opts][opts[:engine]]
+              template_opts = Hash[template_opts].merge!(engine_opts)
+            end
+            if current_template_opts = opts[:template_opts]
+              template_opts = Hash[template_opts].merge!(current_template_opts)
+            end
+            opts[:template_class].new(opts[:path], 1, template_opts, &opts[:template_block])
+          end
         end
 
         # The name to use for the template.  By default, just converts the :template option to a string.
@@ -262,8 +332,7 @@ class Roda
 
         # The template path for the given options.
         def template_path(opts)
-          render_opts = render_opts()
-          "#{opts[:views] || render_opts[:views]}/#{template_name(opts)}.#{opts[:ext] || render_opts[:ext] || render_opts[:engine]}"
+          "#{opts[:views]}/#{template_name(opts)}.#{opts[:engine]}"
         end
 
         # If a layout should be used, return a hash of options for
@@ -274,7 +343,7 @@ class Roda
             layout_opts = render_layout_opts
             if l_opts = opts[:layout_opts]
               if (l_locals = l_opts[:locals]) && (layout_locals = layout_opts[:locals])
-                set_locals = layout_locals.merge(l_locals)
+                set_locals = Hash[layout_locals].merge!(l_locals)
               end
               layout_opts.merge!(l_opts)
               if set_locals
@@ -294,7 +363,6 @@ class Roda
             layout_opts
           end
         end
-
       end
     end