roda 0.9.0

data/lib/roda/plugins/all_verbs.rb

@@ -0,0 +1,48 @@
+class Roda
+  module RodaPlugins
+    # The all_verbs plugin adds methods for http verbs other than
+    # get and post.  The following verbs are added, assuming
+    # rack handles them: delete, head, options, link, patch, put,
+    # trace, unlink.
+    #
+    # These methods operate just like Roda's default get and post
+    # methods other that the http verb used, so using them without
+    # any arguments just checks for the request method, while
+    # using them with any arguments also checks that the arguments
+    # match the full path.
+    #
+    # Example:
+    #
+    #   plugin :all_verbs
+    #
+    #   route do |r|
+    #     r.delete
+    #       # Handle DELETE
+    #     end
+    #     r.put do
+    #       # Handle PUT
+    #     end
+    #     r.patch do
+    #       # Handle PATCH
+    #     end
+    #   end
+    #
+    # The verb methods are defined via metaprogramming, so there
+    # isn't documentation for the individual methods created.
+    module AllVerbs
+      module RequestMethods
+        %w'delete head options link patch put trace unlink'.each do |t|
+          if ::Rack::Request.method_defined?("#{t}?")
+            class_eval(<<-END, __FILE__, __LINE__+1)
+              def #{t}(*args, &block)
+                is_or_on(*args, &block) if #{t}?
+              end
+            END
+          end
+        end
+      end
+    end
+
+    register_plugin(:all_verbs, AllVerbs)
+  end
+end

data/lib/roda/plugins/default_headers.rb

@@ -0,0 +1,50 @@
+class Roda
+  module RodaPlugins
+    # The default_headers plugin accepts a hash of headers,
+    # and overrides the default_headers method in the
+    # response class to be a copy of the headers.
+    #
+    # Note that when using this module, you should not
+    # attempt to mutate of the values set in the default
+    # headers hash.
+    #
+    # Example:
+    #
+    #   plugin :default_headers, 'Content-Type'=>'text/csv'
+    #
+    # You can also modify the default headers later:
+    #
+    #   plugin :default_headers
+    #   default_headers['Foo'] = 'bar'
+    #   default_headers.merge!('Bar'=>'baz')
+    module DefaultHeaders
+      # Merge the given headers into the existing default headers, if any.
+      def self.configure(app, headers={})
+        app.instance_eval do
+          @default_headers ||= {}
+          @default_headers.merge!(headers)
+        end
+      end 
+
+      module ClassMethods
+        # The default response headers to use for the current class.
+        attr_reader :default_headers
+
+        # Copy the default headers into the subclass when inheriting.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@default_headers, default_headers.dup)
+        end
+      end
+
+      module ResponseMethods
+        # Get the default headers from the related roda class.
+        def default_headers
+          self.class.roda_class.default_headers.dup
+        end
+      end
+    end
+
+    register_plugin(:default_headers, DefaultHeaders)
+  end
+end

data/lib/roda/plugins/error_handler.rb

@@ -0,0 +1,69 @@
+class Roda
+  module RodaPlugins
+    # The error_handler plugin adds an error handler to the routing,
+    # so that if routing the request raises an error, a nice error
+    # message page can be returned to the user.
+    # 
+    # You can provide the error handler as a block to the plugin:
+    #
+    #   plugin :error_handler do |e|
+    #     "Oh No!"
+    #   end
+    #
+    # Or later via the +error+ class method:
+    #
+    #   plugin :error_handler
+    #
+    #   error do |e|
+    #     "Oh No!"
+    #   end
+    #
+    # In both cases, the exception instance is passed into the block,
+    # and the block can return the request body via a string.
+    #
+    # If an exception is raised, the response status will be set to 500
+    # before executing the error handler.  The error handler can change
+    # the response status if necessary.
+    module ErrorHandler
+      # If a block is given, automatically call the +error+ method on
+      # the Roda class with it.
+      def self.configure(app, &block)
+        if block
+          app.error(&block)
+        end
+      end
+
+      module ClassMethods
+        # Install the given block as the error handler, so that if routing
+        # the request raises an exception, the block will be called with
+        # the exception in the scope of the Roda instance.
+        def error(&block)
+          define_method(:handle_error, &block)
+          private :handle_error
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # If an error occurs, set the response status to 500 and call
+        # the error handler.
+        def _route
+          super
+        rescue => e
+          response.status = 500
+          super{handle_error(e)}
+        end
+
+        # By default, have the error handler reraise the error, so using
+        # the plugin without installing an error handler doesn't change
+        # behavior.
+        def handle_error(e)
+          raise e
+        end
+      end
+    end
+
+    register_plugin(:error_handler, ErrorHandler)
+  end
+end

