roda 2.0.0 → 2.1.0

data/lib/roda/plugins/delegate.rb

@@ -21,21 +21,24 @@ class Roda
     #
     #     # /hello branch
     #     on "hello" do
+    #       # Set variable for all routes in /hello branch
+    #       @greeting = 'Hello'
+    #
     #       # GET /hello/world request
     #       get "world" do
-    #         "Hello world!"
+    #         "#{@greeting} world!"
     #       end
     #
     #       # /hello request
     #       is do
     #         # GET /hello request
     #         get do
-    #           "Hello!"
+    #           "#{@greeting}!"
     #         end
     #
     #         # POST /hello request
     #         post do
-    #           puts "Someone said hello!"
+    #           puts "Someone said #{@greeting}!"
     #           redirect
     #         end
     #       end

data/lib/roda/plugins/indifferent_params.rb

@@ -14,6 +14,13 @@ class Roda
     # The params hash is initialized lazily, so you only pay
     # the penalty of copying the request params if you call
     # the +params+ method.
+    #
+    # Note that there is a rack-indifferent gem that
+    # automatically makes rack use indifferent params. Using
+    # rack-indifferent is faster and has some other minor
+    # advantages over the indifferent_params plugin, though
+    # it affects rack itself instead of just the Roda app that
+    # you load the plugin into.
     module IndifferentParams
       module InstanceMethods
         # A copy of the request params that will automatically

data/lib/roda/plugins/mailer.rb

@@ -168,6 +168,10 @@ class Roda
             header_content_type = @headers.delete(CONTENT_TYPE)
             m.headers(@headers)
             m.body(@body.join) unless @body.empty?
+            mail_attachments.each do |a, block|
+              m.add_file(*a)
+              block.call if block
+            end
 
             if content_type = header_content_type || roda_class.opts[:mailer][:content_type]
               if mail.multipart?
@@ -188,11 +192,16 @@ class Roda
             super
           end
         end
+
+        # The attachments related to the current mail.
+        def mail_attachments
+          @mail_attachments ||= []
+        end
       end
 
       module InstanceMethods
         # Add delegates for common email methods.
-        [:from, :to, :cc, :bcc, :subject, :add_file].each do |meth|
+        [:from, :to, :cc, :bcc, :subject].each do |meth|
           define_method(meth) do |*args|
             env[RODA_MAIL].send(meth, *args)
             nil
@@ -215,6 +224,14 @@ class Roda
           end
         end
 
+        # Delay adding a file to the message until after the message body has been set.
+        # If a block is given, the block is called after the file has been added, and you
+        # can access the attachment via <tt>response.mail.attachments.last</tt>.
+        def add_file(*a, &block)
+          response.mail_attachments << [a, block]
+          nil
+        end
+
         private
 
         # Set the text_part or html_part (depending on the method) in the related email,

data/lib/roda/plugins/multi_route.rb

@@ -147,7 +147,8 @@ class Roda
 
         # The names for the currently stored named routes
         def named_routes(namespace=nil)
-          opts[:namespaced_routes][namespace].keys
+          routes = opts[:namespaced_routes][namespace]
+          routes ? routes.keys : []
         end
 
         # Return the named route with the given name.

data/lib/roda/plugins/path.rb

@@ -3,40 +3,93 @@ class Roda
     # 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:
+    # redirect, or anything else.
+    #
+    # Additionally, you can call the +path+ class method with a class and a block, and it will register
+    # the class.  You can then call the +path+ instance method with an instance of that class, and it will
+    # instance_exec the block with the arguments provided to path.
+    #
+    # Example:
     #
     #   plugin :path
     #   path :foo, '/foo'
     #   path :bar do |bar|
     #     "/bar/#{bar.id}"
     #   end
+    #   path Baz do |baz, *paths|
+    #     "/baz/#{baz.id}/#{paths.join('/')}"
+    #   end
+    #   path Quux |quux, path|
+    #     "/quux/#{quux.id}/#{path}"
+    #   end
     #
     #   route do |r|
+    #     r.post 'foo' do
+    #       r.redirect foo_path # /foo
+    #     end
+    #
     #     r.post 'bar' do
     #       bar = Bar.create(r.params['bar'])
