darkhelmet-sinatra 0.9.1.1 → 0.10.1

data/README.rdoc

@@ -1,6 +1,6 @@
 = Sinatra
 
-Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
+Sinatra is a DSL for quickly creating web applications in Ruby with minimal
 effort:
 
   # myapp.rb
@@ -45,7 +45,7 @@ Route patterns may include named parameters, accessible via the
 <tt>params</tt> hash:
 
   get '/hello/:name' do
-    # matches "GET /foo" and "GET /bar"
+    # matches "GET /hello/foo" and "GET /hello/bar"
     # params[:name] is 'foo' or 'bar'
     "Hello #{params[:name]}!"
   end
@@ -109,28 +109,67 @@ directory. To use a different views directory:
 
   set :views, File.dirname(__FILE__) + '/templates'
 
+One important thing to remember is that you always have to reference
+templates with symbols, even if they're in a subdirectory (in this
+case use <tt>:'subdir/template'</tt>). Rendering methods will render
+any strings passed to them directly.
+
 === Haml Templates
 
 The haml gem/library is required to render HAML templates:
 
+  ## You'll need to require haml in your app
+  require 'haml'
+
   get '/' do
     haml :index
   end
 
 Renders <tt>./views/index.haml</tt>.
 
+{Haml's options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Haml.html]
+can be set globally through Sinatra's configurations,
+see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
+and overridden on an individual basis.
+
+  set :haml, {:format => :html5 } # default Haml format is :xhtml
+
+  get '/' do
+    haml :index, :haml_options => {:format => :html4 } # overridden
+  end
+
+
 === Erb Templates
 
+  ## You'll need to require erb in your app
+  require 'erb'
+
   get '/' do
     erb :index
   end
 
 Renders <tt>./views/index.erb</tt>
 
+=== Erubis
+
+The erubis gem/library is required to render builder templates:
+
+  ## You'll need to require erubis in your app
+  require 'erubis'
+
+  get '/' do
+    erubis :index
+  end
+
+Renders <tt>./views/index.erubis</tt>
+
 === Builder Templates
 
 The builder gem/library is required to render builder templates:
 
+  ## You'll need to require builder in your app
+  require 'builder'
+
   get '/' do
     content_type 'application/xml', :charset => 'utf-8'
     builder :index
@@ -142,6 +181,9 @@ Renders <tt>./views/index.builder</tt>.
 
 The sass gem/library is required to render Sass templates:
 
+  ## You'll need to require haml or sass in your app
+  require 'sass'
+
   get '/stylesheet.css' do
     content_type 'text/css', :charset => 'utf-8'
     sass :stylesheet
@@ -149,6 +191,18 @@ The sass gem/library is required to render Sass templates:
 
 Renders <tt>./views/stylesheet.sass</tt>.
 
+{Sass' options}[http://haml.hamptoncatlin.com/docs/rdoc/classes/Sass.html]
+can be set globally through Sinatra's configurations,
+see {Options and Configurations}[http://www.sinatrarb.com/configuration.html],
+and overridden on an individual basis.
+
+  set :sass, {:style => :compact } # default Sass style is :nested
+
+  get '/stylesheet.css' do
+    content_type 'text/css', :charset => 'utf-8'
+    sass :stylesheet, :style => :expanded # overridden
+  end
+
 === Inline Templates
 
   get '/' do
@@ -177,7 +231,7 @@ Or, specify an explicit Hash of local variables:
 This is typically used when rendering templates as partials from within
 other templates.
 
-=== In-file Templates
+=== Inline Templates
 
 Templates may be defined at the end of the source file:
 
@@ -197,9 +251,9 @@ Templates may be defined at the end of the source file:
   @@ index
   %div.title Hello world!!!!!
 
-NOTE: In-file templates defined in the source file that requires sinatra
-are automatically loaded. Call the <tt>use_in_file_templates!</tt>
-method explicitly if you have in-file templates in other source files.
+NOTE: Inline templates defined in the source file that requires sinatra
+are automatically loaded. Call `enable :inline_templates` explicitly if you
+have inline templates in other source files.
 
 === Named Templates
 
@@ -255,43 +309,53 @@ filters are accessible by routes and templates:
     params[:splat] #=> 'bar/baz'
   end
 
+After filter are evaluated after each request within the context of the
+request and can also modify the request and response. Instance variables
+set in before filters and routes are accessible by after filters:
+
+  after do
+    puts response.status
+  end
+
 == Halting
 
-To immediately stop a request during a before filter or route use:
+To immediately stop a request within a filter or route use:
 
   halt
 
-You can also specify a body when halting ...
+You can also specify the status when halting ...
+
+  halt 410
+
+Or the body ...
 
   halt 'this will be the body'
 
-Or set the status and body ...
+Or both ...
 
   halt 401, 'go away!'
 
+With headers ...
+
+  halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
+
 == Passing
 
 A route can punt processing to the next matching route using <tt>pass</tt>:
 
   get '/guess/:who' do
     pass unless params[:who] == 'Frank'
-    "You got me!"
+    'You got me!'
   end
 
   get '/guess/*' do
-    "You missed!"
+    'You missed!'
   end
 
 The route block is immediately exited and control continues with the next
 matching route. If no matching route is found, a 404 is returned.
 
-== Configuration and Reloading
-
-Sinatra supports multiple environments and reloading. Reloading happens
-before each request when running under the <tt>:development</tt>
-environment. Wrap your configurations (e.g., database connections, constants,
-etc.) in <tt>configure</tt> blocks to protect them from reloading or to
-target specific environments.
+== Configuration
 
 Run once, at startup, in any environment:
 
@@ -300,14 +364,14 @@ Run once, at startup, in any environment:
   end
 
 Run only when the environment (RACK_ENV environment variable) is set to
-<tt>:production</tt>.
+<tt>:production</tt>:
 
   configure :production do
     ...
   end
 
-Run when the environment (RACK_ENV environment variable) is set to
-either <tt>:production</tt> or <tt>:test</tt>.
+Run when the environment is set to either <tt>:production</tt> or
+<tt>:test</tt>:
 
   configure :production, :test do
     ...
@@ -331,7 +395,7 @@ code is 404, the <tt>not_found</tt> handler is invoked:
 === Error
 
 The +error+ handler is invoked any time an exception is raised from a route
-block or before filter. The exception object can be obtained from the
+block or a filter. The exception object can be obtained from the
 <tt>sinatra.error</tt> Rack variable:
 
   error do
@@ -354,15 +418,35 @@ You get this:
 
   So what happened was... something bad
 
+Alternatively, you can install error handler for a status code:
+
+  error 403 do
+    'Access forbidden'
+  end
+
+  get '/secret' do
+    403
+  end
+
+Or a range:
+
+  error 400..510 do
+    'Boom'
+  end
+
 Sinatra installs special <tt>not_found</tt> and <tt>error</tt> handlers when
 running under the development environment.
 
 == Mime types
 
 When using <tt>send_file</tt> or static files you may have mime types Sinatra
-doesn't understand. Use +mime+ to register them by file extension:
+doesn't understand. Use +mime_type+ to register them by file extension:
 
-  mime :foo, 'text/foo'
+  mime_type :foo, 'text/foo'
+
+You can also use it with the +content_type+ helper:
+
+  content_type :foo
 
 == Rack Middleware
 
@@ -401,45 +485,100 @@ typically don't have to +use+ them explicitly.
 
 == Testing
 
-The Sinatra::Test mixin and Sinatra::TestHarness class include a variety of
-helper methods for testing your Sinatra app:
+Sinatra tests can be written using any Rack-based testing library
+or framework. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] is
+recommended:
 
   require 'my_sinatra_app'
-  require 'test/unit'
-  require 'sinatra/test'
+  require 'rack/test'
 
   class MyAppTest < Test::Unit::TestCase
-    include Sinatra::Test
+    include Rack::Test::Methods
+
+    def app
+      Sinatra::Application
+    end
 
     def test_my_default
       get '/'
-      assert_equal 'Hello World!', @response.body
+      assert_equal 'Hello World!', last_response.body
     end
 
     def test_with_params
-      get '/meet', {:name => 'Frank'}
-      assert_equal 'Hello Frank!', @response.body
+      get '/meet', :name => 'Frank'
+      assert_equal 'Hello Frank!', last_response.body
     end
 
     def test_with_rack_env
-      get '/', {}, :agent => 'Songbird'
-      assert_equal "You're using Songbird!", @response.body
+      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
+      assert_equal "You're using Songbird!", last_response.body
+    end
+  end
+
+NOTE: The built-in Sinatra::Test module and Sinatra::TestHarness class
+are deprecated as of the 0.9.2 release.
+
+== Sinatra::Base - Middleware, Libraries, and Modular Apps
+
+Defining your app at the top-level works well for micro-apps but has
+considerable drawbacks when building reuseable components such as Rack
+middleware, Rails metal, simple libraries with a server component, or
+even Sinatra extensions. The top-level DSL pollutes the Object namespace
+and assumes a micro-app style configuration (e.g., a single application
+file, ./public and ./views directories, logging, exception detail page,
+etc.). That's where Sinatra::Base comes into play:
+
+  require 'sinatra/base'
+
+  class MyApp < Sinatra::Base
+    set :sessions, true
+    set :foo, 'bar'
+
+    get '/' do
+      'Hello world!'
     end
   end
 
-See http://www.sinatrarb.com/testing.html for more on Sinatra::Test and using it
-with other test frameworks such as RSpec, Bacon, and test/spec.
+The MyApp class is an independent Rack component that can act as
+Rack middleware, a Rack application, or Rails metal. You can +use+ or
++run+ this class from a rackup +config.ru+ file; or, control a server
+component shipped as a library:
+
+   MyApp.run! :host => 'localhost', :port => 9090
+
+The methods available to Sinatra::Base subclasses are exactly as those
+available via the top-level DSL. Most top-level apps can be converted to
+Sinatra::Base components with two modifications:
+
+* Your file should require +sinatra/base+  instead of +sinatra+;
+  otherwise, all of Sinatra's DSL methods are imported into the main
+  namespace.
+* Put your app's routes, error handlers, filters, and options in a subclass
+  of Sinatra::Base.
+
++Sinatra::Base+ is a blank slate. Most options are disabled by default,
+including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html]
+for details on available options and their behavior.
+
+SIDEBAR: Sinatra's top-level DSL is implemented using a simple delegation
+system. The +Sinatra::Application+ class -- a special subclass of
+Sinatra::Base -- receives all :get, :put, :post, :delete, :before,
+:error, :not_found, :configure, and :set messages sent to the
+top-level. Have a look at the code for yourself: here's the
+{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064]
+being {included into the main namespace}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].
 
 == Command line
 
 Sinatra applications can be run directly:
 
