scorched 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc95df5b8180579cc08c6d839b56dc64ad9105b1
-  data.tar.gz: 0a445e9f72ee7aaf30c7f0aa8a9cc93ec5c919ee
+  metadata.gz: b0950b3928b9921a50ec7af0cb01869412172f09
+  data.tar.gz: b698623e4b6e40a64cf56ac47b7d20be50df4c2f
 SHA512:
-  metadata.gz: 2a46ef33d42014a33f3d0abc9d0009714f088caeaaba24633e72c1d25ad033838b5a693c53bfdf5dbaf9b1ae6c0dd714d5d8f52c17e0dcceadc9773dad558ac9
-  data.tar.gz: 2446404ea7aa8a28d140921d66142fd292f51b492fabb7029f7a3d632ba97a1707425589b11ecf46b58b1e35563f2f7d6e530d88ae26ca04858d24bba7890033
+  metadata.gz: e528fe6a63bfdd08127ff405e83541a5a6032fa6db1746be18c50a0e9488de6eba591b720fb218fda4378e42b244eba4246be71fb4bc8c384921cdd9c2c2bca8
+  data.tar.gz: 00f71b40921a073e043a985e693e8a2924c93f16a4221a2f5efcf72588d90515846c67151302cd931d1af7fe112884c17f2424c068bbd82e83170de954f1ce12

data/Milestones.md

@@ -3,6 +3,9 @@ Milestones
 
 Changelog
 ---------
+### v0.5.2
+* Response content-type now defaults to "text/html;charset=utf-8", rather than empty.
+
 ### v0.5.1
 * Added URL helpers, #absolute and #url
 * Render helper now loads files itself as Tilt still has issues with UTF-8 files.

data/README.md