-    #       r.redirect bar_path(bar)
+    #       r.redirect bar_path(bar) # /bar/1
+    #     end
+    #
+    #     r.post 'baz' do
+    #       bar = Baz[1]
+    #       r.redirect path(baz, 'c', 'd') # /baz/1/c/d
+    #     end
+    #
+    #     r.post 'quux' do
+    #       bar = Quux[1]
+    #       r.redirect path(quux, '/bar') # /quux/1/bar
     #     end
     #   end
     #
-    # The path method accepts the following options:
+    # The path method accepts the following options when not called with a class:
     #
-    # :add_script_name :: Prefix the path generated with SCRIPT_NAME.
+    # :add_script_name :: Prefix the path generated with SCRIPT_NAME. This defaults to the app's
+    #                     :add_script_name option.
     # :name :: Provide a different name for the method, instead of using <tt>*_path</tt>.
     # :url :: Create a url method in addition to the path method, which will prefix the string generated
     #         with the appropriate scheme, host, and port.  If true, creates a <tt>*_url</tt>
     #         method.  If a Symbol or String, uses the value as the url method name.
     # :url_only :: Do not create a path method, just a url method.
     #
-    # Note that if :add_script_name, :url, or :url_only is used, this will also create a <tt>_*_path</tt>
+    # Note that if :add_script_name, :url, or :url_only is used, will also create a <tt>_*_path</tt>
     # method.  This is necessary in order to support path methods that accept blocks, as you can't pass
     # a block to a block that is instance_execed.
     module Path
       DEFAULT_PORTS = {'http' => 80, 'https' => 443}.freeze
       OPTS = {}.freeze
 
+      # Initialize the path classes when loading the plugin
+      def self.configure(app)
+        app.instance_eval do
+          @path_classes ||= {}
+          unless @path_classes[String]
+            path(String){|str| str}
+          end
+        end
+      end
+
       module ClassMethods
+        # Hash of recognizes classes for path instance method.  Keys are classes, values are procs.
+        attr_reader :path_classes
+
+        # Freeze the path classes when freezing the app.
+        def freeze
+          @path_classes.freeze
+          super
+        end
+
         # Create a new instance method for the named path.  See plugin module documentation for options.
         def path(name, path=nil, opts=OPTS, &block)
+          if name.is_a?(Class)
+            raise RodaError, "can't provide path or options when calling path with a class" unless path.nil? && opts.empty?
+            raise RodaError, "must provide a block when calling path with a class" unless block
+            @path_classes[name] = block
+            return
+          end
+
           if path.is_a?(Hash)
             raise RodaError,  "cannot provide two option hashses to Roda.path" unless opts.empty?
             opts = path
@@ -53,7 +106,7 @@ class Roda
 
           meth = opts[:name] || "#{name}_path"
           url = opts[:url]
-          add_script_name = opts[:add_script_name]
+          add_script_name = opts.fetch(:add_script_name, self.opts[:add_script_name])
 
           if add_script_name || url || opts[:url_only]
             _meth = "_#{meth}"
@@ -93,6 +146,22 @@ class Roda
           nil
         end
       end
+
+      module InstanceMethods
+        # Return a path based on the class of the object.  The object passed must have
+        # had its class previously registered with the application.  If the app's
+        # :add_script_name option is true, this prepends the SCRIPT_NAME to the path.
+        def path(obj, *args)
+          app = self.class
+          if blk = app.path_classes[obj.class]
+            path = instance_exec(obj, *args, &blk)
+            path = request.script_name.to_s + path if app.opts[:add_script_name]
+            path
+          else
+            raise RodaError, "unrecognized object given to Roda#path: #{obj.inspect}"
+          end
+        end
+      end
     end
 
     register_plugin(:path, Path)

data/lib/roda/plugins/render.rb

@@ -38,8 +38,8 @@ class Roda
     #                 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>.
-    # :views :: The directory holding the view files, defaults to 'views' in the
-    #           current directory.
+    # :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).
     #
     # Most of these options can be overridden at runtime by passing options
     # to the +view+ or +render+ methods:
@@ -86,20 +86,20 @@ class Roda
 
       # Setup default rendering options.  See Render for details.
       def self.configure(app, opts=OPTS)
