scorched 0.19 → 0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 126d0553639f9a33afab401c7084a573a28914c4
-  data.tar.gz: ca8aaba8a210a5b48ec91be131ec9d5432be489a
+  metadata.gz: 5b78f42bbcf1ea4018406b7fcf95f31c78ed1c4e
+  data.tar.gz: 3a86547b8e623c089ec67a1a45f65a4ce2b1554d
 SHA512:
-  metadata.gz: def1aa2f26ef50000e5a6689a4eeb9f120119968c6604915618d12f3d22211dbdf3e4ba080f4d79525c98848e8729b4b022a843bcab159fb870899efed7511db
-  data.tar.gz: 35cb01c416ccb4ed8e328476b5a7a1a80b76570e5d0229b9c02e7082f4eb078fdc92e868adcfaf227546761f8827a6d8b658cf970be30ed1dda2ef8608c0d81a
+  metadata.gz: 2ff3c8bc993bffc2d5d94682fc53288a6293edfe94f9f7e9341efb08f6af71cd868cc6614541b286add86c2d0c2ff2c80021115957d088c7afc3bd1c8de075e6
+  data.tar.gz: e96714a418248738c3bb78d76bed6d8a41b28055bed3d1840bca2e2c1430bfb67960e8e5d6fcb6341dbec244bf06172cd2513d20c031c9fe950d311931a3ab9f

data/CHANGES.md

@@ -1,8 +1,18 @@
 Changelog
 =========
 
+_Note that Scorched is yet to reach a v1.0 release. This means breaking changes may still be made. If upgrading Scorched version for your project, review this changelog carefully._
+
+### v0.20
+* _After_ filters are now still processed when a request is halted. This restores the original behaviour prior to version 0.8. This fixes an issue where halting the request after setting flash session data would cause the request to bomb-out.
+* As an extension of the change above, filters can now be marked as _forced_ using the new `force` option, which if true, means the filter will run even if the request is halted within another filter (including within another forced filter). This ensures a particular filter is run for every request. This required changing the public interface for the _filter_ method. The sugar methods _before_, _after_, and _error_ have remained backwards compatible. 
+* Named captures are now passed to route proc's as a single hash argument. The previous behaviour was an oversight.
+* Halting within an error filter is now swallowed if the error filter is invoked by an error raised in a before or after filter.
+* The `controller` helper can now be used to map predefined controllers simply by omitting the block, which is now optional. This a more convenient means of mapping controllers as compared to the more barebones `map` method.
+* `log` method now returns the log object. Method arguments are also now optional, meaning you can use the more natural logger interface if you prefer, e.g. `log.info "hello"`.
+
 ### v0.19
-* The behaviour of wildcards '*' and '**' (and their _named_ equivalents) have been reverted to their original behviour of matching one or more characters, instead of zero or more. This means `/*` will no longer match `/`. Adding a question mark directly after a wildcard will have that wildcard match zero or more character, instead of one or more. So the pattern `/*?` will match both `/` and `/about`.
+* The behaviour of wildcards `*` and `**` (and their _named_ equivalents) have been reverted to their original behaviour of matching one or more characters, instead of zero or more. This means `/*` will no longer match `/`. Adding a question mark directly after a wildcard will have that wildcard match zero or more character, instead of one or more. So the pattern `/*?` will match both `/` and `/about`.
 
 ### v0.18
 * Redirects now use a 303 or 302 HTTP status code by default, depending on HTTP version (similar logic to Sinatra). Trailing slash redirects (triggered by :strip_trailing_slash) still uses a 307 status.

data/docs/02_fundamentals/01_the_controller.md

@@ -88,17 +88,10 @@ You can use nesting and inheritance exclusively, or together, depending on your
 
 Controller Helper
 -----------------
-There is a more succinct way of defining sub-controllers, and that's with the `controller` helper. Here's the previous example re-written using the `controller` helper.
+There is a more succinct way of mapping and defining sub-controllers, and that's with the `controller` helper. Here's the previous example cut-down and re-written using the `controller` helper.
 
 ``` ruby
 class MyApp < Scorched::Controller
-  render_defaults[:dir] = 'views'
-  render_defaults[:layout] = :main
-  
-  conditions[:user] = proc { |usernames|
-    [*usernames].include? 'bob'
-  }
-  
   get '/' do
     bold "Hello there"
   end
@@ -117,7 +110,7 @@ class MyApp < Scorched::Controller
 end
 ```
 