@@ -1,20 +1,39 @@
-Scorched
-========
+[Simple, Powerful, Scorched](http://scorchedrb.com)
+==========================
 
-*Light-weight, DRY as a desert, web framework for Ruby. Inspired by Sinatra, this framework is my vision of the next evolutionary step in light-weight ruby web frameworks.*
+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.
 
-Scorched honours the patrons of the past. It's not a complete reinvention of the lightweight web framework, but rather what I hope is an evolutionary enhancement. Most of the concepts are carried forward from predecessors. Scorched merely enhances those concepts in an attempt to extract their full potential, as well as offering up to scrutiny some entirely new idioms. All with the intention to make developing lightweight web apps in Ruby even more enjoyable.
+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.
 
-The name 'Scorched' is inspired by the main goal of the project, which is to DRY-up what the likes of Sinatra and Padrino left moist.
+Getting Started
+---------------
 
+Install the canister...
 
-The Errors of Our Past (aka. Areas of Moisty-ness)
---------------------------------------------------
-I think the biggest mistake made by the predecessors of Scorched such as Sinatra/Padrino, was to not leverage the power
-of the class. The consequences of this made for some awkwardness. Helpers are a classical reinvention of what
-classes and modules were already made to solve. Scorched implements Controllers as Classes, which in addition to having their own DSL, allow defining and calling traditional class methods. Allowing developers to implement helpers and other common functionality as proper methods not only makes them more predictable and familiar, but of course allow such helpers to be inheritable via plain-old Class inheritance.
+    gem install scorched
 
-Perhaps another error (or area of sogginess, if you will) has been a lack of consideration for the hierarchical nature of websites, and the fact that sub-directories are often expected to inherit attributes of their parents. Scorched supports sub-controllers to any arbitrary depth, with each controllers filters and route conditions applied along the way. This can assist many areas of web development, including security, restful interfaces, and interchangeable output formats.
+Open the valve...
+
+    # 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
+
+
+The Errors of Our Past
+----------------------
+One of the big mistakes made by a lot of other Ruby frameworks, was to not leverage the power of the class. The consequences of this made for some awkwardness. Helpers for example, are a classical reinvention of what classes and modules were already made to solve. Scorched implements Controllers as Classes, which in addition to having their own DSL, allow defining and calling traditional class methods. The decision to allow developers to implement helpers and other common functionality as proper methods not only makes Controllers somewhat more predictable and familiar, but of course allow such helpers to be inheritable via plain-old Class inheritance.
+
+Perhaps another design oversight of other frameworks, has been the lack of consideration for the hierarchical nature of websites, and the fact that sub-directories are often expected to inherit attributes of their parents. Scorched supports sub-controllers to any arbitrary depth, with each controllers configuration, filters, route conditions, etc, applied along the way. This can assist many areas of web development, including security, restful interfaces, and interchangeable content types.
 
 
 Design Philosophy
@@ -33,28 +52,28 @@ Part of what keeps Scorched lightweight, is that unlike other lightweight web fr
 
 First Impressions
 -----------------
-Below I present a sample of the API as it currently stands:
 
+    # ruby
     class MyApp < Scorched::Controller
-
+      
       # From the most simple route possible...
       get '/' do
         "Hello World"
       end
       
-      # To something that gets the muscle's flexing a little
+      # 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: {content_type: :json} do
+      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.to_json
+          response.body = response.body.to_json
         end
       end
       
@@ -63,21 +82,20 @@ Below I present a sample of the API as it currently stands:
         # 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 << {url: '/admin', priority: 10, target: My3rdPartyAdminApp}
-      self << {url: '**', conditions: {maintenance_mode: true}, target: proc { |env|
+      # 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:
 
 * Multi-method routes - Because sometimes the difference between a GET and POST can be a single line of code. If no methods are provided, the route receives all HTTP methods.
 * Named Wildcards - Not an original idea, but you may note the named wildcard with the double colon. This maps to the '**' glob directive, which will span forward-slashes while matching. The single asterisk (or colon) behaves like the single asterisk glob directive, and will not match forward-slashes.
 * Route priorities - Routes (referred to as mappings internally) can be assigned priorities. A priority can be any arbitrary number by which the routes are ordered. The higher the number, the higher the priority.
-* Conditions - Conditions are merely procs defined on the controller which are inherited (and can be overriden) by child controllers. When a request comes in, mappings that match the requested URL, first have their conditions evaluated in the context of the controller instance, before control is handed off to the target associated with that mapping. It's a very simple implementation that comes with a lot of potential.
-
-That should hopefully give you an example of how the core of Scorched is shaping up. This demonstrates only a subset of what Scorched will offer.
+* Conditions - Conditions are merely procs defined on the controller which are inherited (and can be overriden) by child controllers. When a request comes in, mappings that match the requested URL, first have their conditions evaluated in the context of the controller instance, before control is handed off to the target associated with that mapping. It's a very simple implementation that comes with a lot of flexibility.
 
 
 Development Progress

data/docs/01_preface.md

@@ -0,0 +1,6 @@
+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._
+
+_As an early adopter, feel free to use the Github issue tracker to ask questions and request assistance._

data/docs/02_fundamentals/01_the_controller.md

@@ -0,0 +1,19 @@
+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.
+
+    # 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
+
+The rest of the documentation will detail the Controller more thoroughly.

data/docs/02_fundamentals/02_configuration.md

@@ -0,0 +1,29 @@
+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.
+
+Options
+-------
+
+Each configuration is listed below, with the default value of each included.
+
+* ``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'``  
+    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.
+
+The follow view configuration options can all be overriden when calling ``render``.
+
+* ``view_config[:dir] = 'views'``  
+    The directory containing all the view templates, relative to the current working directory.
+* ``view_config[:layout] = false``  
+    The default layout to use when rendering views. 
+* ``view_config[:engine] = :erb``  
+    The default rendering engine. This is used when ``render`` is given a filename with no extension, or a string.

data/docs/02_fundamentals/03_routing.md

@@ -0,0 +1,92 @@
+Routing
+=======
+
+When Scorched receives a request, the first thing it does is iterate over it's internal mapping hash, looking for the any URL pattern that matches the current URL. If it finds an appropriate match, it invokes the ``call`` method on the target defined for that mapping, unless the target is a ``Proc``, in which case it's invoked via ``instance_exec`` to run it within the context of the controller instance.
+
+Mappings can be defined manually using the ``map`` class method, also aliased as ``<<``. Besides the required URL pattern and target elements, a mapping can also define a priority, and one or more conditions. The example below demonstrates the use of all of them.
+
+    # ruby
+    map pattern: '/', priority: -99, conditions: {methods: ['POST', 'PUT', 'DELETE']}, target: proc { |env|
+      [200, {}, 'Bugger off']
+    }
+
+The position the new mapping is inserted into the mapping hash is determined by it's priority, and the priority of the mappings already defined. This avoids re-sorting the mapping hash every time it's added to. This isn't a performance consideration, but is required to maintain the natural insert order of the mappings which have identical priorities (such as the default 0).
+
+A ``mapping`` method is also provided as means to access all defined mappings on a controller, but it should be considered read-only for the reasons just stated.
+
+Route Helpers
+-------------
+Adding mappings manually can be a little verbose and painful, which is why Scorched includes a bunch of route helpers which are used in most code examples.
+
+The main route helper which all others delegate to, is the ``route`` class method. Here's what it looks like in both it's simple and advance form:
+
+    # ruby
+    route '/' do
+      'Well hello there'
+    end
+    
+    route '/*', 5, methods: ['POST', 'PUT', 'DELETE'] do |capture|
+      "Hmm trying to change #{capture} I see"
+    end
+
+You can see pretty clearly how these examples correspond to the pattern, priority, conditions and target options of a manual mapping. The pattern, priority and conditions behave exactly as they do for a manual mapping, with a couple of exceptions.
+
+The first exception is that the pattern must match to the end of the request path. This is mentioned in the _pattern matching_ section below.
+
+The other more notable exception is in how the given block is treated. The block given to the route helper is wrapped in another proc. The wrapping proc does a couple of things. It first sends all the captures in the url pattern as argument to the given block, this is shown in the example above. The other thing it does is takes care of assigning the return value to the body of the response.
+
+In the latter of the two examples above, a ``:methods`` condition defines what methods the route is intended to process. The first example has no such condition, so it accepts all HTTP methods. Typically however, a route will handle a single HTTP method, which is why Scorched also provides the convenience helpers: ``get``, ``post``, ``put``, ``delete``, ``head``, ``options``, and ``patch``. These methods automatically define the corresponding ``:method`` condition, with the ``get`` helper also including ``head`` as an accepted HTTP method.
+
+Pattern Matching
+----------------
+All patterns attempt to match the remaining unmatched portion of the _request path_; the _request path_ being Rack's
+``path_info`` request variable. The unmatched path will always begin with a forward slash if the previously matched portion of the path ended immediately before, or included as the last character, a forward slash. As an example, if the request was to "/article/21", then both "/article/" => "/21" and "/article" => "/21" would match.
+
+All patterns must match from the beginning of the path. So even though the pattern "article" would match "/article/21", it wouldn't count as a match because the match didn't start at a non-zero offset.
+
+If a pattern contains named captures, unnamed captures will be lost - this is how named regex captures work in Ruby. So if you name one capture, make sure you name any other captures you may want to access.
+
+Patterns can be defined as either a String or Regexp.
+
+###String Patterns
+String patterns are compiled into Regexp patterns corresponding to the following rules:
+
+* `*` - Matches all characters excluding the forward slash.
+* `**` - Matches all characters including the forward slash.
+* `:param` - Same as `*` except the capture is named to whatever the string following the single-colon is.
+* `::param` - Same as `**` except the capture is named to whatever the string following the double-colon is.
+* `$` - If placed at the end of a pattern, the pattern only matches if it matches the entire path. For patterns defined using the route helpers, e.g. ``Controller.route``, ``Controller.get``, this is implied. 
+
+###Regex Patterns
+Regex patterns offer more power and flexibility than string patterns (naturally). The rules for Regex patterns are identical to String patterns, e.g. they must match from the beginning of the path, etc. 
+
+
+Conditions
+----------
+Conditions are essentially just pre-requisites that must be met before a mapping is invoked to handle the current request. They're implemented as ``Proc`` objects which take a single argument, and return true if the condition is satisfied, or false otherwise. Scorched comes with a number of pre-defined conditions included, many of which are provided by _rack-accept_ - one of the few dependancies of Scorched.
+
+* ``:charset`` - Character sets accepted by the client.
+* ``:encoding`` - Encodings accepted by the client.
+* ``:host`` - The host name (i.e. domain name) used in the request.
+* ``:language`` - Languages accepted by the client.
+* ``:media_type`` - Media types (i.e. content types) accepted by the client.
+* ``:methods`` - The request method used, e.g. GET, POST, PUT, ...
+* ``:user_agent`` - The user agent string provided with the request. Takes a Regexp or String.
+* ``:status`` - The response status of the request. Intended for use by _after_ filters.
+
+Like configuration options, conditions are implemented using the ``Scorched::Options`` class, so they're inherited and be overridable by child classes. You may easily add your own conditions as the example below demonstrates.
+
+    # ruby
+    condition[:has_permission] = proc { |v|
+      user.has_permission == v
+    }
+    
+    get '/', has_permission: true do
+      'Welcome'
+    end
+    
+    get '/', has_permission: false do
+      'Forbidden'
+    end
+
+Each of the built-in conditions can take a single value, or an array of values, with the exception of the ``:host`` and ``:user_agent`` conditions which support Regexp patterns.

data/docs/02_fundamentals/04_requests_and_responses.md

@@ -0,0 +1,30 @@
+Requests and Responses
+======================
+One of the first things a controller does when it instantiates itself, is make the Rack environment hash accessible via the ``env`` helper, as well as make available a ``Scorched::Request`` and ``Scorched::Response`` object under the respective ``request`` and ``response`` methods.
+
+The ``Scorched::Request`` and ``Scorched::Response`` classes are children of the corresponding _Rack_ request and response classes, with a little extra functionality tacked on.
+
+The _request_ object makes accessible all the information associated with the current request, such as the GET and POST data, server and environment information, request headers, and so on. The _response_ is much the same, but in reverse. You'll use the _response_ object to set response headers and manipulate the body of the response.
+
+Refer to the _Rack_ documentation for more information on the ``Rack::Request`` and ``Rack::Response`` classes.
+
+
+Scorched Extras
+---------------
+As mentioned, Scorched tacks a few extras onto it's ``Scorched::Request`` and ``Scorched::Response`` classes. Most of these extras were added as a requirement of the Scorched controller, but they're just as useful to other developers.
+
+Refer to the generated API documentation for ``Scorched::Request`` and ``Scorched::Response``.
+
+
+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.
+
+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 ``throw :halt``. Calling ``halt`` is often preferred though because as well as being shorter, it can take an optional argument to set the response status, which is something you typically want to do when halting a request.
+
+
+Redirections
+------------
+A common requirement of many applications is to redirect requests to another URL based on some kind of condition. Scorched offers the very simple ``redirect`` method which takes one argument - the URL to redirect to. Like ``halt`` it's mostly a convenience method. It sets the _Location_ header of the response before halting the request.

data/docs/02_fundamentals/05_filters.md

@@ -0,0 +1,45 @@
+Filters
+=======
+Filters serve as a handy place to put functionality and behaviour that's common to a set of routes, or for that matter, a whole website or application. Filters are executed in the context of the controller; the same context as routes. Filters are also inheritable, meaning sub-classes inherit the filters of their parent - this inheritance is enabled through the use of the ``Scorched::Collection`` class, and is implemented such that each filter will only run once per-request.
+
+There are currently two types of filter in Scorched, both of which are documented below.
+
+
+Before and After Filters
+------------------------
+Before and After filters allow pre- and post-processing of requests. They are executed before and after each request, respectively.
+
+    # ruby
+    before do
+      raise Error, "Must be logged in to access this site" unless session[:logged_in] == true
+    end
+
+Like routes, filters can have conditions defined on them, for example:
+
+    # ruby
+    after media_type: 'application/json' do
+      response.body.to_json!
+    end
+
+Before and after filters run even if no route within the controller matches. This makes them suitable for handling 404 errors for example.
+
+    # ruby
+    after status: 404 do
+      response.body = render(:not_found)
+    end
+
+Your imagination is the only limitation.
+
+
+Error Filters
+-------------
+Error filters are processed like regular filters, except they're called whenever an exception occurs. If an error filter returns false, it's assumed to be unhandled, and the next error filter is called. This continues until one of the following is true, 1) an error filter returns true, in which case the exception is assumed to be handled, 2) an error filter raises an exception itself, or 3) there are no more error handlers defined on the current controller, in which case the exception is re-raised.
+
+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.
+
+    # ruby
+    error PermissionError do |e|
+      flash[:error] = "You do not have the appropriate permission to perform that action: #{e.message}"
+    end

