scorched 0.7 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bbeb1df9d3b27b4e455d9c0ee30d282da0875a58
-  data.tar.gz: bf7ee84acc65b7bd2cd355afdca30150ac8b8f6a
+  metadata.gz: 9e853e2cdf6c23a10cebb3ada3d26cc90a0535b7
+  data.tar.gz: 2cfe230e619c9ad1f0304c35699ed55cdcc9e94b
 SHA512:
-  metadata.gz: a546b0e44c56adb26cc23d5d0fe40a60485467a50639c05fd36fadd8ce7dab591de8ff06b73c73756739ace69ab34a56402e9179d49e56b7a4920993050292d4
-  data.tar.gz: 3f85d181a8db836196db23099b6d5b49a424bad7d2f56c9e714021127ddcb9c4cf61664ec24b251d0affbd2aa4ea7fd0ea542b87f2a5124ba3100bd202938611
+  metadata.gz: 236012f2a5d523733f2fe8d81389d545d9bbb01a421f2840371e31f7f4b81ccf608cd7ba06838f0291a5bb0796271bd6e1e10de6b0a61301168b4c2865c52dbf
+  data.tar.gz: 2e531bf2da9a00ea4efedf2eaa18d2718d6c7bebc72cf47176f48ac6f4b35c2722f5974b4d72346e5d4d8375cfc4f091fc34af46d2d1165b9c762318ce941f0c

data/Milestones.md

@@ -3,19 +3,22 @@ Milestones
 
 Changelog
 ---------
+### v0.8
+* Changed `controller` method signature to accept an optional URL pattern as the first argument.
+* Implemented a pass mechanism to short-circuit out of the current match and invoke the next match.
+* Added `:auto_pass` configuration option. When true, if none of the controller's mapping match the request, the controller will `pass` back to the outer controller without running any filters.
+* Sub-controllers generated with the `controller` helper are automatically configured with `:auto_pass` set to `true`. This makes inline sub-controllers even more useful for grouping routes.
+
 ### v0.7
 * Logging preparations made. Now just have to decide on a logging strategy, such as what to log, how verbose the messages should be, etc.
-* Environment-specific defaults added. The environment variable ``RACK_ENV`` is used to determine the current environment.
-  * Non-Development
-    * ``config[:static_dir] = false``
-  * Development
-    * ``config[:show_exceptions] = true``
-    * ``config[:logger] = Logger.new(STDOUT)``
-    * Add developer-friendly 404 error page. This is implemented as an after filter, and won't have any effect if the response body is set.
-* ``absolute`` method now returns forward slash if script name is empty.
+* Environment-specific defaults added. The environment variable `RACK_ENV`s used to determine the current environment.
+    * Non-Development
+        * `config[:static_dir] = false`   * Development
+        * `config[:show_exceptions] = true`       * `config[:logger] = Logger.new(STDOUT)`       * Add developer-friendly 404 error page. This is implemented as an after filter, and won't have any effect if the response body is set.
+* `absolute`ethod now returns forward slash if script name is empty.
 
 ### v0.6