-The `controller` helper takes an optional URL pattern as it's first argument, an optional parent class as it's second, and finally a mapping hash as its third optional argument, where you can define a priority, conditions, or override the URL pattern. Of course, the `controller` helper takes a block as well, which defines the body of the new controller class.
+The `controller` helper takes an optional URL pattern as it's first argument, an optional parent class as its second, and finally a mapping hash as its third optional argument, where you can define a priority, conditions, or override the URL pattern. Of course, the `controller` helper takes a block as well, which defines the body of the new controller class.
 
 The optional URL pattern defaults to `'/'` which means it's essentially a match-all mapping. In addition, the generated controller has `:auto_pass` set to `true` by default (refer to configuration documentation for more information). This is a handy combination for grouping a set of routes in their own scope, with their own methods, filters, configuration, etc. 
 
@@ -153,6 +146,18 @@ end
 
 That example, while serving no practical purpose, hopefully demonstrates how you can combine various constructs with sub-controllers, to come up with DRY creative solutions.
 
+Finally, the `controller` helper can also be used a shortcut to map one controller to another, where the given class is mapped directly, instead of being the parent of a new controller class. These two examples are essentially equivalent:
+
+``` ruby
+ControllerA << {pattern: '/sub', target: ControllerB}
+
+# Or
+
+class ControllerA
+  controller '/', ControllerB # Note that no block was given
+end
+```
+
 
 The Root Controller
 -------------------

data/docs/02_fundamentals/04_requests_and_responses.md

@@ -20,9 +20,9 @@ Halting Requests
 ----------------
 There may be instances we're you want to shortcut out-of processing the current request. The `halt` method allows you to do this, though it's worth clarifying its behaviour.
 
-When `halt` is called within a route, it simply exists out of that route, and begins processing any _after_ filters. Halt can also be used within a _before_ or _after_ filter, in which case any remaining filters in the current controller are skipped.
+When `halt` is called within a route, it simply exits out of that route, and begins processing any _after_ filters. Halt can also be used within a _before_ or _after_ filter, in which case any remaining filters in the current controller are skipped, with the exception of _forced_ filters (see documentation on filters).
 
-Calls to `halt` don't propagate up the controller chain. They're local to the controller. A call to `halt` is equivalent to doing a manual `throw :halt`. Calling `halt` is often preferred though because as well as being syntactically sweeter, it can take an optional argument to set the response status and body, which is something you likely want to do when halting a request.
+Calls to `halt` don't propagate up the controller chain. They're caught within the controller they're thrown. A call to `halt` is equivalent to doing a manual `throw :halt`. Calling `halt` is often preferred though because as well as being syntactically sweeter, it can take an optional argument to set the response status and body, which is something you likely want to do when halting a request.
 
 
 Passing Requests

data/docs/02_fundamentals/05_filters.md

@@ -11,7 +11,7 @@ Before and After filters allow pre- and post-processing of requests. They are ex
 
 ```ruby
 before do
-  raise Error, "Must be logged in to access this site" unless session[:logged_in] == true
+  raise "Must be logged in to access this site" unless session[:logged_in] == true
 end
 ```
 
@@ -31,7 +31,15 @@ after status: 404 do
 end
 ```
 
-Your imagination is the only limitation.
+An optional _force_ option exists which ensures the filter is always run, even if another filter halts the request.
+
+```ruby
+after force: true do
+  # Close open file handles or something
+end
+```
+
+How you use filters is up to your own imagination and creative problem solving.
 
 
 Error Filters
@@ -40,10 +48,10 @@ Error filters are processed like regular filters, except they're called whenever
 
 Error filters can handle exceptions raised from within the request target, as well as those raised within _before_ and _after_ filters. The way error filters have been implemented, allows exceptions raised within the request target to be handled before running the _after_ filters. This means that _after_ filters are still run as long as exceptions that occurred within the request target are handled.
 
-Error filters can target only specific types of exception class, in much the same way as a typical Ruby rescue block.
+Error filters can target only specific types of exception class, in much the same way as a typical Ruby rescue block. In the following example, the error filter is only executed when an uncaught PermissionError exception is raised, and when a made-up `catch_exceptions` condition evaluates to true.
 
 ```ruby