-  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-s HANDLER]
+  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-h HOST] [-s HANDLER]
 
 Options are:
 
   -h # help
   -p # set the port (default is 4567)
+  -h # set the host (default is 0.0.0.0)
   -e # set the environment (default is development)
   -s # specify rack server/handler (default is thin)
   -x # turn on the mutex lock (default is off)
@@ -454,7 +593,7 @@ clone and run your app with the <tt>sinatra/lib</tt> directory on the
   git clone git://github.com/sinatra/sinatra.git
   ruby -Isinatra/lib myapp.rb
 
-Alternatively, you can add the <tt>sinatra/lib<tt> directory to the
+Alternatively, you can add the <tt>sinatra/lib</tt> directory to the
 <tt>LOAD_PATH</tt> in your application:
 
   $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'

data/Rakefile

@@ -2,7 +2,7 @@ require 'rake/clean'
 require 'rake/testtask'
 require 'fileutils'
 
-task :default => [:test]
+task :default => :test
 task :spec => :test
 
 # SPECS ===============================================================
@@ -12,12 +12,6 @@ Rake::TestTask.new(:test) do |t|
   t.ruby_opts = ['-rubygems'] if defined? Gem
 end
 
-desc 'Run compatibility specs (requires test/spec)'
-task :compat do |t|
-  pattern = ENV['TEST'] || '.*'
-  sh "specrb --testcase '#{pattern}' -Ilib:test compat/*_test.rb"
-end
-
 # PACKAGING ============================================================
 
 # Load the gemspec using the same limitations as github