-* ``view_config`` options hash renamed to ``render_defaults`` which better reflects its function.
+* `view_config`ptions hash renamed to ` `render_defaults`ch better reflects its function.
 
 ### v0.5.2
 * Minor modification to routing to make it behave as a documented regarding matching at the directly before or on a path.
@@ -30,12 +33,10 @@ Changelog
 * Added session method for convenience, and implemented helper for flash session data.
 * Added cookie helper for conveniently setting, retrieving and deleting cookies.
 * Static file serving actually works now
-  * Custom middleware Scorched::Static serves as a thin layer on top of Rack::File.
+    * Custom middleware Scorched::Static serves as a thin layer on top of Rack::File.
 * Added specs for each configuration option.
 * Using Ruby 2.0 features where applicable. No excuse not to be able to deploy on 2.0 by the time Scorched is ready for production.
-  * Keyword arguments instead of ``*args`` combined with ``Hash === args.last``.
-  * Replaced instances of __FILE__ with __dir__.
-* Added expected Rack middleware, Rack::MethodOverride and Rack::Head.
+    * Keyword arguments instead of `*args`ombined with ` `Hash === args.last`  * Replaced instances of `__FILE__`ith ` `__dir__`Added expected Rack middleware, Rack::MethodOverride and Rack::Head.
     
 ### v0.4
 * Make filters behave like middleware. Inheritable, but are only executed once.
@@ -45,7 +46,7 @@ Changelog
 * Basic request handling and routing
 * String and Regex URL matching, with capture support
 * Implemented route conditions
-  * Added HTTP method condition which the route helpers depend on.
+    * Added HTTP method condition which the route helpers depend on.
 * Added route helpers
 * Implemented support for sub-controllers
 * Implement before and after filters with proper execution order.
@@ -53,7 +54,7 @@ Changelog
 * Mechanism for including Rack middleware.
 * Added more route conditions e.g. content-type, language, user-agent, etc.
 * Provide means to `halt` request.
-  * Added redirect helping for halting and redirecting request
+    * Added redirect helping for halting and redirecting request
 * Mechanism for handling exceptions in routes and before/after filters.
 * Added static resource serving. E.g. public folder.
 
@@ -61,27 +62,23 @@ Changelog
 
 To Do
 -----
-Some of these remaining features may be broken out into a separate contributor library to keep the core lean and focused.
+Some of these remaining features may be reconsidered and either left out, or put into some kind of contrib library.
 
 * Make specs for Collection and Options classes more thorough, e.g. test all non-reading modifiers such as clear, delete, etc.
-* Add view helpers
+* Implement template caching with option to disable/enable (disabled by default in development)
+* Add more view helpers, maybe?
   * Add helper to easily read and build HTTP query strings. Takes care of "?" and "&" logic, escaping, etc. This is
     intended to make link building easier.
   * Form populator implemented with Nokogiri. This would have to be added to a contrib library.
 * Add Verbose logging, including debug logging to show each routing hop and the current environment (variables, mode, etc)
-* Environment optimised defaults
-  * Production
-    * use Rack::Protection
-    * Disable static file serving. Sub-controllers can obviously override this. This will just change the default.
-  * Development
-    * Log to STDOUT
-    * use Rack::ShowExceptions
-    * Add developer-friendly 404 error page.
-    
+
+
 Unlikely
 --------
+These features are unlikely to be implemented unless someone provides a good reason.
+
 * Mutex locking option - I'm of the opinion that the web server should be configured for the concurrency model of the application, rather than the framework.
 * Using Rack::Protection by default - The problem here is that a good portion of Rack::Protection involves sessions, and given that Scorched doesn't itself load any session middleware, these components of Rack::Protection would have to be excluded. I wouldn't want to invoke a false sense of security
 
 
-More things will be added to these lists as they're thought of and considered.
+More things will be added as they're thought of and considered.

data/README.md

@@ -3,32 +3,39 @@
 
 Scorched is a generic, unopinionated, DRY, light-weight web framework for Ruby. It provides a generic yet powerful set of constructs for processing HTTP requests, with which websites and applications of almost any scale can be built.
 
-If you've used a light-weight DSL-based Ruby web framework before, such as a Sinatra, it should look familiar. Scorched is a true evolutionary enhancement of Sinatra, with more power, focus, and less clutter.
+If you've used a light-weight DSL-based Ruby web framework before, such as Sinatra, it should look familiar. Scorched is a true evolutionary enhancement of Sinatra, with more power, focus, and less clutter.
 
 Getting Started
 ---------------
 
 Install the canister...
 
-    gem install scorched
+```console
+$ gem install scorched
+```
 
 Open the valve...
 
-    # ruby
-    # hello_world.ru
-    require 'scorched'
-    class App < Scorched::Controller
-      get '/' do
-        'hello world'
-      end
-    end
-    run App
+```ruby
+# hello_world.ru
+require 'scorched'
+class App < Scorched::Controller
+  get '/' do
+    'hello world'
+  end
+end
+run App
+```
 
 And light the flame...
 
-    rackup hello_world.ru
+```console
+$ rackup hello_world.ru
+```
+
+#### A Note on Requirements
 
-_**Note**: Scorched requires Ruby 2.0 as it makes use of a couple of new features. By the time Scorched hits v1.0, there should be little reason not to be running Ruby 2.0._
+Scorched requires Ruby 2.0 as it makes use of a few new features. It is however, important to ensure your version of Ruby 2.0 includes [changeset 39919](http://bugs.ruby-lang.org/projects/ruby-trunk/repository/revisions/39919) in order to avoid suffering from [random segmentation faults](http://bugs.ruby-lang.org/issues/8100). The first official patch release of 2.0.0 should include the fix, otherwise you can patch it during installation with RVM.
 
 The Errors of Our Past
 ----------------------
@@ -54,42 +61,43 @@ Part of what keeps Scorched lightweight, is that unlike other lightweight web fr
 First Impressions
 -----------------
 
-    # ruby
-    class MyApp < Scorched::Controller
-      
-      # From the most simple route possible...
-      get '/' do
-        "Hello World"
-      end
-      
-      # To something that gets the muscle's flexing
-      route '/articles/:title/::opts', 2, methods: ['GET', 'POST'], content_type: :json do
-        # Do what you want in here. Note, the second argument is the optional route priority.
-      end
-      
-      # Anonymous controllers allow for convenient route grouping to which filters and conditions can be applied
-      controller conditions: {media_type: 'application/json'} do
-        get '/articles/*' do |page|
-          {title: 'Scorched Rocks', body: '...', created_at: '27/08/2012', created_by: 'Bob'}
-        end
-        
-        after do
-          response.body = response.body.to_json
-        end
-      end
-      
-      # The things you get for free by using Classes for Controllers (...that's directed at you Padrino)
-      def my_little_helper
-        # Do some crazy awesome stuff that no route can resist using.
-      end
-      
-      # You can always avoid the routing helpers and add mappings manually. Anything that responds to #call is a valid
-      # target, with the only minor exception being that proc's are instance_exec'd, not call'd.
-      self << {pattern: '/admin', priority: 10, target: My3rdPartyAdminApp}
-      self << {pattern: '**', conditions: {maintenance_mode: true}, target: proc { |env|
-        @request.body << 'Maintenance underway, please be patient.'
-      }}
+```ruby
+class MyApp < Scorched::Controller
+  
+  # From the most simple route possible...
+  get '/' do
+    "Hello World"
+  end
+  
+  # To something that gets the muscle's flexing
+  route '/articles/:title/::opts', 2, methods: ['GET', 'POST'], content_type: :json do
+    # Do what you want in here. Note, the second argument is the optional route priority.
+  end
+  
+  # Anonymous controllers allow for convenient route grouping to which filters and conditions can be applied
+  controller conditions: {media_type: 'application/json'} do
+    get '/articles/*' do |page|
+      {title: 'Scorched Rocks', body: '...', created_at: '27/08/2012', created_by: 'Bob'}
+    end
+    
+    after do
+      response.body = response.body.to_json
     end