-error PermissionError do |e|
+error PermissionError, catch_exceptions: true do |e|
   flash[:error] = "You do not have the appropriate permission to perform that action: #{e.message}"
 end
 ```

data/docs/02_fundamentals/08_views.md

@@ -21,4 +21,11 @@ When a layout is given, a subsequent call to `render` is made, with the rendered
 
 Partials
 --------
-There are cases where you may want a view to be composed of more than just a layout and a single view. The view may contain one or more sub-views, commonly referred to as partials. Scorched makes provisions for this by ignoring the default layout when `render` is called within a view, hence negating the requirement to explicitly override the layout.
+There are cases where you may want a view to be composed of more than just a layout and a single view. The view may contain one or more sub-views, commonly referred to as partials. Scorched makes provisions for this by ignoring the default layout when `render` is called within a view, hence negating the requirement to explicitly override the layout.
+
+Helpers
+-------
+No explicit distinction is made between a controller helper and a view helper, as both share the same context. There are however some helper methods intended primarily for views.
+
+* `absolute` - Returns the absolute URL of the web application root, with the optional argument joined to the end. For example, if you're application was mounted under example.com/myapp/: `absolute '/about' #=> /myapp/about`
+* `url` - Same as absolute, except returns the full URL, e.g. `url '/about' #=> http://example.com/myapp/about`.

data/lib/scorched/controller.rb

@@ -15,7 +15,7 @@ module Scorched
     config << {
       :auto_pass => false, # Automatically _pass_ request back to outer controller if no route matches.
       :cache_templates => true,
-      :logger => nil,
+      :logger => Logger.new(STDOUT),
       :show_exceptions => false,
       :show_http_error_pages => false, # If true, shows the default Scorched HTTP error page.
       :static_dir => false, # The directory Scorched should serve static files from. Set to false if web server or anything else is serving static files.
@@ -32,7 +32,6 @@ module Scorched
     }
     
     if ENV['RACK_ENV'] == 'development'
-      config[:logger] = Logger.new(STDOUT)
       config[:show_exceptions] = true
       config[:static_dir] = 'public'
       config[:cache_templates] = false
@@ -136,20 +135,19 @@ module Scorched
       end
       alias :<< :map
       
-      # Creates a new controller as a sub-class of self (by default), mapping it to self using the provided mapping
-      # hash if one is provided. Returns the new anonymous controller class.
+      # Maps a new ad-hoc or predefined controller.
       #
-      # Takes three optional arguments and a block: a pattern, a parent class from which the generated controller class 
-      # inherits from, a mapping hash for setting conditions and so on, and of course a block which defines the
-      # controller class.
-      #
-      # It's worth noting, however obvious, that the resulting class will only be a Scorched::Controller if the parent 
-      # class is, or inherits from, a Scorched::Controller.
-      def controller(pattern = '/', parent_class = self, **mapping, &block)
-        c = Class.new(parent_class, &block)
-        c.config[:auto_pass] = true if parent_class < Scorched::Controller
-        self << {pattern: pattern, target: c}.merge(mapping)
-        c
+      # If a block is given, creates a new controller as a sub-class of _klass_ (_self_ by default), otherwise maps 
+      # _klass_ itself. Returns the new anonymous controller class if a block is given, or _klass_ otherwise.
+      def controller(pattern = '/', klass = self, **mapping, &block)
+        if block_given?
+          controller = Class.new(klass, &block)
+          controller.config[:auto_pass] = true if klass < Scorched::Controller
+        else
+          controller = klass
+        end
+        self << {pattern: pattern, target: controller}.merge(mapping)
+        controller
       end
       
       # Generates and returns a new route proc from the given block, and optionally maps said proc using the given args.