@@ -33,7 +27,7 @@ def spec
 end
 
 def package(ext='')
-  "dist/sinatra-#{spec.version}" + ext
+  "pkg/sinatra-#{spec.version}" + ext
 end
 
 desc 'Build packages'
@@ -44,15 +38,15 @@ task :install => package('.gem') do
   sh "gem install #{package('.gem')}"
 end
 
-directory 'dist/'
-CLOBBER.include('dist')
+directory 'pkg/'
+CLOBBER.include('pkg')
 
-file package('.gem') => %w[dist/ sinatra.gemspec] + spec.files do |f|
+file package('.gem') => %w[pkg/ sinatra.gemspec] + spec.files do |f|
   sh "gem build sinatra.gemspec"
   mv File.basename(f.name), f.name
 end
 
-file package('.tar.gz') => %w[dist/] + spec.files do |f|
+file package('.tar.gz') => %w[pkg/] + spec.files do |f|
   sh <<-SH
     git archive \
       --prefix=sinatra-#{source_version}/ \
@@ -64,7 +58,7 @@ end
 # Rubyforge Release / Publish Tasks ==================================
 
 desc 'Publish gem and tarball to rubyforge'
-task 'publish:gem' => [package('.gem'), package('.tar.gz')] do |t|
+task 'release' => [package('.gem'), package('.tar.gz')] do |t|
   sh <<-end
     rubyforge add_release sinatra sinatra #{spec.version} #{package('.gem')} &&
     rubyforge add_file    sinatra sinatra #{spec.version} #{package('.tar.gz')}