data/lib/roda/plugins/flash.rb

@@ -0,0 +1,62 @@
+require 'sinatra/flash/hash'
+
+class Roda
+  module RodaPlugins
+    # The flash plugin adds a +flash+ instance method to Roda,
+    # for typical web application flash handling, where values
+    # set in the current flash hash are available in the next
+    # request.
+    #
+    # With the example below, if a POST request is submitted,
+    # it will redirect and the resulting GET request will
+    # return 'b'.
+    #
+    #   plugin :flash
+    #
+    #   route do |r|
+    #     r.is '' do
+    #       r.get do
+    #         flash['a']
+    #       end
+    #
+    #       r.post do
+    #         flash['a'] = 'b'
+    #         r.redirect('')
+    #       end
+    #     end
+    #   end
+    #
+    # The flash plugin uses sinatra-flash internally, so you
+    # must install sinatra-flash in order to use it.
+    module Flash
+      FlashHash = ::Sinatra::Flash::FlashHash
+
+      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
+          @_flash ||= FlashHash.new((session ? session[KEY] : {}))
+        end
+
+        private
+
+        # If the routing doesn't raise an error, rotate the flash
+        # hash in the session so the next request has access to it.
+        def _route
+          res = super
+
+          if f = @_flash
+            session[KEY] = f.next
+          end
+
+          res
+        end
+      end
+    end
+
+    register_plugin(:flash, Flash)
+  end
+end

data/lib/roda/plugins/h.rb

@@ -0,0 +1,24 @@
+class Roda
+  module RodaPlugins
+    # The h plugin adds an +h+ instance method that will HTML
+    # escape the input and return it.
+    #
+    # The following example will return "<foo>" as the body.
+    #
+    #   plugin :h
+    #
+    #   route do |r|
+    #     h('<foo>')
+    #   end
+    module H
+      module InstanceMethods
+        # HTML escape the input and return the escaped version.
+        def h(s)
+          ::Rack::Utils.escape_html(s.to_s)
+        end
+      end
+    end
+
+    register_plugin(:h, H)
+  end
+end

data/lib/roda/plugins/halt.rb

@@ -0,0 +1,79 @@
+class Roda
+  module RodaPlugins
+    # The halt plugin augments the standard request +halt+ method to handle more than
+    # just rack response arrays.
+    #
+    # After loading the halt plugin:
+    #
+    #   plugin :halt
+    #
+    # You can call halt with no arguments to immediately stop processing:
+    #
+    #   route do |r|
+    #     r.halt
+    #   end
+    #
+    # You can call the halt method with an integer to set the response status and return:
+    #   
+    #   route do |r|
+    #     r.halt(403)
+    #   end
+    #
+    # Or set the response body and return:
+    #
+    #   route do |r|
+    #     r.halt("body')
+    #   end
+    #
+    # Or set both:
+    #
+    #   route do |r|
+    #     r.halt(403, "body')
+    #   end
+    #
+    # Or set response status, headers, and body:
+    #
+    #   route do |r|
+    #     r.halt(403, {'Content-Type'=>'text/csv'}, "body')
+    #   end
+    #
+    # Note that there is a difference between provide status, headers, and body as separate
+    # arguments and providing them as a rack response array.  With a rack response array,
+    # the values are used directly, while with 3 arguments, the headers given are merged into
+    # the existing headers and the given body is written to the existing response body.
+    module Halt
+      module RequestMethods
+        # Expand default halt method to handle status codes, headers, and bodies.  See Halt.
+        def halt(*res)
+          case res.length
+          when 0 # do nothing
+          when 1
+            case v = res[0]
+            when Integer
+              response.status = v
+            when String
+              response.write v
+            when Array
+              super
+            else
+              raise Roda::RodaError, "singular argument to #halt must be Integer, String, or Array"
+            end
+          when 2
+            response.status = res[0]
+            response.write res[1]
+          when 3
+            response.status = res[0]
+            response.headers.merge!(res[1])
+            response.write res[2]
+          else
+            raise Roda::RodaError, "too many arguments given to #halt (accepts 0-3, received #{res.length})"
+          end
+
+          _halt response.finish
+        end
+      end
+    end
+
+    register_plugin(:halt, Halt)
+  end
+end