@@ -167,7 +165,7 @@ module Scorched
       #     patch(pattern = nil, priority = nil, **conds, &block)
       def route(pattern = nil, priority = nil, **conds, &block)
         target = lambda do
-          response.body = instance_exec(*request.captures, &block)
+          response.body = instance_exec(*[request.captures].flatten, &block)
           response
         end
         [*pattern].compact.each do |pattern|
@@ -184,22 +182,31 @@ module Scorched
         end
       end
       
-      # Defines a filter of +type+. Helper methods are provided as syntactic sugar for each filter type.
-      # +args+ is used internally by Scorched for passing additional arguments to the filter, such as the exception in
-      # the case of error blocks.
-      # :call-seq:
-      #     filter(type, *args, **conds, &block)
-      #     before(*args, **conds, &block)
-      #     after(*args, **conds, &block)
-      #     error(*args, **conds, &block)
-      def filter(type, *args, **conds, &block)
-        filters[type.to_sym] << {args: args, conditions: conds, proc: block}
+      # Defines a filter of +type+. 
+      # +args+ is used internally by Scorched for passing additional arguments to some filters, such as the exception in
+      # the case of error filters. 
+      def filter(type, args: nil, force: nil, conditions: nil, **more_conditions, &block)
+        more_conditions.merge!(conditions || {})
+        filters[type.to_sym] << {args: args, force: force, conditions: more_conditions, proc: block}
       end
       
-      ['before', 'after', 'error'].each do |type|
-        define_method(type) do |*args, &block|
-          filter(type, *args, &block)
-        end
+      # Syntactic sugar for defining a before filter.
+      # If +force+ is true, the filter is run even if another filter halts the request.
+      def before(force: false, **conditions, &block)
+        filter(:before, force: force, conditions: conditions, &block)
+      end
+      
+      # Syntactic sugar for defining an after filter.
+      # If +force+ is true, the filter is run even if another filter halts the request.
+      def after(force: false, **conditions, &block)
+        filter(:after, force: force, conditions: conditions, &block)
+      end
+      
+      # Syntactic sugar for defining an error filter.
+      # Takes one or more optional exception classes for which this error filter should handle. Handles all exceptions
+      # by default.
+      def error(*classes, **conditions, &block)
+        filter(:error, args: classes, conditions: conditions, &block)
       end
       
     private
@@ -211,7 +218,7 @@ module Scorched
         return pattern if Regexp === pattern
         raise Error, "Can't compile URL of type #{pattern.class}. Must be String or Regexp." unless String === pattern
         match_to_end = !!pattern.sub!(/\$$/, '') || match_to_end
