scorched 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e853e2cdf6c23a10cebb3ada3d26cc90a0535b7
-  data.tar.gz: 2cfe230e619c9ad1f0304c35699ed55cdcc9e94b
+  metadata.gz: 295ef9e64b632d7c0d594d7faa770abe1a276306
+  data.tar.gz: 77d884750ab7dd5946e124963a0f818141074a6c
 SHA512:
-  metadata.gz: 236012f2a5d523733f2fe8d81389d545d9bbb01a421f2840371e31f7f4b81ccf608cd7ba06838f0291a5bb0796271bd6e1e10de6b0a61301168b4c2865c52dbf
-  data.tar.gz: 2e531bf2da9a00ea4efedf2eaa18d2718d6c7bebc72cf47176f48ac6f4b35c2722f5974b4d72346e5d4d8375cfc4f091fc34af46d2d1165b9c762318ce941f0c
+  metadata.gz: a22df1cc5accdf2ef58b0a9135726d5379b74b55ecd5ed6d301c5e7adf55e14f5905c400411d12263f65552cbf32792d0f1400397fc6be260831536033f52f09
+  data.tar.gz: 426055e514e3ec9a4a7a13c2dccb692a914a38d054630a4f39b9df0a1d973520850571491741d3dc3f2a8aab363d62c283b4fac0a76140e1b9433bd825564eff

data/Milestones.md

@@ -3,6 +3,15 @@ Milestones
 
 Changelog
 ---------
+### v0.9
+* Refactored `render` method:
+    * All Scorched options are now keyword arguments, including `:locals` which was added as a proper render option.
+    * Scorched options are no longer passed through to Tilt.
+    * `:tilt` option added to allow options to be passed directly to Tilt, such as `:engine`
+    * Unrecognised options are still passed through to Tilt for convenience.
+* Added template caching using Tilt::Cache.
+    * Added `:cache_templates` config option. Defaults to true except for development.
+
 ### 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.
@@ -18,7 +27,7 @@ Changelog
 * `absolute`ethod now returns forward slash if script name is empty.
 
 ### v0.6
-* `view_config`ptions hash renamed to ` `render_defaults`ch better reflects its function.
+* `view_config` options 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.
@@ -64,8 +73,8 @@ To Do
 -----
 Some of these remaining features may be reconsidered and either left out, or put into some kind of contrib library.
 
+* If one or more matches are found, but their conditions don't pass, a 403 should be returned instead of a 404.
 * Make specs for Collection and Options classes more thorough, e.g. test all non-reading modifiers such as clear, delete, etc.
-* 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.

data/README.md

@@ -110,3 +110,12 @@ This API shouldn't look too foreign to anyone familiar with frameworks like Sina
 Development Progress
 --------------------
 Please refer to [Milestones.md](Milestones.md) for a breakdown of development progress.
+
+
+Links
+-----
+* [Website](http://scorchedrb.com)
+* [Online API Reference](http://rubydoc.info/gems/scorched)
+* [GitHub Project](http://github.com/wardrop/Scorched)
+* [Issue Tracker](http://github.com/wardrop/Scorched/issues)
+* [Discussion/Mailing List](https://groups.google.com/d/forum/scorched)

data/docs/02_fundamentals/01_the_controller.md

@@ -119,22 +119,43 @@ 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. 
+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. 
 
 ``` ruby
 class MyApp < Scorched::Controller
   get '/' do
-    bold "Hello there"
+    format "Hello there"
+  end
+  
+  controller do 
+    before { response['Content-Type'] = 'text/plain' }
+  
+    get '/hello' do
+      'Hello'
+    end
+    
+    def emphasise(str)
+      "**#{str}**"
+    end
   end
   
-  controller conditions: {media_type: 'application/json'} do
-   
+  get '/goodbye' do
+   'Goodbye'
+  end
+  
+  after { response.body = emphasise(response.body.join) }
+  
+  def emphasise(str)
+    "<strong>#{str}</strong>"
   end
 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.
+
+
 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.
+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 makes no differentiation between a sub-controller and any other controller. All Controllers are made equal.
 
-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.
+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 again, can accommodate creative solutions.

data/docs/02_fundamentals/02_configuration.md

@@ -8,7 +8,7 @@ There are two sets of configurables. Those which apply to views, and everything
 Options
 -------
 
-Each configuration is listed below, with the default value of each included. Note, environment specific defaults may override the default values below.
+Each configuration is listed below, with the default value of each included. Note, development environment may override the default values below.
 
 * `config[:strip_trailing_slash] = :redirect`  
     Controls how trailing forward slashes in requests are handled.