+  end
+  
+  # The things you get for free by using Classes for Controllers (...that's directed at you Padrino)
+  def my_little_helper
+    # Do some crazy awesome stuff that no route can resist using.
+  end
+  
+  # You can always avoid the routing helpers and add mappings manually. Anything that responds to #call is a valid
+  # target, with the only minor exception being that proc's are instance_exec'd, not call'd.
+  self << {pattern: '/admin', priority: 10, target: My3rdPartyAdminApp}
+  self << {pattern: '**', conditions: {maintenance_mode: true}, target: proc { |env|
+    @request.body << 'Maintenance underway, please be patient.'
+  }}
+end
+```
 
 This API shouldn't look too foreign to anyone familiar with frameworks like Sinatra, and the potential power at hand should be obvious. The `route` method demonstrates a few minor features of Scorched:
 

data/docs/01_preface.md

@@ -1,6 +1,16 @@
 Preface
 =======
 
-_This is where I share with you all my infinite wisdom. It will come. In the mean time, know that the documentation is currently incomplete, and likely the victim of quite a few typos._
+This collection of documentation serves as a practical technical reference for using Scorched. It explains and demonstrates the use of all constructs, but not necessarily every method. For the story behind Scorched, refer to: http://scorchedrb.com/about
 
-_As an early adopter, feel free to use the Github issue tracker to ask questions and request assistance. Such questions will be used to further refine the documentation._
+
+Getting Started
+---------------
+If you haven't already done so, please refer to the [README](../README.md) for a generic introduction to Scorched, including how to get started.
+
+
+Who Should Use Scorched?
+------------------------
+Whilst Scorched is suitable for any Ruby developer, the documentation does assume you're comfortable programming in Ruby, and that you're familiar with Rack. It also assumes some prior experience with web development and HTTP. Scorched itself, as a very unopinionated and open-ended framework, doesn't necessarily serve the inexperienced developer. To get the most out of Scorched, you need to implement your ideas on top of it, using your preferred tools and techniques, which only a developer with the aforementioned experience will be able to do effectively.
+
+Those who will enjoy using Scorched the most, are creative developers who like to apply their own values, ideas, and  toolset to solving web development problems. Anyone who doesn't like Rails should love Scorched.

data/docs/02_fundamentals/01_the_controller.md

@@ -1,19 +1,140 @@
 The Controller
 ==============
 
-Scorched consists almost entirely of the ``Scorched::Controller``. The Controller is the class from which your application class inherits. All the code examples provided in the documentation are assumed to be wrapped within a controller class.
+Scorched consists almost entirely of the `Scorched::Controller`. The Controller is the class from which your application class inherits. All the code examples provided in the documentation are assumed to be wrapped within a controller class.
 
-    # ruby
-    class MyApp < Scorched::Controller
-      # We are now within the controller class.
-      # Most examples are assumed to be within this context.
+```ruby    
+class MyApp < Scorched::Controller
+  # We are now within the controller class.
+  # Most examples are assumed to be within this context.
+end
+```
+
+Your application's root controller (named `MyApp` in the example above), should be configured as the _run_ target in your rackup file:
+
+```ruby
+# config.ru
+require './myapp.rb'
+run MyApp
+```
+
+Sub-Controllers
+---------------
+One of the core features of Scorched is the fact that Controller's are intended to be inheritable and nestable as sub-controllers. This is perhaps the main advantage of Scorched over the likes of Sinatra and Padrino, and is one of the key innovations of the framework.
+
+For the most part, you will find yourself breaking up your application into many discrete controllers. This will allow you to scope your configuration, filters, error handlers, and conditions, to logical groups of routes. This can save a lot of code repetition, keeping your code DRY, hence the name _Scorched_.
+
+A sub-controller is any controller that's mapped by another controller. `ControllerB` in the following example, is one example of a sub-controller.
+
+``` ruby
+class ControllerA < Scorched::Controller
+  get '/' do
+    "Hello there"
+  end
+  
+  after do
+    response.body[0] << '.' # Always forgetting to add my periods
+  end
+end
+
+class ControllerB < Scorched::Controller
+  get '/' do
+    "I'm apparently a sub-controller"
+  end
+end
+
+ControllerA << {pattern: '/sub', target: ControllerB}
+```
+
+The  previous example is awfully crude, but it hopefully demonstrates that there's absolutely no magic happening here. In that previous example, a request for `/sub` will pass through `ControllerA` and onto `ControllerB`, before heading back out the way it came. Hence, a request for `/sub` will yield `I'm apparently a sub-controller.`; note the period added by ControllerA's _after_ filter (more on _after_ filters later).
+
+While in the previous example, `ControllerB` counts as a sub-controller in that it's nested within ControllerA, at least from a routing perspective, `ControllerA` and `ControllerB` are completely unrelated; they share nothing.
+
+A lot can be gained by not only nesting `ControllerB` within `ControllerA`, but by also inheriting from it.
+
+``` ruby
+class ControllerA < Scorched::Controller
+  render_defaults[:dir] = 'views'
+  render_defaults[:layout] = :main
+  
+  conditions[:user] = proc { |usernames|
+    [*usernames].include? session['username']
+  }
+  
+  
+  get '/' do
+    bold "Hello there"
+  end
+  
+  def bold(str)
+    "<strong>#{str}</strong>"
+  end
+end
+
+class ControllerB < Scorched::Controller
+  render_defaults[:layout] = :controller_b
+  
+  get '/', user: 'bob' do
+    bold "I'm apparently a sub-controller"
+  end
+end
+
+ControllerA << {pattern: '/sub', target: ControllerB}
+```
+
+Now that `ControllerB` is inheriting from `ControllerA`, it not only gets access to all its methods, such as the very helpful `bold`, but it also inherits anything configured on `ControllerA`, such as rendering defaults, filters, middleware, conditions, etc. Very handy.
+
+You can use nesting and inheritance exclusively, or together, depending on your needs.
+
+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.
+
+``` 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
+  
+  controller '/sub' do
+    render_defaults[:layout] = :controller_b
+  
+    get '/', user: ['bob', 'jeff'] do
+      bold "I'm apparently a sub-controller"
     end
+  end
+  
+  def bold(str)
+    "<strong>#{str}</strong>"
+  end
+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 optional URL pattern defaults to `'/'` which can be handy for grouping a set of routes. 
 
-Your application's root controller (named ``MyApp`` in the example above), should be configured as the _run_ target in your rackup file:
+``` ruby
+class MyApp < Scorched::Controller
+  get '/' do
+    bold "Hello there"
+  end
+  
+  controller conditions: {media_type: 'application/json'} do
+   
+  end
+end
+```
 
-    # ruby
-    # config.ru
-    require './myapp.rb'
-    run MyApp
+The Root Controller
+-------------------
+Although you will likely have a main controller to serve as the target for Rack, Scorched does not have the concept of a root controller. It mades no differentiation between a sub-controller and any other controller. All Controllers are made equal.
 
-The rest of the documentation will detail the Controller more thoroughly.
+You can arrange and nest your controllers in any way, shape or form. Scorched has been designed to not make any assumptions about how you structure your controllers, which can accommodate very creative solutions.

data/docs/02_fundamentals/02_configuration.md

@@ -3,34 +3,36 @@ Configuration
 
 Scorched includes a few configurable options out of the box. These all have common defaults, or are otherwise left intentionally blank to ensure the developer opts-in to any potentially undesirable or surprising behaviour.
 
-There are two sets of configurables. Those which apply to views, and everything else. Each set of configuration options is a ``Scorched::Options`` instance. This allows configuration options to be inherited and subsequently overriden by child classes. This is handy in many instances, but a common requirement might be to change the view directory or default layout of some sub-controller.
+There are two sets of configurables. Those which apply to views, and everything else. Each set of configuration options is a `Scorched::Options` instance. This allows configuration options to be inherited and subsequently overridden by child classes. This is handy in many instances, but a common requirement might be to change the view directory or default layout of some sub-controller.
 
 Options
 -------
 
-Each configuration is listed below, with the default value of each included.
+Each configuration is listed below, with the default value of each included. Note, environment specific defaults may override the default values below.
 
-* ``config[:strip_trailing_slash] = :redirect``  
+* `config[:strip_trailing_slash] = :redirect`  
     Controls how trailing forward slashes in requests are handled.
-    * ``:redirect`` - Strips and redirects URL's ending in a forward slash
-    * ``:ignore`` - Internally ignores trailing slash
-    * ``false`` - Does nothing. Respects the presence of a trailing forward flash.
-* ``config[:static_dir] = 'public'``  
+    * `:redirect` - Strips and redirects URL's ending in a forward slash
+    * `:ignore` - Internally ignores trailing slash
+    * `false` - Does nothing. Respects the presence of a trailing forward flash.
+* `config[:static_dir] = 'public'`  
     The directory Scorched should serve static files from. Should be set to false if the web server or some other middleware is serving static files.
-* ``config[:logger] = Logger.new(STDOUT)`` - Currently does nothing until logging is added to Scorched.
+* `config[:logger] = Logger.new(STDOUT)` - Currently does nothing until logging is added to Scorched.
+* `config[:auto_pass] = false` -  If no routes within the current controller match, automatically _pass_ the request back to the outer controller without running any filters. This makes sub-controllers behave more like a kind-of route group.
 
-You can also configure the default options when rendering views by setting them on the ``render_defaults`` hash. The options specified here are merged with those provided when calling the ``render`` method, with the explicit options obviously taking precedence over the defaults.
+You can also configure the default options when rendering views by setting them on the `render_defaults` hash. The options specified here are merged with those provided when calling the `render` method, with the explicit options obviously taking precedence over the defaults.
 
 Refer to the _views_ page for more information.
 
-Here is an example of the configuration options in action. A couple of different ways to set the options are shown. Refer to the API documentation for the ``Scorched::Options`` for more information.
-
-    # ruby
-    class MyApp < Scorched::Controller
-      config[:static_dir] = '../public'
-      render_defaults.merge!(
-        dir: 'templates',
-        layout: :main_layout
-        engine: :haml
-      )
-    end
+Here is an example of the configuration options in action. A couple of different ways to set the options are shown. Refer to the API documentation for the `Scorched::Options` for more information.
+
+```ruby
+class MyApp < Scorched::Controller
+  config[:static_dir] = '../public'
+  render_defaults.merge!(
+    dir: 'templates',
+    layout: :main_layout
+    engine: :haml
+  )
+end
+```