data/lib/roda/plugins/header_matchers.rb

@@ -0,0 +1,57 @@
+class Roda
+  module RodaPlugins
+    # The header_matchers plugin adds hash matchers for matching on less-common
+    # HTTP headers.
+    #
+    #   plugin :header_matchers
+    #
+    # It adds a +:header+ matcher for matching on arbitrary headers, which matches
+    # if the header is present:
+    #
+    #   route do |r|
+    #     r.on :header=>'X-App-Token' do
+    #     end
+    #   end
+    #
+    # It adds a +:host+ matcher for matching by the host of the request:
+    #
+    #   route do |r|
+    #     r.on :host=>'foo.example.com' do
+    #     end
+    #   end
+    #
+    # It adds an +:accept+ matcher for matching based on the Accept header:
+    #
+    #   route do |r|
+    #     r.on :accept=>'text/csv' do
+    #     end
+    #   end
+    #
+    # Note that the accept matcher is very simple and cannot handle wildcards,
+    # priorities, or anything but a simple comma separated list of mime types.
+    module HeaderMatchers
+      module RequestMethods
+        private
+
+        # Match if the given mimetype is one of the accepted mimetypes.
+        def match_accept(mimetype)
+          if env["HTTP_ACCEPT"].to_s.split(',').any?{|s| s.strip == mimetype}
+            response["Content-Type"] = mimetype
+          end
+        end
+
+        # Match if the given uppercase key is present inside the environment.
+        def match_header(key)
+          env[key.upcase.tr("-","_")]
+        end
+
+        # Match if the host of the request is the same as the hostname.
+        def match_host(hostname)
+          hostname === host
+        end
+      end
+    end
+
+    register_plugin(:header_matchers, HeaderMatchers)
+  end
+end

data/lib/roda/plugins/hooks.rb

@@ -0,0 +1,106 @@
+class Roda
+  module RodaPlugins
+    # The hooks plugin adds before and after hooks to the request cycle.
+    #
+    #   plugin :hooks
+    #
+    #   before do
+    #     request.redirect('/login') unless logged_in?
+    #     @time = Time.now
+    #   end
+    #
+    #   after do |res|
+    #     logger.notice("Took #{Time.now - @time} seconds")
+    #   end
+    #
+    # Note that in general, before hooks are not needed, since you can just
+    # run code at the top of the route block:
+    #
+    #   route do |r|
+    #     r.redirect('/login') unless logged_in?
+    #     # ...
+    #   end
+    #
+    # Note that the after hook is called with the rack response array
+    # of status, headers, and body.  If it wants to change the response,
+    # it must mutate this argument, calling <tt>response.status=</tt> inside
+    # an after block will not affect the returned status.
+    #
+    # However, this code makes it easier to write after hooks, as well as
+    # handle cases where before hooks are added after the route block.
+    module Hooks
+      def self.configure(app)
+        @app.instance_exec do
+          @after ||= nil
+          @before ||= nil
+        end
+      end
+
+      module ClassMethods
+        # Add an after hook.  If there is already an after hook defined,
+        # use a proc that instance_execs the existing after proc and
+        # then instance_execs the given after proc, so that the given
+        # after proc always executes after the previous one.
+        def after(&block)
+          if block
+            @after = if b = @after
+              @after = proc do |res|
+                instance_exec(res, &b)
+                instance_exec(res, &block)
+              end
+            else
+              block
+            end
+          end
+          @after
+        end
+
+        # Add a before hook.  If there is already a before hook defined,
+        # use a proc that instance_execs the give before proc and
+        # then instance_execs the existing before proc, so that the given
+        # before proc always executes before the previous one.
+        def before(&block)
+          if block
+            @before = if b = @before
+              @before = proc do
+                instance_exec(&block)
+                instance_exec(&b)
+              end
+            else
+              block
+            end
+          end
+          @before
+        end
+
+        # Copy the before and after hooks into the subclasses
+        # when inheriting
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@before, @before)
+          subclass.instance_variable_set(:@after, @after)
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # Before routing, execute the before hooks, and
+        # execute the after hooks before returning.
+        def _route(*, &block)
+          if b = self.class.before
+            instance_exec(&b)
+          end
+
+          res = super
+        ensure
+          if b = self.class.after
+            instance_exec(res, &b)
+          end
+        end
+      end
+    end
+
+    register_plugin(:hooks, Hooks)
+  end
+end