sinatra-sinatra 0.8.9

data/README.rdoc

@@ -0,0 +1,545 @@
+= Sinatra
+
+Sinatra is a DSL for quickly creating web-applications in Ruby with minimal
+effort:
+
+  # myapp.rb
+  require 'rubygems'
+  require 'sinatra'
+  get '/' do
+    'Hello world!'
+  end
+
+Run with <tt>ruby myapp.rb</tt> and view at <tt>http://localhost:4567</tt>
+
+== HTTP Methods
+
+  get '/' do
+    .. show things ..
+  end
+
+  post '/' do
+    .. create something ..
+  end
+
+  put '/' do
+    .. update something ..
+  end
+
+  delete '/' do
+    .. annihilate something ..
+  end
+
+== Routes
+
+Routes are matched based on the order of declaration. The first route that
+matches the request is invoked.
+
+Basic routes:
+
+  get '/hi' do
+    ...
+  end
+
+Route patterns may include named parameters, accessible via the
+<tt>params</tt> hash:
+
+  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.
+
+  get '/say/*/to/*' do
+    # matches /say/hello/to/world
+    params[:splat] # => ["hello", "world"]
+  end
+
+  get '/download/*.*' do
+    # matches /download/path/to/file.xml
+    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:
+
+  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
+    "You're using Songbird version #{params[:agent][0]}"
+  end
+
+  get '/foo' do
+    # Matches non-songbird browsers
+  end
+
+== 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:
+
+  set :public, File.dirname(__FILE__) + '/static'
+
+== Views / Templates
+
+Templates are assumed to be located directly under a <tt>./views</tt>
+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
+
+  get '/' do
+    erb :index
+  end
+
+Renders <tt>./views/index.erb</tt>
+
+=== Builder Templates
+
+The builder gem/library is required to render builder templates:
+
+  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:
+
+  get '/stylesheet.css' do
+    content_type 'text/css', :charset => 'utf-8'
+    sass :stylesheet
+  end
+
+Renders <tt>./views/stylesheet.sass</tt>.
+
+=== Inline Templates
+
+  get '/' do
+    haml '%div.title Hello World'
+  end
+
+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:
+
+  get '/:id' do
+    @foo = Foo.find(params[:id])
+    haml '%h1= @foo.name'
+  end
+
+Or, specify an explicit Hash of local variables:
+
+  get '/:id' do
+    foo = Foo.find(params[:id])
+    haml '%h1= foo.name', :locals => { :foo => foo }
+  end
+
+This is typically used when rendering templates as partials from within
+other templates.
+
+=== In-file Templates
+
+Templates may be defined at the end of the source file:
+
+  get '/' do
+    haml :index
+  end
+
+  use_in_file_templates!
+
+  __END__
+
+  @@ layout
+  %html
+    = yield
+
+  @@ index
+  %div.title Hello world!!!!!
+
+It's also possible to define named templates using the top-level template
+method:
+
+  template :layout do
+    "%html\n  =yield\n"
+  end
+
+  template :index do
+    '%div.title Hello World!'
+  end
+
+  get '/' do
+    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:
+
+  helpers do
+    def bar(name)
+      "#{name}bar"
+    end
+  end
+
+  get '/:name' do
+    bar(params[:name])
+  end
+
+== 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 do
+    @note = 'Hi!'
+    request.path_info = '/foo/bar/baz'
+  end
+
+  get '/foo/*' do
+    @note #=> 'Hi!'
+    params[:splat] #=> 'bar/baz'
+  end
+
+== Halting
+
+To immediately stop a request during a before filter or route use:
+
+  halt
+
+You can also specify a body when halting ...
+
+  halt 'this will be the body'
+
+Set the status and body ...
+
+  halt 401, 'go away!'
+
+== Passing
+
+A route can punt processing to the next matching route using the <tt>pass</tt>
+statement:
+
+  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.
+
+== 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.
+
+Run once, at startup, in any environment:
+
+  configure do
+    ...
+  end
+
+Run only when the environment (RACK_ENV environment variable) is set to
+<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>.
+
+  configure :production, :test do
+    ...
+  end
+
+== 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.
+
+=== 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:
+
+  not_found do
+    'This is nowhere to be found'
+  end
+
+=== 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:
+
+  error do
+    'Sorry there was a nasty error - ' + env['sinatra.error'].name
+  end
+
+Custom errors:
+
+  error MyCustomError do
+    'So what happened was...' + request.env['sinatra.error'].message
+  end
+
+Then, if this happens:
+
+  get '/' do
+    raise MyCustomError, 'something bad'
+  end
+
+You get this:
+
+  So what happened was... something bad
+
+Sinatra installs special not_found and error 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:
+
+  mime :foo, 'text/foo'
+
+== Rack Middleware
+
+Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
+interface for Ruby web frameworks. One of Rack's most interesting capabilities
+for application developers is support for "middleware" -- components that sit
+between the server and your application monitoring and/or manipulating the
+HTTP request/response to provide various types of common functionality.
+
+Sinatra makes building Rack middleware pipelines a cinch via a top-level
++use+ method:
+
+  require 'sinatra'
+  require 'my_custom_middleware'
+
+  use Rack::Lint
+  use MyCustomMiddleware
+
+  get '/hello' do
+    'Hello World'
+  end
+
+The semantics of +use+ are identical to those defined for the
+Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
+(most frequently used from rackup files). For example, the +use+ method
+accepts multiple/variable args as well as blocks:
+
+  use Rack::Auth::Basic do |username, password|
+    username == 'admin' && password == 'secret'
+  end
+
+Rack is distributed with a variety of standard middleware for logging,
+debugging, URL routing, authentication, and session handling. Sinatra uses
+many of of these components automatically based on configuration so you
+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
+
+  require 'sinatra'
+  require 'sinatra/test/unit'
+  require 'my_sinatra_app'
+
+  class MyAppTest < Test::Unit::TestCase
+    def test_my_default
+      get '/'
+      assert_equal 'My Default Page!', @response.body
+    end
+
+    def test_with_agent
+      get '/', :agent => 'Songbird'
+      assert_equal 'You're in Songbird!', @response.body
+    end
+
+    ...
+  end
+
+=== Test::Spec
+
+Install the test-spec gem and require <tt>'sinatra/test/spec'</tt> before
+your app:
+
+  require 'sinatra'
+  require 'sinatra/test/spec'
+  require 'my_sinatra_app'
+
+  describe 'My app' do
+    it "should show a default page" do
+      get '/'
+      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 'sinatra'
+  require 'sinatra/test/rspec'
+  require 'my_sinatra_app'
+
+  describe 'My app' do
+    it 'should show a default page' do
+      get '/'
+      @response.should be_ok
+      @response.body.should == 'My Default Page!'
+    end
+
+    ...
+
+  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.
+
+== Command line
+
+Sinatra applications can be run directly:
+
+  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)
+  -x # turn on the mutex lock (default is off)
+
+== Contributing
+
+=== Tools
+
+Besides Ruby itself, you only need a text editor, preferably one that supports
+Ruby syntax hilighting. VIM and Emacs are a fine choice on any platform, but
+feel free to use whatever you're familiar with.
+
+Sinatra uses the Git source code management system. If you're unfamiliar with
+Git, you can find more information and tutorials on http://git.or.cz/ as well
+as http://git-scm.com/.  Scott Chacon created a great series of introductory
+screencasts about Git, which you can find here: http://www.gitcasts.com/
+
+=== First Time: Cloning The Sinatra Repo
+
+  cd where/you/keep/your/projects
+  git clone git://github.com/bmizerany/sinatra.git
+  cd sinatra
+  cd path/to/your_project
+  ln -s ../sinatra/
+
+=== Updating Your Existing Sinatra Clone
+
+  cd where/you/keep/sinatra
+  git pull
+
+=== Using Edge Sinatra in Your App
+
+at the top of your sinatra_app.rb file:
+
+  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
+  require 'sinatra'
+
+  get '/about' do
+    "I'm running on Version " + Sinatra::VERSION
+  end
+
+=== Contributing a Patch
+
+There are several ways to do this. Probably the easiest (and preferred) way is
+to fork Sinatra on GitHub (http://github.com/bmizerany/sinatra), push your
+changes to your Sinatra repo, and then send Blake Mizerany (bmizerany on
+GitHub) a pull request.
+
+You can also create a patch file and attach it to a feature request or bug fix
+on the issue tracker (see below) or send it to the mailing list (see Community
+section).
+
+=== Issue Tracking and Feature Requests
+
+http://sinatra.lighthouseapp.com/
+
+== Community
+
+=== Mailing List
+
+http://groups.google.com/group/sinatrarb
+
+If you have a problem or question, please make sure to include all the
+relevant information in your mail, like the Sinatra version you're using, what
+version of Ruby you have, and so on.
+
+=== IRC Channel
+
+You can find us on the Freenode network in the channel #sinatra
+(irc://chat.freenode.net/#sinatra)
+
+There's usually someone online at any given time, but we cannot pay attention
+to the channel all the time, so please stick around for a while after asking a
+question.

data/Rakefile

@@ -0,0 +1,180 @@
+require 'rubygems'
+require 'rake/clean'
+require 'fileutils'
+
+task :default => :test
+
+# SPECS ===============================================================
+
+desc 'Run specs with story style output'
+task :spec do
+  pattern = ENV['TEST'] || '.*'
+  sh "specrb --testcase '#{pattern}' --specdox -Ilib:test test/*_test.rb"
+end
+
+desc 'Run specs with unit test style output'
+task :test do |t|
+  sh "specrb -Ilib:test test/*_test.rb"
+end
+
+desc 'Run compatibility specs'
+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
+def spec
+  @spec ||=
+    begin
+      require 'rubygems/specification'
+      data = File.read('sinatra.gemspec')
+      spec = nil
+      Thread.new { spec = eval("$SAFE = 3\n#{data}") }.join
+      spec
+    end
+end
+
+def package(ext='')
+  "dist/sinatra-#{spec.version}" + ext
+end
+
+desc 'Build packages'
+task :package => %w[.gem .tar.gz].map {|e| package(e)}
+
+desc 'Build and install as local gem'
+task :install => package('.gem') do
+  sh "gem install #{package('.gem')}"
+end
+
+directory 'dist/'
+
+file package('.gem') => %w[dist/ 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|
+  sh "git archive --format=tar HEAD | gzip > #{f.name}"
+end
+
+# Rubyforge Release / Publish Tasks ==================================
+
+desc 'Publish website to rubyforge'
+task 'publish:doc' => 'doc/api/index.html' do
+  sh 'scp -rp doc/* rubyforge.org:/var/www/gforge-projects/sinatra/'
+end
+
+task 'publish:gem' => [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')}
+  end
+end
+
+# Website ============================================================
+# Building docs requires HAML and the hanna gem:
+#   gem install mislav-hanna --source=http://gems.github.com
+
+task 'doc'     => ['doc:api','doc:site']
+
+desc 'Generate Hanna RDoc under doc/api'
+task 'doc:api' => ['doc/api/index.html']
+
+file 'doc/api/index.html' => FileList['lib/**/*.rb','README.rdoc'] do |f|
+  rb_files = f.prerequisites
+  sh((<<-end).gsub(/\s+/, ' '))
+    hanna --charset utf8 \
+          --fmt html \
+          --inline-source \
+          --line-numbers \
+          --main README.rdoc \
+          --op doc/api \
+          --title 'Sinatra API Documentation' \
+          #{rb_files.join(' ')}
+  end
+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
+
+def haml(locals={})
+  require 'haml'
+  template = File.read('doc/template.haml')
+  haml = Haml::Engine.new(template, :format => :html4, :attr_wrapper => '"')
+  haml.render(Object.new, locals)
+end
+
+desc 'Build website HTML and stuff'
+task 'doc:site' => ['doc/index.html', 'doc/book.html']
+
+file 'doc/index.html' => %w[README.rdoc doc/template.haml] do |file|
+  File.open(file.name, 'w') do |file|
+    file << haml(:title => 'Sinatra', :content => rdoc_to_html('README.rdoc'))
+  end
+end
+CLEAN.include 'doc/index.html'
+
+file 'doc/book.html' => ['book/output/sinatra-book.html'] do |file|
+  File.open(file.name, 'w') do |file|
+    book_content = File.read('book/output/sinatra-book.html')
+    file << haml(:title => 'Sinatra Book', :content => book_content)
+  end
+end
+CLEAN.include 'doc/book.html'
+
+file 'book/output/sinatra-book.html' => FileList['book/**'] do |f|
+  unless File.directory?('book')
+    sh 'git clone git://github.com/cschneid/sinatra-book.git book'
+  end
+  sh((<<-SH).strip.gsub(/\s+/, ' '))
+    cd book &&
+    git fetch origin &&
+    git rebase origin/master &&
+    thor book:build
+  SH
+end
+CLEAN.include 'book/output/sinatra-book.html'
+
+desc 'Build the Sinatra book'
+task 'doc:book' => ['book/output/sinatra-book.html']
+
+# Gemspec Helpers ====================================================
+
+def source_version
+  line = File.read('lib/sinatra/base.rb')[/^\s*VERSION = .*/]
+  line.match(/.*VERSION = '(.*)'/)[1]
+end
+
+project_files =
+  FileList[
+    '{lib,test,compat,images}/**',
+    'Rakefile', 'CHANGES', 'README.rdoc'
+  ]
+file 'sinatra.gemspec' => project_files do |f|
+  # read spec file and split out manifest section
+  spec = File.read(f.name)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+  # replace version and date
+  head.sub!(/\.version = '.*'/, ".version = '#{source_version}'")
+  head.sub!(/\.date = '.*'/, ".date = '#{Date.today.to_s}'")
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject{ |file| file =~ /^\./ }.
+    reject { |file| file =~ /^doc/ }.
+    map{ |file| "    #{file}" }.
+    join("\n")
+  # piece file back together and write...
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head,manifest,tail].join("  # = MANIFEST =\n")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "updated #{f.name}"
+end