data/docs/02_fundamentals/06_middleware.md

@@ -0,0 +1,18 @@
+Middleware
+==========
+
+While middleware can be added in your _rackup_ file to wrap your Scorched application, it can be more desirable to add the middleware at the controller level. Scorched itself requires this as it needs to include a set of Rack middleware out-of-the-box. Developers can't be expected to manually add these to their rackup file for every Scorched application.
+
+Like _filters_, middleware is inheritable thanks to it's use of the ``Scorched::Collection`` class. Also like _filters_, middleware proc's are only run once per request, which prevents unintended double-loading of middleware.
+
+Adding middleware to a Scorched controller involves pushing a proc onto the end of the middleware collection, accessible via the ``middleware`` accessor method. The given proc is ``instance_exec``'d in the context of a Rack builder object, and so can be used for more than just loading middleware. 
+
+    # ruby
+    middleware << proc do
+      use Rack::Session::Cookie, secret: 'blah'
+      # Stolen from Rack's own documentation...
+      map "/lobster" do
+        use Rack::Lint
+        run Rack::Lobster.new
+      end
+    end

data/docs/02_fundamentals/07_request_and_session_data.md

@@ -0,0 +1,89 @@
+Request and Session Data
+========================
+
+GET and POST Data
+-----------------
+Many ruby frameworks provide helpers for accessing GET and POST data via some kind of generic accessor, such as a ``params`` method, but Rack already provides this functionality out of the box, and more.
+
+    # ruby
+    post '/' do
+      request.GET['view'] # Key/value pairs submitted in the query string of the URL.
+      request.POST['username'] # Key/value pairs submitted in the payload of a POST request.
+      request.params[:username] # A merged hash of GET and POST data.
+      request[:username] # Shortcut to merged hash of GET and POST data.
+    end
+
+Uploaded files are also accessible as ordinary fields, except the associated value is a hash of properties, instead of a string. An example of an application that accepts file uploads is included in the "examples" directory of the Scorched git repository.
+
+Cookies
+-------
+While Rack provides a relatively simple means of setting, retrieving and deleting cookies, Scorched aggregates those three actions into a single method, ``cookie``, for the sake of brevity and simplicity.
+
+    # ruby
+    def '/' do
+      cookie :previous_page # Retrieves the cookie.
+      cookie :previous_page, '/search' # Sets the cookie
+      cookie :previous_page, nil # Deletes the cookies
+    end
+   
+For each of the above lines, the corresponding Rack methods are called, e.g. ``Rack::Requeste#cookies``, ``Rack::Response#set_cookie`` and ``Rack::Response#delete_cookie``. The values for setting and deleting a cookie can also be a hash, like ``set_cookie`` and ``delete_cookie`` can take directly. Deleting still works when a Hash is provided, as long as the ``value`` property is nil.
+
+    # ruby
+    def '/' do
+      cookie :view, path: '/account', value: 'datasheet' # Sets the cookie
+      cookie :view, path: '/account', value: nil # Deletes the cookie
+    end
+
+
+Sessions
+--------
+Sessions are completely handled by Rack. For conveniance, a ``session`` helper is provided. This merely acts as an alias to ``request['rack.session']`` however. It was raise an exception if called without any Rack session middleware loaded, such as ``Rack::Session::Cookie``.
+
+    # ruby
+    class App < Scorched::Controller
+      middleware << proc {
+        use Rack::Session::Cookie, secret: 'blah'
+      }
+      
+      get '/' do
+        session['logged_in'] ? 'You're currently logged in.' : 'Please login.'
+      end
+    end
+
+###Flash
+A common requirement for websites, and especially web applications, is to provide a message on the next page load corresponding to an action that a user just performed. A common framework idiom that Scorched happily implements are flash session variables - special session data that lives for only a single page load.
+
+This isn't as trivial to implement as it may sound at a glance, which is why Scorched provides this helper.
+
+    # ruby
+    get '/' do
+      "<span class="success">#{flash[:success]}</span>" if flash[:success]
+    end
+    
+    post '/login' do
+      flash[:success] = 'Logged in successfully.'
+    end
+
+The flash helper allows multiple sets of flash session data to be stored under different names. Because of how flash sessions are implemented, they're only deleted on the next page load if that particular flash data set is accessed. These properties of flash sessions can satisfy some interesting use cases. Here's a very uninteresting example:
+
+    # ruby
+    class App < Scorched::Controller
+      get '/' do
+        "<span class="success">#{flash[:success]}</span>" if flash[:success]
+      end
+    
+      post '/login' do
+        flash[:success] = 'Logged in successfully.'
+        if user.membership_type == 'vip' && user.membership_expiry < 5
+          flash(:vip)[:warning] = 'Your VIP membership is about to expire, please renew it.'
+        end
+      end
+      
+      controller pattern: '/vip' do
+        get '/' do
+          "<span class="warning">#{flash(:vip)[:warning]}</span>" if flash(:vip)[:warning]
+        end
+      end
+    end
+
+In the rather contrived example above, when a VIP user logs in, a message is generated and stored as a flash session variable in the ``:vip`` flash data set. Because the ``:vip`` flash data set isn't accessed on the main page, it lives on until it's finally re-accessed on the VIP page.