-        compiled_pattern = pattern.split(%r{(\*{1,2}\??|(?<!\\):{1,2}[^/*$]+\??)}).each_slice(2).map { |unmatched, match|
+        compiled = pattern.split(%r{(\*{1,2}\??|(?<!\\):{1,2}[^/*$]+\??)}).each_slice(2).map { |unmatched, match|
           Regexp.escape(unmatched) << begin
             op = (match && match[-1] == '?' && match.chomp!('?')) ? '*' : '+'
             if %w{* **}.include? match
@@ -223,8 +230,8 @@ module Scorched
             end
           end
         }.join
-        compiled_pattern << '$' if match_to_end
-        Regexp.new(compiled_pattern)
+        compiled << '$' if match_to_end
+        Regexp.new(compiled)
       end
     end
     
@@ -245,13 +252,14 @@ module Scorched
       @response = Response.new
     end
     
+    # This is where the magic happens.
     def action
       inner_error = nil
       rescue_block = proc do |e|
         raise unless filters[:error].any? do |f|
-          (f[:args].empty? || f[:args].any? { |type| e.is_a?(type) }) &&
-          !check_for_failed_condition(f[:conditions]) &&
-          instance_exec(e, &f[:proc])
+          if !f[:args] || f[:args].empty? || f[:args].any? { |type| e.is_a?(type) }
+            instance_exec(e, &f[:proc]) unless check_for_failed_condition(f[:conditions])
+          end
         end
       end
 
@@ -273,22 +281,25 @@ module Scorched
                 }.max || 0,
                 -idx
               ]
-            }.reverse.each { |match,|
+            }.reverse.each { |match,idx|
               request.breadcrumb << match
-              break if catch(:pass) {
+              catch(:pass) {
                 target = match.mapping[:target]
-                response.merge! begin
-                  if Proc === target
-                    instance_exec(&target)
-                  else
-                    target.call(env.merge(
-                      'SCRIPT_NAME' => request.matched_path.chomp('/'),
-                      'PATH_INFO' => request.unmatched_path[match.path.chomp('/').length..-1]
-                    ))
+                catch(:halt) do
+                  response.merge! begin
+                    if Proc === target
+                      instance_exec(&target)
+                    else
+                      target.call(env.merge(
+                        'SCRIPT_NAME' => request.matched_path.chomp('/'),
+                        'PATH_INFO' => request.unmatched_path[match.path.chomp('/').length..-1]
+                      ))
+                    end
                   end
                 end
                 @_handled = true
               }
+              break if @_handled
               request.breadcrumb.pop
             }
             unless @_handled
@@ -298,9 +309,13 @@ module Scorched
             rescue_block.call(inner_error)
           end
           run_filters(:after)
+          true
+        end || begin
+          run_filters(:before, true)
+          run_filters(:after, true)
         end
       rescue => outer_error
-        outer_error == inner_error ? raise : rescue_block.call(outer_error)
+        outer_error == inner_error ? raise : catch(:halt) { rescue_block.call(outer_error) }
       end
       response.finish
     end
@@ -388,7 +403,7 @@ module Scorched
       session[key]
     end
     
-    after do
+    after(force: true) do
       env['scorched.flash'].each { |k,v| session[k] = v } if session && env['scorched.flash']
     end
     
@@ -527,20 +542,29 @@ module Scorched
     
   private
   
-    def run_filters(type)
+    def run_filters(type, forced_only = false)
       tracker = env['scorched.executed_filters'] ||= {before: Set.new, after: Set.new}
-      filters[type].reject{ |f| tracker[type].include? f }.each do |f|
+      filters[type].reject{ |f| tracker[type].include?(f) || (forced_only && !f[:force]) }.each do |f|
         unless check_for_failed_condition(f[:conditions])
           tracker[type] << f
-          instance_exec(&f[:proc])
+          if forced_only
+            catch(:halt) do
+              instance_exec(&f[:proc]); true
+            end or log.warn "Ignored halt while running forced filters."
+          else
+            instance_exec(&f[:proc])
+          end
         end
       end
     end
     
-    def log(type, message)
+    def log(type = nil, message = nil)
       config[:logger].progname ||= 'Scorched'
-      type = Logger.const_get(type.to_s.upcase)
-      config[:logger].add(type, message)
+      if(type)
+        type = Logger.const_get(type.to_s.upcase)
+        config[:logger].add(type, message)
+      end
+      config[:logger]
     end
   end
 end

data/lib/scorched/static.rb

@@ -11,4 +11,4 @@ module Scorched
       response[0] >= 400 ? @app.call(env) : response 
     end
   end
-end
+end

data/lib/scorched/version.rb

@@ -1,3 +1,3 @@
 module Scorched
-  VERSION = '0.19'
+  VERSION = '0.20'
 end

data/spec/controller_spec.rb

@@ -270,6 +270,16 @@ module Scorched
         end
       end
       
+      it "provides wildcard captures as arguments" do
+        app.get('/*/**') { |a,b| "#{a}#{b}" }
+        rt.get('/hello/there/dude').body.should == 'hellothere/dude'
+      end
+      
+      it "provides named captures as a single hash argument" do
+        app.get('/:given_name/::surname') { |h| "#{h[:given_name]} #{h[:surname]}" }
+        rt.get('/bob/smith').body.should == 'bob smith'
+      end
+      
       it "always matches to the end of the URL (implied $)" do
         app.get('/') { 'awesome '}
         rt.get('/dog').status.should == 404
@@ -352,9 +362,9 @@ module Scorched
           response.body.should == 'roof'
         end
       
-        it "inherits from parent class, or any other class" do
-          app.controller.superclass.should == app
-          app.controller('/', String).superclass.should == String
+        it "inherits from parent class, or otherwise the specified class" do
+          app.controller{}.superclass.should == app
+          app.controller('/', String){}.superclass.should == String
         end
       
         it "can take mapping options" do
@@ -377,6 +387,14 @@ module Scorched
           rt.get('/').body.should == 'hello'
           filters_run.should == 0
         end
+        
+        it "can be used to map a predefined controller" do
+          person_controller = Class.new(Scorched::Controller) do
+            get('/name') { 'George' }
+          end
+          app.controller '/person', person_controller
+          rt.get('/person/name').body.should == 'George'
+        end
       end
     end
     
@@ -547,6 +565,12 @@ module Scorched
         rt.get('/').body.should == 'StandardErrorArgumentError'
       end
       
+      they "swallow halts when executed in an outer context" do
+        app.before { raise "Big bad error" }
+        app.error { throw :halt }
+        rt.get('/') # Would otherwise bomb out with uncaught throw.
+      end
+      
       they "only get called once per error" do
         times_called = 0
         app.error { times_called += 1 }
@@ -621,8 +645,8 @@ module Scorched
       end
       
       it "takes an optional status" do
-        app.get('/') { halt 401 }
-        rt.get('/').status.should == 401
+        app.get('/') { halt 600 }
+        rt.get('/').status.should == 600
       end
       
       it "takes an optional response body" do
@@ -631,21 +655,41 @@ module Scorched
       end
       
       it "can take a status and a response body" do
-        app.get('/') { halt 401, 'cool' }
-        rt.get('/').status.should == 401
+        app.get('/') { halt 600, 'cool' }
+        rt.get('/').status.should == 600
         rt.get('/').body.should == 'cool'
       end
       
-      it "skips processing filters" do
-        app.after { response.status = 403 }
+      it "still processes filters" do
+        app.after { response.status = 600 }
         app.get('/') { halt }
-        rt.get('/').status.should == 200
+        rt.get('/').status.should == 600
       end
       
-      it "short circuits filters if halted within filter" do
-        app.before { halt }
-        app.after { response.status = 403 }
-        rt.get('/').status.should_not == 403
+      describe "within filters" do
+        it "short circuits filters if halted within filter" do
+          app.before { halt }
+          app.after { response.status = 600 }
+          rt.get('/').status.should_not == 600
+        end
+        
+        it "forced filters are always run" do
+          app.before { halt }
+          app.after(force: true) { response.status = 600 }
+          app.after { response.status = 700 } # Shouldn't run because it's not forced
+          app.get('/') { 'hello' }
+          rt.get('/').status.should == 600
+        end
+        
+        it "halting within a forced filter still runs other forced filters" do
+          app.before { halt }
+          app.before(force: true) { halt }
+          app.before(force: true) { response.status = 600 }
+          app.get('/') { 'hello' }
+          rt.get('/').status.should == 600
+          app.after(force: true) { response.status = 700 }
+          rt.get('/').status.should == 700
+        end
       end
     end
     
@@ -674,6 +718,14 @@ module Scorched
         rt.get('/')
         var.should == false
       end
+      
+      it "works in filters" do
+        app.error { redirect '/somewhere' }
+        app.get('/') { raise "Some error" }
+        rt.get('/').location.should == '/somewhere'
+        app.before { redirect '/somewhere_else' }
+        rt.get('/').location.should == '/somewhere_else'
+      end
     end
     
     describe "passing" do

data/spec/helper.rb

@@ -3,6 +3,8 @@ ENV['RACK_ENV'] = 'production'
 require 'rack/test'
 require_relative '../lib/scorched.rb'
 
+Scorched::Controller.config[:logger] = Logger.new(nil)
+
 module Scorched
   class SimpleCounter
     def initialize(app)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scorched
 version: !ruby/object:Gem::Version
-  version: '0.19'
+  version: '0.20'
 platform: ruby
 authors:
 - Tom Wardrop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-29 00:00:00.000000000 Z
+date: 2013-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -172,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.0.6
 signing_key: 
 specification_version: 4
 summary: Light-weight, DRY as a desert, web framework for Ruby