-        orig_opts = opts
         if app.opts[:render]
-          app.opts[:render] = app.opts[:render].merge(opts)
-        else
-          app.opts[:render] = opts.dup
+          opts = app.opts[:render][:orig_opts].merge(opts)
         end
+        app.opts[:render] = opts.dup
+        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("views", Dir.pwd)
+        opts[:views] = File.expand_path(opts[:views]||"views", app.opts[:root])
         opts[:layout_opts] = (opts[:layout_opts] || {}).dup
+        opts[:layout_opts][:_is_layout] = true
 
-        if layout = orig_opts.fetch(:layout, true)
+        if layout = opts.fetch(:layout, true)
           opts[:layout] = true unless opts.has_key?(:layout)
 
           case layout
@@ -196,8 +196,8 @@ class Roda
           end
         end
 
-        # Given the template name and options, return the template class, template path/content,
-        # and template block to use for the render.
+        # 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)
           if content = opts[:inline]
             path = opts[:path] = content
@@ -221,6 +221,14 @@ class Roda
             opts[:key] = key
           end
 
+          if !opts[:_is_layout] && (r_locals = render_opts[:locals])
+            opts[:locals] = if locals = opts[:locals]
+              r_locals.merge(locals)
+            else
+              r_locals
+            end
+          end
+
           opts
         end
 
@@ -230,6 +238,12 @@ class Roda
           opts.merge(template)
         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
+        end
+
         # The name to use for the template.  By default, just converts the :template option to a string.
         def template_name(opts)
           opts[:template].to_s
@@ -246,10 +260,15 @@ class Roda
         # used, return nil.
         def view_layout_opts(opts)
           if layout = opts.fetch(:layout, render_opts[:layout])
-            layout_opts = if opts[:layout_opts]
-              opts[:layout_opts].merge(render_opts[:layout_opts])
-            else
-              render_opts[:layout_opts].dup
+            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)
+              end
+              layout_opts.merge!(l_opts)
+              if set_locals
+                layout_opts[:locals] = set_locals
+              end
             end
 
             case layout

data/lib/roda/plugins/static.rb

@@ -0,0 +1,35 @@
+class Roda
+  module RodaPlugins
+    # The static plugin loads the Rack::Static middleware into the application.
+    # It mainly exists to make serving static files simpler, by supplying
+    # defaults to Rack::Static that are appropriate for Roda.
+    #
+    # The static plugin recognizes the application's :root option, and by default
+    # sets the Rack::Static +:root+ option to the +public+ subfolder of the application's
+    # +:root+ option.  Additionally, if a relative path is provided as the :root
+    # option to the plugin, it will be considered relative to the application's
+    # +:root+ option.
+    #
+    # Since the :urls option for Rack::Static is always required, the static plugin
+    # uses a separate option for it.
+    # 
+    # Examples:
+    #
+    #   opts[:root] = '/path/to/app'
+    #   plugin :static, ['/js', '/css'] # path: /path/to/app/public
+    #   plugin :static, ['/images'], :root=>'pub'  # path: /path/to/app/pub
+    #   plugin :static, ['/media'], :root=>'/path/to/public' # path: /path/to/public
+    module Static
+      # Load the Rack::Static middleware.  Use the paths given as the :urls option,
+      # and set the :root option to be relative to the application's :root option.
+      def self.configure(app, paths, opts={})
+        opts = opts.dup
+        opts[:urls] = paths
+        opts[:root] =  File.expand_path(opts[:root]||"public", app.opts[:root])
+        app.use ::Rack::Static, opts
+      end
+    end
+
+    register_plugin(:static, Static)
+  end
+end

data/lib/roda/plugins/view_options.rb