data/docs/02_fundamentals/08_views.md

@@ -0,0 +1,4 @@
+Views
+=====
+
+_More documentation coming soon. Until then, as a tip, the whole view infrastructure of Scorched is implemented as the ``render`` method._

data/docs/02_fundamentals/09_sharing_request_state.md

@@ -0,0 +1,16 @@
+Sharing and Managing Request State
+==================================
+Because Scorched allows sub-controllers to an arbitrary depth and treats all controllers equal (i.e it has no concept of a _root_ controller), it means instance variables and the likes cannot be used to track, maintain or share request state between controllers. I mention this because instance variables are the most common way to manage the request state in frameworks such as Sinatra.
+
+The only data exchanged between controllers is the Rack environment hash. Using the Rack environment hash is the only thread-safe way to manage the request state between controllers. As an example use case, consider the Scorched implementation of flash session data. Flash session data must be shared between controllers throughout the life of the request. The rack environment hash is the only suitable place to store this data.
+
+The Rack idiom is to namespace your keys, typically with your project name, using dots as delimiters. You can further group your keys using more dot-delimited namespaces. Perhaps an example is due:
+
+    # ruby
+    before user_agent: /MSIE|Windows/ do
+      env['myapp.dangerous_request'] = true
+    end
+    
+    get '/' do
+      "Welcome to #{env['myapp.settings.site_name']}!"
+    end

data/docs/03_further_reading/be_creative.md

@@ -0,0 +1,45 @@
+Be Creative
+===========
+Getting the most out of Scorched requires a bit of creative thinking. A couple of examples are given below.
+
+Effortless REST
+---------------
+An DRY way to serve multiple content-types:
+
+    # ruby
+    class App < Scorched::Controller
+      def view(view = nil)
+        view ? env['app.view'] = view : env['app.view']
+      end
+      
+      after do
+        data = response.body.join('')
+        response['Content-type'] = 'text/html'
+        if check_condition?(:media_type, 'text/html')
+          response.body = render(view, locals: {data: data})
+        elsif check_condition?(:media_type, 'application/json')
+          response['Content-type'] = 'application/json'
+          response.body = data.to_json
+        elsif check_condition?(:media_type, 'application/pdf')
+          response['Content-type'] = 'text/plain'
+          response.status = 406
+          response.body = 'PDF rendering service currently unavailable.'
+        else
+          response.body = render(view, locals: {data: data})
+        end
+      end
+      
+      get '/' do
+        view :index
+        [
+          {title: 'Sweet Purple Unicorns', date: '08/03/2013'},
+          {title: 'Mellow Grass Men', date: '21/03/2013'}
+        ]
+      end
+    end
+  
+
+Authentication and Permissions
+------------------------------
+
+_Example coming soon._

data/examples/file_upload.ru