@@ -17,8 +17,9 @@ Each configuration is listed below, with the default value of each included. Not
     * `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] = false` - Is currently only used for Rack::Logger.
 * `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.
+* `config[:cache_templates] = true` - If true, caches compiled templates using Tilt::Cache.
 
 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.
 

data/docs/03_further_reading/live_console.md

@@ -0,0 +1,8 @@
+Running a Live Console
+======================
+
+Scorched does not include a console like Rails or Merb does, but only because it doesn't need to. Multiple solutions already exist, including simply loading your application within IRB or Pry.
+
+First, I suggest you try [Racksh](https://github.com/sickill/racksh). It's a very handy yet simple Rack shell implementation that should meet most of your expectations. You can install _racksh_ as a gem with `gem install racksh`. I suggest you read the README in the projects Github repository to get started.
+
+Another option for those running Phusion Passenger Enterprise, is the live IRB and debugging console. An introductory video can be found here: http://vimeo.com/45923773

data/lib/scorched/controller.rb

@@ -1,4 +1,6 @@
 module Scorched
+  TemplateCache = Tilt::Cache.new
+  
   class Controller
     include Scorched::Options('config')
     include Scorched::Options('render_defaults')
@@ -10,23 +12,26 @@ module Scorched
     
     config << {
       :strip_trailing_slash => :redirect, # :redirect => Strips and redirects URL ending in forward slash, :ignore => internally ignores trailing slash, false => does nothing.
-      :static_dir => 'public', # The directory Scorched should serve static files from. Set to false if web server or anything else is serving static files.
+      :static_dir => false, # The directory Scorched should serve static files from. Set to false if web server or anything else is serving static files.
       :logger => nil,
       :show_exceptions => false,
       :auto_pass => false, # Automatically _pass_ request back to outer controller if no route matches.
+      :cache_templates => true
     }
     
     render_defaults << {
       :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
+      :engine => :erb,
+      :locals => {},
+      :tilt => {}, # Options intended for Tilt. This gets around potentialkey name conflicts between Scorched and the renderer invoked by Tilt. For example, if you had to specify an `:engine` for the renderer, this allows you to do that without.
     }
     
     if ENV['RACK_ENV'] == 'development'
       config[:logger] = Logger.new(STDOUT)
       config[:show_exceptions] = true
-    else
-      config[:static_dir] = false
+      config[:static_dir] = 'public'
+      config[:cache_templates] = false
     end
     
     conditions << {
@@ -325,8 +330,9 @@ module Scorched
       env['scorched.flash'].each { |k,v| session[k] = v } if session && env['scorched.flash']
     end
     
-    # Serves a thin layer of convenience to Rack's built-in methods: Request#cookies, Response#set_cookie, and
+    # Serves as a thin layer of convenience to Rack's built-in methods: Request#cookies, Response#set_cookie, and
     # Response#delete_cookie.
+    #
     # If only one argument is given, the specified cookie is retreived and returned.
     # If both arguments are supplied, the cookie is either set or deleted, depending on whether the second argument is
     # nil, or otherwise is a hash containing the key/value pair ``:value => nil``.
@@ -346,35 +352,53 @@ module Scorched
     end
     
     # Renders the given string or file path using the Tilt templating library.
-    # The options hash is merged with the controllers _render_defaults_. Unrecognised options are passed through to Tilt. 
-    # The template engine is derived from file name, or otherwise as specified by the _:engine_ option. If a string is
-    # given, the _:engine_ option must be set.
+    # Each option defaults to the corresponding value defined in _render_defaults_ attribute. Unrecognised options are
+    # passed through to Tilt, but a `:tilt` option is also provided for passing options directly to Tilt.
+    # The template engine is derived from the file name, or otherwise as specified by the _:engine_ option. If a string
+    # is given, the _:engine_ option must be set.
     #
-    # Refer to Tilt documentation for a list of valid template engines.
-    def render(string_or_file, options = {}, &block)
-      options = render_defaults.merge(explicit_options = options)
-      engine = (derived_engine = Tilt[string_or_file.to_s]) || Tilt[options[:engine]]
-      raise Error, "Invalid or undefined template engine: #{options[:engine].inspect}" unless engine
-      if Symbol === string_or_file
+    # Refer to Tilt documentation for a list of valid template engines and Tilt options.
+    def render(
+      string_or_file,
+      dir: render_defaults[:dir],
+      layout: @_no_default_layout ? nil : render_defaults[:layout],
+      engine: render_defaults[:engine],
+      locals: render_defaults[:locals],
+      tilt: render_defaults[:tilt],
+      **options,
+      &block
+    )
+      template_cache = config[:cache_templates] ? TemplateCache : Tilt::Cache.new
+      tilt_options = options.merge(tilt || {})
+      tilt_engine = (derived_engine = Tilt[string_or_file.to_s]) || Tilt[engine]
+      raise Error, "Invalid or undefined template engine: #{engine.inspect}" unless tilt_engine
+      template = if Symbol === string_or_file
         file = string_or_file.to_s
-        file = file << ".#{options[:engine]}" unless derived_engine
-        file = File.join(options[:dir], file) if options[:dir]
+        file = file << ".#{engine}" unless derived_engine
+        file = File.join(dir, file) if dir
         # Tilt still has unresolved file encoding issues. Until that's fixed, we read the file manually.
-        template = engine.new(nil, nil, options) { File.read(file) }
+        template_cache.fetch(:file, tilt_engine, file, tilt_options) do
+          tilt_engine.new(nil, nil, tilt_options) { File.read(file) }
+        end
       else
-        template = engine.new(nil, nil, options) { string_or_file }
+        template_cache.fetch(:string, tilt_engine, string_or_file, tilt_options) do
+          tilt_engine.new(nil, nil, tilt_options) { string_or_file }
+        end
       end
-      
+    
       # The following chunk of code is responsible for preventing the rendering of layouts within views.
-      options[:layout] = false if @_no_default_layout && !explicit_options[:layout]
       begin
         @_no_default_layout = true
-        output = template.render(self, options[:locals], &block)
+        output = template.render(self, locals, &block)
       ensure
         @_no_default_layout = false
       end
-      output = render(options[:layout], options.merge(layout: false)) { output } if options[:layout]
-      output
+      
+      if layout
+        render(layout, dir: dir, layout: false, engine: engine, locals: locals, tilt: tilt, **options) { output }
+      else
+        output
+      end
     end
     
     # Takes an optional URL, relative to the applications root, and returns a fully qualified URL.

data/lib/scorched/version.rb

@@ -1,3 +1,3 @@
 module Scorched
-  VERSION = '0.8'
+  VERSION = '0.9'
 end

data/spec/controller_spec.rb

@@ -525,7 +525,7 @@ module Scorched
     end
     
     describe "configuration" do
-      describe "strip_trailing_slash" do
+      describe :strip_trailing_slash do
         it "can be set to strip trailing slash and redirect" do
           app.config[:strip_trailing_slash] = :redirect
           app.get('/test') { }
@@ -552,7 +552,7 @@ module Scorched
         end
       end
       
-      describe "static_dir" do
+      describe :static_dir do
         it "can serve static file from the specific directory" do
           app.config[:static_dir] = 'public'
           response = rt.get('/static.txt')
@@ -567,7 +567,7 @@ module Scorched
         end
       end
       
-      describe "show_exceptions" do
+      describe :show_exceptions do
         it "shows debug-friendly error page for unhandled exceptions" do
           app.config[:show_exceptions] = true
           app.get('/') { raise RuntimeError, "Kablamo!" }
@@ -585,8 +585,8 @@ module Scorched
         end
       end
       
-      describe "auto_pass" do
-        it "if no match, passes to the outer controller without running any filters" do
+      describe :auto_pass do
+        it "passes to the outer controller without running any filters, if no match" do
           sub = Class.new(Scorched::Controller) do
             config[:auto_pass] = true
             before { response.status = 600 }
@@ -605,6 +605,28 @@ module Scorched
           rt.get('/').status.should == 600
         end
       end
+      
+      describe :cache_templates do
+        before(:each) do
+          File.open('views/temp.str', 'w') { |f| f.write 'hello world' }
+        end
+        
+        it "can cache templates" do
+          app.config[:cache_templates] = true
+          app.get('/') { render :'temp.str' }
+          rt.get('/').body.should == 'hello world'
+          File.open('views/temp.str', 'a') { |f| f.write '!!!' }
+          rt.get('/').body.should == 'hello world'
+        end
+        
+        it "can be set not to cache templates" do
+          app.config[:cache_templates] = false
+          app.get('/') { render :'temp.str' }
+          rt.get('/').body.should == 'hello world'
+          File.open('views/temp.str', 'a') { |f| f.write '!!!' }
+          rt.get('/').body.should == 'hello world!!!'
+        end
+      end
     end
     
     describe "sessions" do
@@ -766,6 +788,35 @@ module Scorched
         end
         rt.get('/').body.should == '({1 for none})'
       end
+      
+      it "can pass local variables through to view" do
+        app.get '/' do
+          render '<%= var %>', engine: 'erb', dir: 'views', locals: {var: 'hello sailor'}
+        end
+        rt.get('/').body.should == 'hello sailor'
+      end
+      
+      it "provides a means for passing options directly to tilt" do
+        Tilt.register(Class.new(Tilt::ERBTemplate) do
+          def prepare
+            options[:engine].new if options[:engine]
+            super
+          end
+        end, 'test')
+        
+        app.get '/safe' do
+          render '<%= var %>', engine: 'test', dir: 'views', locals: {var: 'hello sailor'}
+          render '<%= var %>', engine: 'test', dir: 'views', locals: {var: 'hello sailor'}, tilt: {engine: Class.new}
+        end
+        rt.get('/safe').body.should == 'hello sailor'
+        
+        app.get '/boomer' do
+          render '<%= var %>', engine: 'test', dir: 'views', locals: {var: 'hello sailor'}, tilt: {engine: 'invalid'}
+        end
+        expect {
+          rt.get('/boomer')
+        }.to raise_error(NoMethodError)
+      end
     end
     
     describe "url helpers" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scorched
 version: !ruby/object:Gem::Version
-  version: '0.8'
+  version: '0.9'
 platform: ruby
 authors:
 - Tom Wardrop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-27 00:00:00.000000000 Z
+date: 2013-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -103,6 +103,7 @@ files:
 - docs/02_fundamentals/09_sharing_request_state.md
 - docs/03_further_reading/be_creative.md
 - docs/03_further_reading/code_reloading.md
+- docs/03_further_reading/live_console.md
 - docs/03_further_reading/running_unit_tests.md
 - examples/file_upload.ru
 - examples/media_types.ru