@@ -0,0 +1,161 @@
+class Roda
+  module RodaPlugins
+    # The view_options plugin allows you to override view and layout
+    # options and locals for specific branches and routes.
+    #
+    #   plugin :render
+    #   plugin :view_options
+    #
+    #   route do |r|
+    #     r.on "users" do
+    #       set_layout_options :template=>'users_layout'
+    #       set_layout_locals :title=>'Users'
+    #       set_view_options :engine=>'haml'
+    #       set_view_locals :footer=>'(c) Roda'
+    #
+    #       # ...
+    #     end
+    #   end
+    #
+    # The options and locals you specify have higher precedence than
+    # the render plugin options, but lower precedence than options
+    # you directly pass to the view/render methods.
+    #
+    # The view_options plugin also has special support for sites
+    # that have outgrown a flat view directory and use subdirectories
+    # for views.  It allows you to set the view directory to
+    # use, and template names that do not contain a slash will
+    # automatically use that view subdirectory.  Example:
+    #
+    #   plugin :render, :layout=>'./layout'
+    #   plugin :view_options
+    #
+    #   route do |r|
+    #     r.on "users" do
+    #       set_view_subdir 'users'
+    #       
+    #       r.get :id do
+    #         append_view_subdir 'profile'
+    #         view 'index' # uses ./views/users/profile/index.erb
+    #       end
+    #
+    #       r.get 'list' do
+    #         view 'lists/users' # uses ./views/lists/users.erb
+    #       end
+    #     end
+    #   end
+    #
+    # Note that when a view subdirectory is set, the layout will
+    # also be looked up in the subdirectory unless it contains
+    # a slash.  So if you want to use a view subdirectory for
+    # templates but have a shared layout, you should make sure your
+    # layout contains a slash, similar to the example above.
+    module ViewOptions
+      # Load the render plugin before this plugin, since this plugin
+      # works by overriding methods in the render plugin.
+      def self.load_dependencies(app)
+        app.plugin :render
+      end
+
+      # The following methods are created via metaprogramming:
+      # set_layout_locals :: Set locals to use in the layout
+      # set_layout_options :: Set options to use when rendering the layout
+      # set_view_locals :: Set locals to use in the view
+      # set_view_options :: Set options to use when rendering the view
+      module InstanceMethods
+        %w'layout view'.each do |type|
+          %w'locals options'.each do |var|
+            v = "_#{type}_#{var}"
+            module_eval(<<-END, __FILE__, __LINE__+1)
+              def set#{v}(opts)
+                if @#{v}
+                  @#{v} = @#{v}.merge(opts)
+                else
+                  @#{v} = opts
+                end
+              end
+            END
+          end
+        end
+
+        # Append a view subdirectory to use.  If there hasn't already
+        # been a view subdirectory set, this just sets it to the argument.
+        # If there has already been a view subdirectory set, this sets
+        # the view subdirectory to a subdirectory of the existing
+        # view subdirectory.
+        def append_view_subdir(v)
+          if subdir = @_view_subdir
+            set_view_subdir("#{subdir}/#{v}")
+          else
+            set_view_subdir(v)
+          end
+        end
+
+        # Set the view subdirectory to use.  This can be set to nil
+        # to not use a view subdirectory.
+        def set_view_subdir(v)
+          @_view_subdir = v
+        end
+
+        private
+
+        # If view options or locals have been set and this
+        # template isn't a layout template, merge the options
+        # and locals into the returned hash.
+        def parse_template_opts(template, opts)
+          t_opts = super
+
+          unless t_opts[:_is_layout]
+            if v_opts = @_view_options
+              t_opts.merge!(v_opts)
+            end
+
+            if v_locals = @_view_locals
+              t_opts[:locals] = if t_locals = t_opts[:locals]
+                v_locals.merge(t_locals)
+              else
+                v_locals
+              end
+            end
+          end
+
+          t_opts
+        end
+
+        # If layout options or locals have been set,
+        # merge the options and locals into the returned hash.
+        def render_layout_opts
+          opts = super
+
+          if l_opts = @_layout_options
+            opts.merge!(l_opts)
+          end
+
+          if l_locals = @_layout_locals
+            opts[:locals] = if o_locals = opts[:locals]
+              o_locals.merge(l_locals)
+            else
+              l_locals
+            end
+          end
+
+          opts
+        end
+
+        # Override the template name to use the view subdirectory if the
+        # there is a view subdirectory and the template name does not
+        # contain a slash.
+        def template_name(opts)
+          name = super
+          if (v = @_view_subdir) && name !~ /\//
+            "#{v}/#{name}"
+          else
+            name
+          end
+        end
+      end
+    end
+
+    register_plugin(:view_options, ViewOptions)
+  end
+end