@@ -0,0 +1,44 @@
+require File.expand_path('../../lib/scorched.rb', __FILE__)
+
+class MediaTypesExample < Scorched::Controller
+  
+  get '/' do
+    response['Content-Type'] = 'text/html'
+    <<-HTML
+      <form method="POST" action="#{absolute(request.matched_path)}" enctype="multipart/form-data">
+        <input type="file" name="example_file" />
+        <input type="submit" value="Submit" />
+      </form>
+    HTML
+  end
+  
+  post '/' do
+    example_file = request[:example_file]
+    <<-HTML
+      We know the following about the received file.
+      <ul>
+        <li><strong>Name:</strong> #{example_file[:filename]}</li>
+        <li><strong>Supposed Type:</strong> #{example_file[:type]}</li>
+        <li><strong>Actual Type:</strong> <em>Just pretend we are using MimeMagic</em></li>
+        <li><strong>Size:</strong> #{format_byte_size example_file[:tempfile].size}</li>
+      </ul>
+    HTML
+  end
+  
+  after do
+    response['Content-Type'] = 'text/html; charset=utf-8' unless response['Content-Type']
+  end
+  
+  # My self-proclaimed awesome byte size formatter: https://gist.github.com/Wardrop/4952405
+  def format_byte_size(bytes, opts = {})
+    opts = {binary: true, precision: 2, as_bits: false}.merge(opts)
+    suffixes = ['bytes', 'KB', 'MB', 'GB', 'TB', 'PB','EB', 'ZB', 'YB']
+    opts[:as_bits] && suffixes[0] = 'bits' && suffixes[1..-1].each { |v| v.downcase! } && bytes *= 8
+    opts[:binary] ? base = 1024 : (base = 1000) && suffixes[1..-1].each { |v| v.insert(1,'i') }
+    exp = Math.log(bytes, base).floor
+    "#{(bytes.to_f / (base ** exp)).round(opts[:precision])} #{suffixes[exp]}"
+  end
+  
+end
+
+run MediaTypesExample

data/examples/media_types.ru

@@ -1,2 +1,26 @@
-require './media_types.rb'
+require 'json'
+require File.expand_path('../../lib/scorched.rb', __FILE__)
+
+class MediaTypesExample < Scorched::Controller
+  
+  get '/', media_type: 'text/html' do
+    <<-HTML
+      <div><strong>Name: </strong> John Falkon</div>
+      <div><strong>Age: </strong> 39</div>
+      <div><strong>Occupation: </strong> Carpet Cleaner</div>
+    HTML
+  end
+  
+  controller pattern: '/*' do
+    get '/*' do |*captures|
+      request.breadcrumb.inspect
+    end
+  end
+  
+  get '/,', media_type: 'application/json' do
+    {name: 'John Falkon', age: 39, occupation: 'Carpet Cleaner'}.to_json
+  end
+  
+end
+
 run MediaTypesExample

data/lib/scorched/controller.rb

@@ -15,7 +15,7 @@ module Scorched
     }
     
     view_config << {
-      :dir => 'views', # The directory containing all the view templates, relative to the application root.
+      :dir => 'views', # The directory containing all the view templates, relative to the current working directory.
       :layout => false, # The default layout template to use, relative to the view directory. Set to false for no default layout.
       :engine => :erb
     }
@@ -84,17 +84,17 @@ module Scorched
       # Generates and assigns mapping hash from the given arguments.
       #
       # Accepts the following keyword arguments:
-      #   :url - The url pattern to match on. Required.
+      #   :pattern - The url pattern to match on. Required.
       #   :target - A proc to execute, or some other object that responds to #call. Required.
       #   :priority - Negative or positive integer for giving a priority to the mapped item.
       #   :conditions - A hash of condition:value pairs
       # Raises ArgumentError if required key values are not provided.
