rtomayko-sinatra 0.8.10 → 0.9.0

data/ChangeLog

@@ -0,0 +1,96 @@
+= 0.3.3 / 2009-01-06
+
+  * Pin to Rack 0.4.0 (this is the last release on Rack 0.4)
+
+  * Log unhandled exception backtraces to rack.errors.
+
+  * Use RACK_ENV environment variable to establish Sinatra
+    environment when given. Thin sets this when started with
+    the -e argument.
+
+  * BUG: raising Sinatra::NotFound resulted in a 500 response
+    code instead of 404.
+
+  * BUG: use_in_file_templates! failes with CR/LF (#45)
+
+  * BUG: Sinatra detects the app file and root path when run under
+    thin/passenger.
+
+= 0.3.2
+
+  * BUG: Static and send_file read entire file into String before
+    sending. Updated to stream with 8K chunks instead.
+
+  * Rake tasks and assets for building basic documentation website.
+    See http://sinatra.rubyforge.org
+
+  * Various minor doc fixes.
+
+= 0.3.1
+
+  * Unbreak optional path parameters [jeremyevans]
+
+= 0.3.0
+
+  * Add sinatra.gemspec w/ support for github gem builds. Forks can now
+    enable the build gem option in github to get free username-sinatra.gem
+    builds: gem install username-sinatra.gem --source=http://gems.github.com/
+
+  * Require rack-0.4 gem; removes frozen rack dir.
+
+  * Basic RSpec support; require 'sinatra/test/rspec' instead of
+    'sinatra/test/spec' to use. [avdi]
+
+  * before filters can modify request environment vars used for
+    routing (e.g., PATH_INFO, REQUEST_METHOD, etc.) for URL rewriting
+    type functionality.
+
+  * In-file templates now uses @@ instead of ## as template separator.
+
+  * Top-level environment test predicates: development?, test?, production?
+
+  * Top-level "set", "enable", and "disable" methods for tweaking
+    app options. [rtomayko]
+
+  * Top-level "use" method for building Rack middleware pipelines
+    leading to app. See README for usage. [rtomayko]
+
+  * New "reload" option - set false to disable reloading in development.
+
+  * New "host" option - host/ip to bind to [cschneid]
+
+  * New "app_file" option - override the file to reload in development
+    mode [cschneid]
+
+  * Development error/not_found page cleanup [sr, adamwiggins]
+
+  * Remove a bunch of core extensions (String#to_param, String#from_param,
+    Hash#from_params, Hash#to_params, Hash#symbolize_keys, Hash#pass)
+
+  * Various grammar and formatting fixes to README; additions on
+    community and contributing [cypher]
+
+  * Build RDoc using Hanna template: http://sinatrarb.rubyforge.org/api
+
+  * Specs, documentation and fixes for splat'n routes [vic]
+
+  * Fix whitespace errors across all source files. [rtomayko]
+
+  * Fix streaming issues with Mongrel (body not closed). [bmizerany]
+
+  * Fix various issues with environment not being set properly (configure
+    blocks not running, error pages not registering, etc.) [cypher]
+
+  * Fix to allow locals to be passed to ERB templates [cschneid]
+
+  * Fix locking issues causing random errors during reload in development.
+
+  * Fix for escaped paths not resolving static files [Matthew Walker]
+
+= 0.2.1
+
+  * File upload fix and minor tweaks.
+
+= 0.2.0
+
+  * Initial gem release of 0.2 coebase.

data/README.rdoc

@@ -1,7 +1,9 @@
 = Sinatra
 
 Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
-effort:
+effort.
+
+== Sample App
 
   # myapp.rb
   require 'rubygems'
@@ -30,6 +32,10 @@ Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
     .. annihilate something ..
   end
 
+  head '/' do
+
+  end
+
 == Routes
 
 Routes are matched based on the order of declaration. The first route that
@@ -41,17 +47,14 @@ Basic routes:
     ...
   end
 
-Route patterns may include named parameters, accessible via the
-<tt>params</tt> hash:
+Named parameters:
 
   get '/:name' do
     # matches "GET /foo" and "GET /bar"
     # params[:name] is 'foo' or 'bar'
-    "Hello #{params[:name]}!"
   end
 
-Route patterns may also include splat (or wildcard) parameters, accessible
-via the <tt>params[:splat]</tt> array.
+Splat parameters:
 
   get '/say/*/to/*' do
     # matches /say/hello/to/world
@@ -63,13 +66,7 @@ via the <tt>params[:splat]</tt> array.
     params[:splat] # => ["path/to/file", "xml"]
   end
 
-Route matching with Regular Expressions:
-
-  get %r{/hello/([\w]+)} do
-    "Hello, #{params[:captures].first}!"
-  end
-
-Routes may include a variety of matching conditions, such as the user agent:
+User agent matching:
 
   get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
     "You're using Songbird version #{params[:agent][0]}"
@@ -81,29 +78,33 @@ Routes may include a variety of matching conditions, such as the user agent:
 
 == Static Files
 
-Static files are served from the <tt>./public</tt> directory. You can specify
-a different location by setting the <tt>:public</tt> option:
+Put all of your static content in the ./public directory
+
+  root
+    \ public
+
+To use a different static directory:
 
   set :public, File.dirname(__FILE__) + '/static'
 
-== Views / Templates
+== Views
+
+Views are searched for in a ./views directory in the same location as
+your main application.
 
-Templates are assumed to be located directly under a <tt>./views</tt>
-directory. To use a different views directory:
+To use a different views directory:
 
   set :views, File.dirname(__FILE__) + '/templates'
 
 === Haml Templates
 
-The haml gem/library is required to render HAML templates:
-
   get '/' do
     haml :index
   end
 
 Renders <tt>./views/index.haml</tt>.
 
-=== Erb Templates
+=== Erb
 
   get '/' do
     erb :index
@@ -111,20 +112,11 @@ Renders <tt>./views/index.haml</tt>.
 
 Renders <tt>./views/index.erb</tt>
 
-=== Builder Templates
+=== Builder
 
-The builder gem/library is required to render builder templates:
+See Sinatra::Builder
 
-  get '/' do
-    content_type 'application/xml', :charset => 'utf-8'
-    builder :index
-  end
-
-Renders <tt>./views/index.builder</tt>.
-
-=== Sass Templates
-
-The sass gem/library is required to render Sass templates:
+=== Sass
 
   get '/stylesheet.css' do
     content_type 'text/css', :charset => 'utf-8'
@@ -143,8 +135,9 @@ Renders the inlined template string.
 
 === Accessing Variables
 
-Templates are evaluated within the same context as the route blocks. Instance
-variables set in route blocks are available in templates:
+Templates are evaluated within the Sinatra::EventContext instance
+used to evaluate event blocks. Instance variables set in event
+blocks can be accessed direcly in views:
 
   get '/:id' do
     @foo = Foo.find(params[:id])
@@ -165,32 +158,27 @@ other templates.
 
 Templates may be defined at the end of the source file:
 
-  require 'rubygems'
-  require 'sinatra'
-
   get '/' do
     haml :index
   end
 
+  use_in_file_templates!
+
   __END__
 
   @@ layout
-  %html
-    = yield
+  X
+  = yield
+  X
 
   @@ index
   %div.title Hello world!!!!!
 
-NOTE:  Sinatra will automaticly load any in-file-templates in the
-source file that first required sinatra.  If you have in-file-templates
-in another source file you will need to explicitly call
-+use_in_file_templates! on main in that file.
-
 It's also possible to define named templates using the top-level template
 method:
 
   template :layout do
-    "%html\n  =yield\n"
+    "X\n=yield\nX"
   end
 
   template :index do
@@ -201,17 +189,9 @@ method:
     haml :index
   end
 
-If a template named "layout" exists, it will be used each time a template
-is rendered. You can disable layouts by passing <tt>:layout => false</tt>.
-
-  get '/' do
-    haml :index, :layout => !request.xhr?
-  end
-
 == Helpers
 
-Use the top-level <tt>helpers</tt> method to define helper methods for use in
-route blocks and templates:
+The top-level <tt>helpers</tt> method
 
   helpers do
     def bar(name)
@@ -225,9 +205,7 @@ route blocks and templates:
 
 == Filters
 
-Before filters are evaluated before each request within the context of the
-request and can modify the request and response. Instance variables set in
-filters are accessible by routes and templates.
+Before filters are evaluated in request context before routing is performed:
 
   before do
     @note = 'Hi!'
@@ -239,75 +217,64 @@ filters are accessible by routes and templates.
     params[:splat] #=> 'bar/baz'
   end
 
-== Halting
+Before filters can modify the request and response; instance variables are
+available to routes.
 
-To immediately stop a request during a before filter or route use:
+== Halt!
 
-  halt
+To immediately stop a request during a before filter or event use:
 
-You can also specify a body when halting ...
+  throw :halt
 
-  halt 'this will be the body'
+Set the body to a simple string
 
-Set the status and body ...
+  throw :halt, 'this will be the body'
 
-  halt 401, 'go away!'
+Set status then the body
 
-== Passing
+  throw :halt, [401, 'go away!']
 
-A route can punt processing to the next matching route using the <tt>pass</tt>
-statement:
+Run a proc inside the Sinatra::EventContext instance and set the body to the
+result
 
-  get '/guess/:who' do
-    pass unless params[:who] == 'Frank'
-    "You got me!"
-  end
-
-  get '/guess/*' do
-    "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.
+  throw :halt, lambda { puts 'In a proc!'; 'I just wrote to $stdout!' }
 
 == 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.
+before every request when running under the :development environment. Wrap
+your configurations in <tt>configure</tt> (i.e. Database connections, Constants,
+etc.) to protect them from reloading or to target specific environments.
 
-Run once, at startup, in any environment:
+All environments:
 
   configure do
     ...
   end
 
-Run only when the environment (RACK_ENV environment variable) is set to
-<tt>:production</tt>.
+Production:
 
   configure :production do
     ...
   end
 
-Run when the environment (RACK_ENV environment variable) is set to
-either <tt>:production</tt> or <tt>:test</tt>.
+Two at a time:
 
   configure :production, :test do
     ...
   end
 
+This is also really nifty for error handling.
+
 == Error handling
 
-Error handlers run within the same context as routes and before filters, which
-means you get all the goodies it has to offer, like <tt>haml</tt>, <tt>erb</tt>,
-<tt>halt</tt>, etc.
+Error handlers run inside the current Sinatra::EventContext instance, which
+means you get all the goodies it has to offer (i.e. haml, erb, throw :halt,
+etc.)
 
 === Not Found
 
-When a <tt>Sinatra::NotFound</tt> exception is raised, or the response's status
-code is 404, the <tt>not_found</tt> handler is invoked:
+When Sinatra::NotFound is raised, the not_found handler is invoked:
 
   not_found do
     'This is nowhere to be found'
@@ -315,12 +282,14 @@ 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
-'sinatra.error' Rack variable:
+By default, the +error+ handler is invoked on Sinatra::ServerError or when
+an unknown error occurs.
+
+The exception can be obtained from the 'sinatra.error' variable in
+request.env.
 
   error do
-    'Sorry there was a nasty error - ' + env['sinatra.error'].name
+    'Sorry there was a nasty error - ' + request.env['sinatra.error'].name
   end
 
 Custom errors:
@@ -340,12 +309,12 @@ You get this:
   So what happened was... something bad
 
 Sinatra installs special not_found and error handlers when running under
-the development environment.
+the development.
 
 == 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:
+When using send_file or static files you may have mime types Sinatra doesn't
+understand.  Use +mime+ in those cases.
 
   mime :foo, 'text/foo'
 
@@ -386,61 +355,59 @@ typically don't have to +use+ them explicitly.
 
 == Testing
 
-The Sinatra::Test module includes a variety of helper methods for testing
-your Sinatra app. Sinatra includes support for Test::Unit, test-spec, RSpec,
-and Bacon through separate source files.
-
-=== Test::Unit
+=== Test/Unit
 
+  require 'rubygems'
   require 'sinatra'
   require 'sinatra/test/unit'
   require 'my_sinatra_app'
 
   class MyAppTest < Test::Unit::TestCase
+
     def test_my_default
-      get '/'
+      get_it '/'
       assert_equal 'My Default Page!', @response.body
     end
 
     def test_with_agent
-      get '/', :agent => 'Songbird'
+      get_it '/', :agent => 'Songbird'
       assert_equal 'You're in Songbird!', @response.body
     end
 
     ...
-  end
 
-=== Test::Spec
+  end
 
-Install the test-spec gem and require <tt>'sinatra/test/spec'</tt> before
-your app:
+=== Test/Spec
 
+  require 'rubygems'
   require 'sinatra'
   require 'sinatra/test/spec'
   require 'my_sinatra_app'
 
   describe 'My app' do
+
     it "should show a default page" do
-      get '/'
+      get_it '/'
       should.be.ok
       body.should.equal 'My Default Page!'
     end
 
     ...
+
   end
 
 === RSpec
 
-Install the rspec gem and require <tt>'sinatra/test/rspec'</tt> before
-your app:
-
+  require 'rubygems'
+  require 'spec'
   require 'sinatra'
   require 'sinatra/test/rspec'
   require 'my_sinatra_app'
 
   describe 'My app' do
     it 'should show a default page' do
-      get '/'
+      get_it '/'
       @response.should be_ok
       @response.body.should == 'My Default Page!'
     end
@@ -449,35 +416,20 @@ your app:
 
   end
 
-=== Bacon
-
-  require 'sinatra'
-  require 'sinatra/test/bacon'
-  require 'my_sinatra_app'
-
-  describe 'My app' do
-    it 'should be ok' do
-      get '/'
-      should.be.ok
-      body.should == 'Im OK'
-    end
-  end
-
-See Sinatra::Test for more information on +get+, +post+, +put+, and
-friends.
+See Sinatra::Test::Methods for more information on +get_it+, +post_it+,
++put_it+, and friends.
 
 == Command line
 
 Sinatra applications can be run directly:
 
-  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-s HANDLER]
+  ruby myapp.rb [-h] [-x] [-p PORT] [-e ENVIRONMENT]
 
 Options are:
 
   -h # help
   -p # set the port (default is 4567)
   -e # set the environment (default is development)
-  -s # specify rack server/handler (default is thin)
   -x # turn on the mutex lock (default is off)
 
 == Contributing
@@ -510,7 +462,7 @@ screencasts about Git, which you can find here: http://www.gitcasts.com/
 
 at the top of your sinatra_app.rb file:
 
-  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
+  $:.unshift File.dirname(__FILE__) + '/sinatra/lib'
   require 'sinatra'
 
   get '/about' do