@@ -95,12 +89,6 @@ file 'doc/api/index.html' => FileList['lib/**/*.rb','README.rdoc'] do |f|
 end
 CLEAN.include 'doc/api'
 
-def rdoc_to_html(file_name)
-  require 'rdoc/markup/to_html'
-  rdoc = RDoc::Markup::ToHtml.new
-  rdoc.convert(File.read(file_name))
-end
-
 # Gemspec Helpers ====================================================
 
 def source_version
@@ -108,12 +96,7 @@ def source_version
   line.match(/.*VERSION = '(.*)'/)[1]
 end
 
-project_files =
-  FileList[
-    '{lib,test,compat,images}/**',
-    'Rakefile', 'CHANGES', 'README.rdoc'
-  ]
-file 'sinatra.gemspec' => project_files do |f|
+task 'sinatra.gemspec' => FileList['{lib,test,compat}/**','Rakefile','CHANGES','*.rdoc'] do |f|
   # read spec file and split out manifest section
   spec = File.read(f.name)
   head, manifest, tail = spec.split("  # = MANIFEST =\n")
@@ -134,3 +117,13 @@ file 'sinatra.gemspec' => project_files do |f|
   File.open(f.name, 'w') { |io| io.write(spec) }
   puts "updated #{f.name}"
 end
+
+# Rcov ==============================================================
+namespace :test do
+  desc 'Mesures test coverage'
+  task :coverage do
+    rm_f "coverage"
+    rcov = "rcov --text-summary --test-unit-only -Ilib"
+    system("#{rcov} --no-html --no-color test/*_test.rb")
+  end
+end