-      def map(url: nil, priority: nil, conditions: {}, target: nil)
-        raise ArgumentError, "Mapping must specify url pattern and target" unless url && target
+      def map(pattern: nil, priority: nil, conditions: {}, target: nil)
+        raise ArgumentError, "Mapping must specify url pattern and target" unless pattern && target
         priority = priority.to_i
         insert_pos = mappings.take_while { |v| priority <= v[:priority]  }.length
         mappings.insert(insert_pos, {
-          url: compile(url),
+          pattern: compile(pattern),
           priority: priority,
           conditions: conditions,
           target: target
@@ -113,17 +113,17 @@ module Scorched
       # (or inherits from) a Scorched::Controller.
       def controller(parent_class = self, **mapping, &block)
         c = Class.new(parent_class, &block)
-        self << {url: '/', target: c}.merge(mapping)
+        self << {pattern: '/', target: c}.merge(mapping)
         c
       end
       
       # Generates and returns a new route proc from the given block, and optionally maps said proc using the given args.
-      def route(url = nil, priority = nil, **conditions, &block)
+      def route(pattern = nil, priority = nil, **conditions, &block)
         target = lambda do |env|
-          env['rack.response'].body << instance_exec(*env['rack.request'].captures, &block)
-          env['rack.response']
+          env['scorched.response'].body = instance_exec(*env['scorched.request'].captures, &block)
+          env['scorched.response']
         end
-        self << {url: compile(url, true), priority: priority, conditions: conditions, target: target} if url
+        self << {pattern: compile(pattern, true), priority: priority, conditions: conditions, target: target} if pattern
         target
       end
 
@@ -151,11 +151,11 @@ module Scorched
       # Parses and compiles the given URL string pattern into a regex if not already, returning the resulting regexp
       # object. Accepts an optional _match_to_end_ argument which will ensure the generated pattern matches to the end
       # of the string.
-      def compile(url, match_to_end = false)
-        return url if Regexp === url
-        raise Error, "Can't compile URL of type #{url.class}. Must be String or Regexp." unless String === url
-        match_to_end = !!url.sub!(/\$$/, '') || match_to_end
-        pattern = url.split(%r{(\*{1,2}|(?<!\\):{1,2}[^/*$]+)}).each_slice(2).map { |unmatched, match|
+      def compile(pattern, match_to_end = false)
+        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
+        regex_pattern = pattern.split(%r{(\*{1,2}|(?<!\\):{1,2}[^/*$]+)}).each_slice(2).map { |unmatched, match|
           Regexp.escape(unmatched) << begin
             if %w{* **}.include? match
               match == '*' ? "([^/]+)" : "(.+)"
@@ -166,8 +166,8 @@ module Scorched
             end
           end
         }.join
-        pattern << '$' if match_to_end
-        Regexp.new(pattern)
+        regex_pattern << '$' if match_to_end
+        Regexp.new(regex_pattern)
       end
     end
     
@@ -179,8 +179,8 @@ module Scorched
       define_singleton_method :env do
         env
       end
-      env['rack.request'] ||= Request.new(env)
-      env['rack.response'] ||= Response.new
+      env['scorched.request'] ||= Request.new(env)
+      env['scorched.response'] ||= Response.new
     end
     
     def action
@@ -232,7 +232,7 @@ module Scorched
       to_match = to_match.chomp('/') if config[:strip_trailing_slash] == :ignore && to_match =~ %r{./$}
       matches = []
       mappings.each do |m|
-        m[:url].match(to_match) do |match_data|
+        m[:pattern].match(to_match) do |match_data|
           if match_data.pre_match == ''
             if check_conditions?(m[:conditions])
               if match_data.names.empty?
@@ -240,7 +240,7 @@ module Scorched
               else
                 captures = Hash[match_data.names.map{|v| v.to_sym}.zip match_data.captures]
               end
-              matches << {mapping: m, captures: captures, url: match_data.to_s}
+              matches << {mapping: m, captures: captures, path: match_data.to_s}
               break if short_circuit
             end
           end
@@ -274,12 +274,12 @@ module Scorched
     
     # Convenience method for accessing Rack request.
     def request
-      env['rack.request']
+      env['scorched.request']
     end
     
     # Convenience method for accessing Rack response.
     def response
-      env['rack.response']
+      env['scorched.response']
     end
     
     # Convenience method for accessing Rack session.
@@ -375,7 +375,6 @@ module Scorched
       else
         uri.to_s
       end
-      
     end
     
     # Takes an optional path, relative to the applications root URL, and returns an absolute path.

data/lib/scorched/request.rb

@@ -1,6 +1,7 @@
 module Scorched
   class Request < Rack::Request
-    # Keeps track of the matched URL portions and what object handled them.
+    # Keeps track of the matched URL portions and what object handled them. Useful for debugging and building
+    # breadcrumb navigation.
     def breadcrumb
       env['breadcrumb'] ||= []
     end
@@ -10,17 +11,20 @@ module Scorched
       breadcrumb.last ? breadcrumb.last[:captures] : []
     end
     
+    # Returns an array of capture arrays; one for each mapping that's been hit during the request processing so far.
     def all_captures
       breadcrumb.map { |v| v[:captures] }
     end
     
+    # The portion of the path that's currently been matched by one or more mappings.
     def matched_path
-      join_paths(breadcrumb.map{|v| v[:url]})
+      join_paths(breadcrumb.map{|v| v[:path]})
     end
     
+    # The remaining portion of the path that has yet to be matched by any mappings.
     def unmatched_path
       path = path_info.partition(matched_path).last
-      path[0,0] = '/' unless path[0] == '/'
+      path[0,0] = '/' if path.empty? || matched_path[-1] == '/'
       path
     end
   

data/lib/scorched/response.rb

@@ -14,5 +14,18 @@ module Scorched
         self.status, @header, self.body = response
       end
     end
+    
+    # Automatically wraps the assigned value in an array if it doesn't respond to ``each``.
+    def body=(value)
+      super(value.respond_to?(:each) ? value : [value])
+    end
+    
+    def finish(*args, &block)
+      self['Content-Type'] ||= 'text/html;charset=utf-8'
+      super
+    end
+    
+    alias :to_a :finish
+    alias :to_ary :finish
   end
 end

data/lib/scorched/version.rb

@@ -1,3 +1,3 @@
 module Scorched
-  VERSION = '0.5.1'
+  VERSION = '0.5.2'
 end

data/spec/controller_spec.rb

@@ -24,13 +24,13 @@ module Scorched
       end
     
       it "handles a root rack call correctly" do
-        app << {url: '/$', target: generic_handler}
+        app << {pattern: '/$', target: generic_handler}
         response = rt.get '/'
         response.status.should == 200
       end
     
       it "does not maintain state between requests" do
-        app << {url: '/state', target: proc { |env| [200, {}, [@state = 1 + @state.to_i]] }}
+        app << {pattern: '/state', target: proc { |env| [200, {}, [@state = 1 + @state.to_i]] }}
         response = rt.get '/state'
         response.body.should == '1'
         response = rt.get '/state'
@@ -39,7 +39,7 @@ module Scorched
       
       it "raises exception when invalid mapping hash given" do
         expect {
-          app << {url: '/'}
+          app << {pattern: '/'}
         }.to raise_error(ArgumentError)
         expect {
           app << {target: generic_handler}
@@ -49,70 +49,90 @@ module Scorched
     
     describe "URL matching" do
       it 'always matches from the beginning of the URL' do
-        app << {url: 'about', target: generic_handler}
+        app << {pattern: 'about', target: generic_handler}
         response = rt.get '/about'
         response.status.should == 404
       end
       
       it "matches eagerly by default" do
-        request = nil
-        app << {url: '/*', target: proc do |env|
-          request = env['rack.request']; [200, {}, ['ok']]
+        req = nil
+        app << {pattern: '/*', target: proc do |env|
+          req = request; [200, {}, ['ok']]
         end}
         response = rt.get '/about'
-        request.captures.should == ['about']
+        req.captures.should == ['about']
       end
       
       it "can be forced to match end of URL" do
-        app << {url: '/about$', target: generic_handler}
+        app << {pattern: '/about$', target: generic_handler}
         response = rt.get '/about/us'
         response.status.should == 404
-        app << {url: '/about', target: generic_handler}
+        app << {pattern: '/about', target: generic_handler}
         response = rt.get '/about/us'
         response.status.should == 200
       end
       
+      it "unmatched path doesn't always begin with a forward slash" do
+        gh = generic_handler
+        app << {pattern: '/ab', target: Class.new(Scorched::Controller) do
+          map(pattern: 'out', target: gh)
+        end}
+        rt.get('/about').body.should == "ok"
+      end
+      
+      it "unmatched path begins with forward slash if last match was up to or included a forward slash" do
+        gh = generic_handler
+        app << {pattern: '/about/', target: Class.new(Scorched::Controller) do
+          map(pattern: '/us', target: gh)
+        end}
+        app << {pattern: '/contact', target: Class.new(Scorched::Controller) do
+          map(pattern: '/us', target: gh)
+        end}
+        rt.get('/about/us').body.should == "ok"
+        rt.get('/contact/us').body.should == "ok"
+      end
+      
       it "can match anonymous wildcards" do
-        request = nil
-        app << {url: '/anon/*/**', target: proc do |env|
-          request = env['rack.request']; [200, {}, ['ok']]
+        req = nil
+        app << {pattern: '/anon/*/**', target: proc do |env|
+          req = request; [200, {}, ['ok']]
         end}
         response = rt.get '/anon/jeff/has/crabs'
-        request.captures.should == ['jeff', 'has/crabs']
+        req.captures.should == ['jeff', 'has/crabs']
       end
       
       it "can match named wildcards (ignoring anonymous captures)" do
-        request = nil
-        app << {url: '/anon/:name/*/::infliction', target: proc do |env|
-          request = env['rack.request']; [200, {}, ['ok']]
+        req = nil
+        app << {pattern: '/anon/:name/*/::infliction', target: proc do |env|
+          req = request; [200, {}, ['ok']]
         end}
         response = rt.get '/anon/jeff/smith/has/crabs'
-        request.captures.should == {name: 'jeff', infliction: 'has/crabs'}
+        req.captures.should == {name: 'jeff', infliction: 'has/crabs'}
       end
       
       it "can match regex and preserve anonymous captures" do
-        request = nil
-        app << {url: %r{/anon/([^/]+)/(.+)}, target: proc do |env|
-          request = env['rack.request']; [200, {}, ['ok']]
+        req = nil
+        app << {pattern: %r{/anon/([^/]+)/(.+)}, target: proc do |env|
+          req = request; [200, {}, ['ok']]
         end}
         response = rt.get '/anon/jeff/has/crabs'
-        request.captures.should == ['jeff', 'has/crabs']
+        req.captures.should == ['jeff', 'has/crabs']
       end
       
       it "can match regex and preserve named captures (ignoring anonymous captures)" do
-        request = nil
-        app << {url: %r{/anon/(?<name>[^/]+)/([^/]+)/(?<infliction>.+)}, target: proc do |env|
-          request = env['rack.request']; [200, {}, ['ok']]
+        req = nil
+        app << {pattern: %r{/anon/(?<name>[^/]+)/([^/]+)/(?<infliction>.+)}, target: proc do |env|
+          req = request; [200, {}, ['ok']]
         end}
         response = rt.get '/anon/jeff/smith/has/crabs'
-        request.captures.should == {name: 'jeff', infliction: 'has/crabs'}
+        req.captures.should == {name: 'jeff', infliction: 'has/crabs'}
       end
       
       it "matches routes based on priority, otherwise giving precedence to those defined first" do
-        app << {url: '/', priority: -1, target: proc { |env| self.class.mappings.shift; [200, {}, ['four']] }}
-        app << {url: '/', target: proc { |env| self.class.mappings.shift; [200, {}, ['two']] }}
-        app << {url: '/', target: proc { |env| self.class.mappings.shift; [200, {}, ['three']] }}
-        app << {url: '/', priority: 2, target: proc { |env| self.class.mappings.shift; [200, {}, ['one']] }}
+        app << {pattern: '/', priority: -1, target: proc { |env| self.class.mappings.shift; [200, {}, ['four']] }}
+        app << {pattern: '/', target: proc { |env| self.class.mappings.shift; [200, {}, ['two']] }}
+        app << {pattern: '/', target: proc { |env| self.class.mappings.shift; [200, {}, ['three']] }}
+        app << {pattern: '/', priority: 2, target: proc { |env| self.class.mappings.shift; [200, {}, ['one']] }}
         rt.get('/').body.should == 'one'
         rt.get('/').body.should == 'two'
         rt.get('/').body.should == 'three'
@@ -128,14 +148,14 @@ module Scorched
       end
       
       it "executes route only if all conditions return true" do
-        app << {url: '/', conditions: {methods: 'POST'}, target: generic_handler}
+        app << {pattern: '/', conditions: {methods: 'POST'}, target: generic_handler}
         response = rt.get "/"
         response.status.should == 404
         response = rt.post "/"
         response.status.should == 200
         
         app.conditions[:has_name] = proc { |name| request.GET['name'] }
-        app << {url: '/about', conditions: {methods: ['GET', 'POST'], has_name: 'Ronald'}, target: generic_handler}
+        app << {pattern: '/about', conditions: {methods: ['GET', 'POST'], has_name: 'Ronald'}, target: generic_handler}
         response = rt.get "/about"
         response.status.should == 404
         response = rt.get "/about", name: 'Ronald'
@@ -143,15 +163,15 @@ module Scorched
       end
       
       it "raises exception when condition doesn't exist or is invalid" do
-        app << {url: '/', conditions: {surprise_christmas_turkey: true}, target: generic_handler}
+        app << {pattern: '/', conditions: {surprise_christmas_turkey: true}, target: generic_handler}
         expect {
           rt.get "/"
         }.to raise_error(Scorched::Error)
       end
       
       it "falls through to next route when conditions are not met" do
-        app << {url: '/', conditions: {methods: 'POST'}, target: proc { |env| [200, {}, ['post']] }}
-        app << {url: '/', conditions: {methods: 'GET'}, target: proc { |env| [200, {}, ['get']] }}
+        app << {pattern: '/', conditions: {methods: 'POST'}, target: proc { |env| [200, {}, ['post']] }}
+        app << {pattern: '/', conditions: {methods: 'GET'}, target: proc { |env| [200, {}, ['get']] }}
         rt.get("/").body.should == 'get'
         rt.post("/").body.should == 'post'
       end
@@ -161,7 +181,7 @@ module Scorched
       it "allows end points to be defined more succinctly" do
         route_proc = app.route('/*', 2, methods: 'GET') { |capture| capture }
         mapping = app.mappings.first
-        mapping.should == {url: mapping[:url], priority: 2, conditions: {methods: 'GET'}, target: route_proc}
+        mapping.should == {pattern: mapping[:pattern], priority: 2, conditions: {methods: 'GET'}, target: route_proc}
         rt.get('/about').body.should == 'about'
       end
       
@@ -170,7 +190,7 @@ module Scorched
         wrapped_block = app.route(&block)
         app.mappings.length.should == 0
         block.should_not == wrapped_block
-        app << {url: '/*', target: wrapped_block}
+        app << {pattern: '/*', target: wrapped_block}
         rt.get('/turkey').body.should == 'turkey'
       end
       
@@ -208,7 +228,7 @@ module Scorched
       end
       
       it "should ignore the already matched portions of the path" do
-        app.controller url: '/article' do
+        app.controller pattern: '/article' do
           get('/*') { |title| title }
         end
         rt.get('/article/hello-world').body.should == 'hello-world'
@@ -391,7 +411,7 @@ module Scorched
           get '/'do
             request.env['scorched.simple_counter']
           end
-          controller url: '/sub_controller' do
+          controller pattern: '/sub_controller' do
             get '/' do
               request.env['scorched.simple_counter']
             end
@@ -549,6 +569,7 @@ module Scorched
           app.post('/') { cookie :test, 'hello' }
           app.post('/goodbye') { cookie :test, {value: 'goodbye', expires: Time.now() + 999999 } }
           app.delete('/') { cookie :test, nil }
+          app.delete('/alt') { cookie :test, {value: nil} }
           
           rt.get('/').body.should == ''
           rt.post('/')
@@ -557,6 +578,8 @@ module Scorched
           rt.get('/').body.should == 'goodbye'
           rt.delete('/')
           rt.get('/').body.should == ''
+          rt.delete('/alt')
+          rt.get('/').body.should == ''
         end
       end
       

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scorched
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.2
 platform: ruby
 authors:
 - Tom Wardrop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-06 00:00:00.000000000 Z
+date: 2013-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -91,11 +91,18 @@ files:
 - LICENSE
 - Milestones.md
 - README.md
-- docs/be_creative.md
-- docs/filters.md
-- docs/routing.md
-- docs/sharing_request_state.md
-- examples/media_types.rb
+- docs/01_preface.md
+- docs/02_fundamentals/01_the_controller.md
+- docs/02_fundamentals/02_configuration.md
+- docs/02_fundamentals/03_routing.md
+- docs/02_fundamentals/04_requests_and_responses.md
+- docs/02_fundamentals/05_filters.md
+- docs/02_fundamentals/06_middleware.md
+- docs/02_fundamentals/07_request_and_session_data.md
+- docs/02_fundamentals/08_views.md
+- docs/02_fundamentals/09_sharing_request_state.md
+- docs/03_further_reading/be_creative.md
+- examples/file_upload.ru
 - examples/media_types.ru
 - lib/scorched.rb
 - lib/scorched/collection.rb

data/docs/be_creative.md

@@ -1,32 +0,0 @@
-Effortless REST
----------------
-An easy way to serve multiple content-types:
-
-  class App < Scorched::Controller
-    def view(view = nil)
-      view ? env['app.view'] = view : env['app.view']
-    end
-  
-    after do
-      if check_condition?(:media_type, 'text/html')
-        response.body = [render(view)]
-      if check_condition?(:media_type, 'application/json')
-        response['Content-type'] = 'application/json'
-        response.body = [response.body.to_json]
-      elsif check_condition?(:media_type, 'application/pdf')
-        response['Content-type'] = 'application/pdf'
-        # response.body = [render_pdf(view)]
-      else
-        response.body = [render(view)]
-      end
-    end
-  
-    get '/' do
-      view :index
-      [
-        {title: 'Sweet Purple Unicorns', date: '08/03/2013'},
-        {title: 'Mellow Grass Men', date: '21/03/2013'}
-      ]
-    end
-  end
-  

data/docs/filters.md

@@ -1,8 +0,0 @@
-
-After Filters
--------------
-
-
-Error Filters
--------------
-Error filters are processed like regular filters, except they're called whenever an exception occurs. If an error filter returns false, it's assumed to be unhandled, and the next error filter is called. This continues until one of the following is true, 1) an error filter returns true, in which case the exception is assumed to be handled, 2) an error filter raises an exception itself, or 3) there are no more error handlers defined on the current controller, in which case the exception is re-raised.

data/docs/routing.md

@@ -1,29 +0,0 @@
-Patterns
-========
-All patterns attempt to match the remaining unmatched portion of the request path (the request path being rack's
-`path_info` variable). The unmatched path will always begin with a forward slash if the previously matched portion of the
-path ended at a forward slash, regardless of whether it actually included the forward slash in the match, or if the
-forward slash was the next character. As an example, if the request was to "/article/21", then both "/article/" => "/21"
-and "/article" => "/21" would match.
-    
-All patterns match from the beginning of the path. Matches that occur beyond the beginning of the path won't count as a
-match. So even though the pattern "article" would match "/article/21", it wouldn't count as a match because the match
-didn't start at a non-zero offset.
-
-If a pattern contains named captures, unnamed captures will be lost (this is how named regex captures work in Ruby). So
-if you name one capture, make sure you name any other captures you may want to access.
-
-String Patterns
----------------
-* `*` - Matches all characters excluding the forward slash.
-* `**` - Matches all characters including the forward slash.
-* `:param` - Same as `*` except the capture is named to whatever the string following the single-colon is.
-* `::param` - Same as `**` except the capture is named to whatever the string following the double-colon is.
-* `$` - If placed at the end of a pattern, the pattern only matches if it matches the entire path. For routes, this is
-  implied, so it should only be explicitly added if trying to match a dollar sign character. If added anywhere other
-  than the end of the pattern, it will match the dollar sign character.
-
-
-Regex Patterns
---------------
-Regex patterns offer more power and flexibility than string patterns (naturally). To be continued... (captures, named captures, etc).

data/docs/sharing_request_state.md

@@ -1,5 +0,0 @@
-Managing Request State
-----------------------
-Because Scorched allows sub-controllers to an arbitrary depth and treats all controllers equal (i.e has no concept of a _root_ controller), it means instance variables cannot be used to track, maintain or share request state between controllers. I mention this because instance variables are the most common way to manage the request state in the likes of Sinatra.
-
-As an example, consider the Scorched implementation of flash session data. This data must be shared between controllers throughout the life of the request. The solution here, which you can find by looking at the Scorched source code, is to use the Rack environment hash. It's the one object that's accessible throughout the entire life-cycle of a request, and it's what you should use to maintain request state between controllers and even other embedded Rack applications.

data/examples/media_types.rb

@@ -1,18 +0,0 @@
-require 'json'
-require_relative '../lib/scorched.rb'
-
-class MediaTypesExample < Scorched::Controller
-  
-  get '/', media_type: 'text/html' do
-    <<-HTML
-      <div><strong>Name: </strong> John Falkon</div>
-      <div><strong>Age: </strong> 39</div>
-      <div><strong>Occupation: </strong> Carpet Cleaner</div>
-    HTML
-  end
-  
-  get '/,', media_type: 'application/json' do
-    {name: 'John Falkon', age: 39, occupation: 'Carpet Cleaner'}.to_json
-  end
-  
-end