1
0
Fork 0
mirror of https://github.com/sinatra/sinatra synced 2023-03-27 23:18:01 -04:00
Classy web-development dressed in a DSL (official / canonical repo)
Find a file
Konstantin Haase 8815d4e973 thanks foca
2011-03-03 00:14:59 +01:00
lib update Sinatra::VERSION 2011-02-27 09:48:05 +01:00
test correct builder test name in load error warning, fixes #196. 2011-02-27 09:45:26 +01:00
.gitignore
.yardopts
AUTHORS thanks foca 2011-03-03 00:14:59 +01:00
CHANGES add 1.1.3 release date to changes 2011-02-27 09:48:37 +01:00
Gemfile Use platforms properly in Gemfile, even though bundler is broken. 2011-02-26 15:48:14 +01:00
LICENSE
Rakefile add rake task for generating release specific contributor list 2011-02-28 10:37:33 +01:00
README.de.rdoc
README.es.rdoc add example for halt with template in spanish readme 2011-03-01 17:18:40 +01:00
README.fr.rdoc
README.hu.rdoc
README.jp.rdoc
README.pt-br.rdoc
README.rdoc add example for halt with template 2011-02-27 09:47:07 +01:00
README.ru.rdoc
README.zh.rdoc bring Chinese README up to speed, fixes #197 2011-02-27 14:05:37 +01:00
sinatra.gemspec 1.2.0.d release 2011-02-26 16:18:52 +01:00

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

= Sinatra
<i>注:本文档仅仅是英文版的翻译,会出现内容没有及时更新的情况发生。
如有不一致的地方,请以英文版为准。</i>

Sinatra是一个基于Ruby语言以最小精力为代价快速创建web应用为目的的DSL
领域专属语言):

  # myapp.rb
  require 'sinatra'

  get '/' do
    'Hello world!'
  end

安装gem然后运行

  gem install sinatra
  ruby -rubygems myapp.rb

在该地址查看: http://localhost:4567

推荐同时运行<tt>gem install thin</tt>Sinatra会优先选择thin作为服务器。

== 路由

在Sinatra中一个路由是一个HTTP方法与URL匹配范式的配对。
每个路由都与一个代码块关联:

  get '/' do
    .. 显示一些事物 ..
  end

  post '/' do
    .. 创建一些事物 ..
  end

  put '/' do
    .. 更新一些事物 ..
  end

  delete '/' do
    .. 消灭一些事物 ..
  end

  options '/' do
    .. 满足一些事物 ..
  end

路由按照它们被定义的顺序进行匹配。
第一个与请求匹配的路由会被调用。

路由范式可以包括具名参数,可通过<tt>params</tt>哈希表获得:

  get '/hello/:name' do
    # 匹配 "GET /hello/foo" 和 "GET /hello/bar"
    # params[:name] 的值是 'foo' 或者 'bar'
    "Hello #{params[:name]}!"
  end

你同样可以通过代码块参数获得具名参数:

  get '/hello/:name' do |n|
    "Hello #{n}!"
  end

路由范式也可以包含通配符参数,
可以通过<tt>params[:splat]</tt> 数组获得。

  get '/say/*/to/*' do
    # 匹配 /say/hello/to/world
    params[:splat] # => ["hello", "world"]
  end

  get '/download/*.*' do
    # 匹配 /download/path/to/file.xml
    params[:splat] # => ["path/to/file", "xml"]
  end

通过正则表达式匹配的路由:

  get %r{/hello/([\w]+)} do
    "Hello, #{params[:captures].first}!"
  end

或者使用代码块参数:

  get %r{/hello/([\w]+)} do |c|
    "Hello, #{c}!"
  end

=== 条件

路由也可以包含多样的匹配条件比如user agent

  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
    "你正在使用Songbird版本是 #{params[:agent][0]}"
  end

  get '/foo' do
    # 匹配除Songbird以外的浏览器
  end

其他可选的条件是 +host_name+ 和 +provides+

  get '/', :host_name => /^admin\./ do
    "管理员区域,无权进入!"
  end

  get '/', :provides => 'html' do
    haml :index
  end
  
  get '/', :provides => ['rss', 'atom', 'xml'] do
    builder :feed
  end

你也可以很轻松地定义自己的条件:

  set(:probability) { |value| condition { rand <= value } }
  
  get '/win_a_car', :probability => 0.1 do
    "You won!"
  end
  
  get '/win_a_car' do
    "Sorry, you lost."
  end

=== 返回值

路由代码块的返回值至少决定了返回给HTTP客户端的响应体
或者至少决定了在Rack堆栈中的下一个中间件。
大多数情况下,将是一个字符串,就像上面的例子中的一样。
但是其他值也是可以接受的。

你可以返回任何对象或者是一个合理的Rack响应
Rack body对象或者HTTP状态码

* 一个包含三个元素的数组: <tt>[状态 (Fixnum), 头 (Hash), 响应体 (回应 #each)]</tt>
* 一个包含两个元素的数组: <tt>[状态 (Fixnum), 响应体 (回应 #each)]</tt>
* 一个能够回应 <tt>#each</tt> ,只传回字符串的对象
* 一个代表状态码的数字

那样,我们可以轻松的实现例如流式传输的例子:

    class Stream
      def each
        100.times { |i| yield "#{i}\n" }
      end
    end

    get('/') { Stream.new }

=== 自定义路由匹配器

如上显示Sinatra内置了对于使用字符串和正则表达式作为路由匹配的支持。
但是,它并没有只限于此。
你可以非常容易地定义你自己的匹配器:

  class AllButPattern
    Match = Struct.new(:captures)

    def initialize(except)
      @except   = except
      @caputres = Match.new([])
    end

    def match(str)
      @caputres unless @except === str
    end
  end

  def all_but(pattern)
    AllButPattern.new(pattern)
  end

  get all_but("/index") do
    # ...
  end

请注意上面的例子可能超工程了,
因为它也可以用更简单的方式表述:

  get // do
    pass if request.path_info == "/index"
    # ...
  end

或者,使用消极向前查找:

  get %r{^(?!/index$)} do
    # ...
  end

== 静态文件

静态文件是从 <tt>./public</tt> 目录提供服务。你可以通过设置<tt>:public</tt>
选项设定一个不同的位置:

  set :public, File.dirname(__FILE__) + '/static'

请注意public目录名并没有被包含在URL之中。文件
<tt>./public/css/style.css</tt>是通过
<tt>http://example.com/css/style.css</tt>地址访问的。

== 视图 / 模板

模板被假定直接位于<tt>./views</tt>目录。
要使用不同的视图目录:

  set :views, File.dirname(__FILE__) + '/templates'

请记住一件非常重要的事情,你只可以通过符号引用模板,
即使它们在子目录下
(在这种情况下,使用 <tt>:'subdir/template'</tt>)。
你必须使用一个符号,
因为渲染方法会直接地渲染任何传入的字符串。 

=== Haml模板

需要引入 <tt>haml</tt> gem/library以渲染 HAML 模板:

  # 你需要在你的应用中引入 haml
  require 'haml'

  get '/' do
    haml :index
  end

渲染 <tt>./views/index.haml</tt>。

{Haml的选项}[http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options]
可以通过Sinatra的配置全局设定
参见 {选项和配置}[http://www.sinatrarb.com/configuration.html]
也可以个别的被覆盖。

  set :haml, {:format => :html5 } # 默认的Haml输出格式是 :xhtml

  get '/' do
    haml :index, :haml_options => {:format => :html4 } # 被覆盖,变成:html4
  end


=== Erb模板

  # 你需要在你的应用中引入 erb
  require 'erb'

  get '/' do
    erb :index
  end

渲染 <tt>./views/index.erb</tt>

=== Erubis

需要引入 <tt>erubis</tt> gem/library以渲染 erubis 模板:

  # 你需要在你的应用中引入 erubis
  require 'erubis'

  get '/' do
    erubis :index
  end

渲染 <tt>./views/index.erubis</tt>

使用Erubis代替Erb也是可能的:

  require 'erubis'
  Tilt.register :erb, Tilt[:erubis]

  get '/' do
    erb :index
  end

使用Erubis来渲染 <tt>./views/index.erb</tt>。

=== Builder 模板

需要引入 <tt>builder</tt> gem/library 以渲染 builder templates

  # 需要在你的应用中引入builder
  require 'builder'

  get '/' do
    builder :index
  end

渲染 <tt>./views/index.builder</tt>。

=== Nokogiri 模板

需要引入 <tt>nokogiri</tt> gem/library 以渲染 nokogiri 模板:

  # 需要在你的应用中引入 nokogiri
  require 'nokogiri'

  get '/' do
    nokogiri :index
  end

渲染 <tt>./views/index.nokogiri</tt>。

=== Sass 模板 

需要引入 <tt>haml</tt> 或者 <tt>sass</tt> gem/library 以渲染 Sass 模板:

  # 需要在你的应用中引入 haml 或者 sass 
  require 'sass'

  get '/stylesheet.css' do
    sass :stylesheet
  end

渲染 <tt>./views/stylesheet.sass</tt>。

{Sass 的选项}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
可以通过Sinatra选项全局设定
参考 {选项和配置(英文)}[http://www.sinatrarb.com/configuration.html],
也可以在个体的基础上覆盖。

  set :sass, {:style => :compact } # 默认的 Sass 样式是 :nested

  get '/stylesheet.css' do
    sass :stylesheet, :style => :expanded # 覆盖
  end

=== Scss 模板 

需要引入 <tt>haml</tt> 或者 <tt>sass</tt> gem/library 来渲染 Scss templates

  # 需要在你的应用中引入 haml 或者 sass
  require 'sass'

  get '/stylesheet.css' do
    scss :stylesheet
  end

渲染 <tt>./views/stylesheet.scss</tt>。

{Scss的选项}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
可以通过Sinatra选项全局设定
参考 {选项和配置(英文)}[http://www.sinatrarb.com/configuration.html],
也可以在个体的基础上覆盖。

  set :scss, :style => :compact # default Scss style is :nested

  get '/stylesheet.css' do
    scss :stylesheet, :style => :expanded # overridden
  end

=== Less 模板 

需要引入 <tt>less</tt> gem/library 以渲染 Less 模板:

  # 需要在你的应用中引入 less
  require 'less'

  get '/stylesheet.css' do
    less :stylesheet
  end

渲染 <tt>./views/stylesheet.less</tt>。

=== Liquid 模板 

需要引入 <tt>liquid</tt> gem/library 来渲染 Liquid 模板:

  # 需要在你的应用中引入 liquid
  require 'liquid'

  get '/' do
    liquid :index
  end

渲染 <tt>./views/index.liquid</tt>。

因为你不能在Liquid 模板中调用 Ruby 方法 (除了 +yield+) 
你几乎总是需要传递locals给它

  liquid :index, :locals => { :key => 'value' }

=== Markdown 模板

需要引入 <tt>rdiscount</tt> gem/library 以渲染 Markdown 模板:

  # 需要在你的应用中引入rdiscount
  require "rdiscount"
  
  get '/' do
    markdown :index
  end

渲染 <tt>./views/index.markdown</tt> 
(+md+ 和 +mkd+ 也是合理的文件扩展名)。

在markdown中是不可以调用方法的也不可以传递 locals给它。
你因此一般会结合其他的渲染引擎来使用它:


  erb :overview, :locals => { :text => markdown(:introduction) }

请注意你也可以从其他模板中调用 markdown 方法:

  %h1 Hello From Haml!
  %p= markdown(:greetings)

既然你不能在Markdown中调用Ruby你不能使用Markdown编写的布局。
不过,使用其他渲染引擎作为模版的布局是可能的,
通过传递<tt>:layout_engine</tt>选项:

  get '/' do
    markdown :index, :layout_engine => :erb
  end

这将会渲染 <tt>./views/index.md</tt> 并使用
<tt>./views/layout.erb</tt> 作为布局。

请记住你可以全局设定这个选项:

  set :markdown, :layout_engine => :haml, :layout => :post

  get '/' do
    markdown :index
  end

这将会渲染 <tt>./views/index.markdown</tt> (和任何其他的 Markdown
模版) 并使用 <tt>./views/post.haml</tt> 作为布局.

也可能使用BlueCloth而不是RDiscount来解析Markdown文件:

  require 'bluecloth'

  Tilt.register 'markdown', BlueClothTemplate
  Tilt.register 'mkd',      BlueClothTemplate
  Tilt.register 'md',       BlueClothTemplate

  get '/' do
    markdown :index
  end

使用BlueCloth来渲染 <tt>./views/index.md</tt> 。

=== Textile 模板

需要引入 <tt>RedCloth</tt> gem/library 以渲染 Textile 模板:

  # 在你的应用中引入redcloth
  require "redcloth"

  get '/' do
    textile :index
  end

渲染 <tt>./views/index.textile</tt>。

在textile中是不可以调用方法的也不可以传递 locals给它。
你因此一般会结合其他的渲染引擎来使用它:

  erb :overview, :locals => { :text => textile(:introduction) }

请注意你也可以从其他模板中调用+textile+方法:

  %h1 Hello From Haml!
  %p= textile(:greetings)

既然你不能在Textile中调用Ruby你不能使用Textile编写的布局。
不过,使用其他渲染引擎作为模版的布局是可能的,
通过传递<tt>:layout_engine</tt>选项:

  get '/' do
    textile :index, :layout_engine => :erb
  end

这将会渲染 <tt>./views/index.textile</tt> 并使用
<tt>./views/layout.erb</tt> 作为布局。

请记住你可以全局设定这个选项:

  set :textile, :layout_engine => :haml, :layout => :post

  get '/' do
    textile :index
  end

这将会渲染 <tt>./views/index.textile</tt> (和任何其他的 Textile
模版) 并使用 <tt>./views/post.haml</tt> 作为布局.

=== RDoc 模板

需要引入 <tt>RDoc</tt> gem/library 以渲染RDoc模板

  # 需要在你的应用中引入rdoc/markup/to_html
  require "rdoc/markup/to_html"

  get '/' do
    rdoc :index
  end

渲染 <tt>./views/index.rdoc</tt>。

在rdoc中是不可以调用方法的也不可以传递locals给它。
你因此一般会结合其他的渲染引擎来使用它:

  erb :overview, :locals => { :text => rdoc(:introduction) }

请注意你也可以从其他模板中调用+rdoc+方法:

  %h1 Hello From Haml!
  %p= rdoc(:greetings)

既然你不能在RDoc中调用Ruby你不能使用RDoc编写的布局。
不过,使用其他渲染引擎作为模版的布局是可能的,
通过传递<tt>:layout_engine</tt>选项:

  get '/' do
    rdoc :index, :layout_engine => :erb
  end

这将会渲染 <tt>./views/index.rdoc</tt> 并使用
<tt>./views/layout.erb</tt> 作为布局。

请记住你可以全局设定这个选项:

  set :rdoc, :layout_engine => :haml, :layout => :post

  get '/' do
    rdoc :index
  end

这将会渲染 <tt>./views/index.rdoc</tt> (和任何其他的 RDoc
模版) 并使用 <tt>./views/post.haml</tt> 作为布局.

=== Radius 模板

需要引入 <tt>radius</tt> gem/library 以渲染 Radius 模板:

  # 需要在你的应用中引入radius
  require 'radius'

  get '/' do
    radius :index
  end

渲染 <tt>./views/index.radius</tt>。

因为你不能在Radius 模板中调用 Ruby 方法 (除了 +yield+) 
你几乎总是需要传递locals给它

  radius :index, :locals => { :key => 'value' }

=== Markaby 模板 

需要引入<tt>markaby</tt> gem/library以渲染Markaby模板

  #需要在你的应用中引入 markaby
  require 'markaby'

  get '/' do
    markaby :index
  end

渲染 <tt>./views/index.mab</tt>。

你也可以使用嵌入的 Markaby:

  get '/' do
    markaby { h1 "Welcome!" }
  end

=== Slim 模板 

需要引入 <tt>slim</tt> gem/library 来渲染 Slim 模板:

  # 需要在你的应用中引入 slim
  require 'slim'

  get '/' do
    slim :index
  end

渲染 <tt>./views/index.slim</tt>。

=== CoffeeScript 模板

需要引入 <tt>coffee-script</tt> gem/library 并至少满足下面条件一项
以执行Javascript:

* +node+ (来自 Node.js) 在你的路径中
* 你正在运行 OSX
* +therubyracer+ gem/library

请察看 http://github.com/josh/ruby-coffee-script 获取更新的选项。

现在你可以渲染 CoffeeScript 模版了:

  # 需要在你的应用中引入coffee-script
  require 'coffee-script'

  get '/application.js' do
    coffee :application
  end

渲染 <tt>./views/application.coffee</tt>。

=== 嵌入模板字符串

  get '/' do
    haml '%div.title Hello World'
  end

渲染嵌入模板字符串。

=== 在模板中访问变量

模板和路由执行器在同样的上下文求值。
在路由执行器中赋值的实例变量可以直接被模板访问。

  get '/:id' do
    @foo = Foo.find(params[:id])
    haml '%h1= @foo.name'
  end

或者,显式地指定一个本地变量的哈希:

  get '/:id' do
    foo = Foo.find(params[:id])
    haml '%h1= foo.name', :locals => { :foo => foo }
  end

典型的使用情况是在别的模板中按照局部模板的方式来渲染。


=== 内联模板

模板可以在源文件的末尾定义:

  require 'sinatra'

  get '/' do
    haml :index
  end

  __END__

  @@ layout
  %html
    = yield

  @@ index
  %div.title Hello world!!!!!

注意引入sinatra的源文件中定义的内联模板才能被自动载入。
如果你在其他源文件中有内联模板,
需要显式执行调用<tt>enable :inline_templates</tt>。

=== 具名模板

模板可以通过使用顶层 <tt>template</tt> 方法定义:

  template :layout do
    "%html\n  =yield\n"
  end

  template :index do
    '%div.title Hello World!'
  end

  get '/' do
    haml :index
  end

如果存在名为"layout"的模板,该模板会在每个模板渲染的时候被使用。
你可以单独地通过传送 <tt>:layout => false</tt>来禁用,
或者通过<tt>set :haml, :layout => false</tt>来禁用他们。

  get '/' do
    haml :index, :layout => !request.xhr?
  end

=== 关联文件扩展名

为了关联一个文件扩展名到一个模版引擎,使用
<tt>Tilt.register</tt>。比如,如果你喜欢使用
+tt+ 作为Textile模版的扩展名你可以这样做:

  Tilt.register :tt, Tilt[:textile]

=== 添加你自己的模版引擎

首先通过Tilt注册你自己的引擎然后创建一个渲染方法:

  Tilt.register :myat, MyAwesomeTemplateEngine

  helpers do
    def myat(*args) render(:myat, *args) end
  end

  get '/' do
    myat :index
  end

渲染 <tt>./views/index.myat</tt>。察看 https://github.com/rtomayko/tilt 
来更多了解Tilt.

== 过滤器

前置过滤器在每个请求前,在请求的上下文环境中被执行,
而且可以修改请求和响应。
在过滤器中设定的实例变量可以被路由和模板访问:

  before do
    @note = 'Hi!'
    request.path_info = '/foo/bar/baz'
  end

  get '/foo/*' do
    @note #=> 'Hi!'
    params[:splat] #=> 'bar/baz'
  end

后置过滤器在每个请求之后,在请求的上下文环境中执行,
而且可以修改请求和响应。
在前置过滤器和路由中设定的实例变量可以被后置过滤器访问:

  after do
    puts response.status
  end

请注意:除非你显式使用 +body+ 方法,而不是在路由中直接返回字符串,
消息体在后置过滤器是不可用的,
因为它在之后才会生成。

过滤器可以可选地带有范式,
只有请求路径满足该范式时才会执行:

  before '/protected/*' do
    authenticate!
  end

  after '/create/:slug' do |slug|
    session[:last_slug] = slug
  end

和路由一样,过滤器也可以带有条件:

  before :agent => /Songbird/ do
    # ...
  end

  after '/blog/*', :host_name => 'example.com' do
    # ...
  end

== 辅助方法

使用顶层的 <tt>helpers</tt> 方法来定义辅助方法,
以便在路由处理器和模板中使用:

  helpers do
    def bar(name)
      "#{name}bar"
    end
  end

  get '/:name' do
    bar(params[:name])
  end

=== 使用 Sessions

Session被用来在请求之间保持状态。如果被激活每一个用户会话
对应有一个session哈希:

  enable :sessions

  get '/' do
    "value = " << session[:value].inspect
  end

  get '/:value' do
    session[:value] = params[:value]
  end

请注意 <tt>enable :sessions</tt> 实际上保存所有的数据在一个cookie之中。
这可能不会总是做你想要的(比如,保存大量的数据会增加你的流量)。
你可以使用任何的Rack session中间件为了这么做
*不要*调用 <tt>enable :sessions</tt>,而是
按照自己的需要引入你的中间件:

  use Rack::Session::Pool, :expire_after => 2592000

  get '/' do
    "value = " << session[:value].inspect
  end

  get '/:value' do
    session[:value] = params[:value]
  end

=== 挂起

要想直接地停止请求,在过滤器或者路由中使用:

  halt

你也可以指定挂起时的状态码:

  halt 410

或者消息体:

  halt 'this will be the body'

或者两者;

  halt 401, 'go away!'

也可以带消息头:

  halt 402, {'Content-Type' => 'text/plain'}, 'revenge'

=== 让路

一个路由可以放弃处理,将处理让给下一个匹配的路由,使用 <tt>pass</tt>

  get '/guess/:who' do
    pass unless params[:who] == 'Frank'
    'You got me!'
  end

  get '/guess/*' do
    'You missed!'
  end

路由代码块被直接退出,控制流继续前进到下一个匹配的路由。
如果没有匹配的路由将返回404。

=== 触发另一个路由

有些时候,+pass+ 并不是你想要的,你希望得到的是另一个路由的结果
。简单的使用 +call+ 可以做到这一点:

  get '/foo' do
    status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
    [status, body.upcase]
  end

  get '/bar' do
    "bar"
  end

请注意在以上例子中,你可以更加简化测试并增加性能,只要简单的移动
 <tt>"bar"</tt>到一个被<tt>/foo</tt>
和 <tt>/bar</tt>同时使用的helper。

如果你希望请求被发送到同一个应用,而不是副本,
使用 <tt>call!</tt> 而不是 <tt>call</tt>.

察看 Rack specification 如果你想更多了解 <tt>call</tt>.

=== 设定 消息体,状态码和消息头

通过路由代码块的返回值来设定状态码和消息体不仅是可能的,而且是推荐的。
但是,在某些场景中你可能想在作业流程中的特定点上设置消息体。
你可以通过 +body+ 辅助方法这么做。
如果你这样做了,
你可以在那以后使用该方法获得消息体:

  get '/foo' do
    body "bar"
  end

  after do
    puts body
  end

也可以传一个代码块给 +body+它将会被Rack处理器执行
这将可以被用来实现streaming参见“返回值”。

和消息体类似,你也可以设定状态码和消息头:

  get '/foo' do
    status 418
    headers \
      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN"
      "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
    body "I'm a tea pot!"
  end

如同 +body+, 不带参数的 +headers+ 和 +status+ 可以用来访问
他们你的当前值.

=== 媒体类型

当使用 <tt>send_file</tt> 或者静态文件的场合,你的媒体类型可能
Sinatra并不理解。使用 +mime_type+ 通过文件扩展名来注册它们:

  mime_type :foo, 'text/foo'

你也可以通过 +content_type+ 辅助方法使用:

  get '/' do
    content_type :foo
    "foo foo foo"
  end

=== 生成 URL

为了生成URL你需要使用 +url+ 辅助方法,
例如在Haml中:

  %a{:href => url('/foo')} foo

它会根据反向代理和Rack路由如果有的话来计算生成的URL。

这个方法还有一个别名 +to+ (见下面的例子).

=== 浏览器重定向

你可以通过 +redirect+ 辅助方法触发浏览器重定向:

  get '/foo' do
    redirect to('/bar')
  end

任何额外的参数都会被以 +halt+相同的方式来处理:

  redirect to('/bar'), 303
  redirect 'http://google.com', 'wrong place, buddy'

你可以方便的通过
<tt>redirect back</tt>把用户重定向到来自的页面:

  get '/foo' do
    "<a href='/bar'>do something</a>"
  end

  get '/bar' do
    do_something
    redirect back
  end

为了传递参数给redirect或者加入query:

  redirect to('/bar?sum=42')

或者使用session:

  enable :session

  get '/foo' do
    session[:secret] = 'foo'
    redirect to('/bar')
  end

  get '/bar' do
    session[:secret]
  end

=== 缓存控制

正确地设定消息头是恰当的HTTP缓存的基础。

你可以方便的设定 Cache-Control 消息头,像这样:

  get '/' do
    cache_control :public
    "cache it!"
  end

核心提示: 在前置过滤器中设定缓存.

  before do
    cache_control :public, :must_revalidate, :max_age => 60
  end

如果你正在用 +expires+ 辅助方法设定对应的消息头
<tt>Cache-Control</tt> 会自动设定:

  before do
    expires 500, :public, :must_revalidate
  end

为了合适地使用缓存,你应该考虑使用 +etag+ 和 +last_modified+方法。.
推荐在执行繁重任务*之前*使用这些helpers
他们会立刻发送响应,如果客户端在缓存中已经有了当前版本。

  get '/article/:id' do
    @article = Article.find params[:id]
    last_modified @article.updated_at
    etag @article.sha1
    erb :article
  end

使用
{weak ETag}[http://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation]
也是有可能的:

  etag @article.sha1, :weak

这些辅助方法并不会为你做任何缓存,而是将必要的信息传送给你的缓存
如果你在寻找缓存的快速解决方案,试试
{rack-cache}[http://rtomayko.github.com/rack-cache/]:

  require "rack/cache"
  require "sinatra"

  use Rack::Cache

  get '/' do
    cache_control :public, :max_age => 36000
    sleep 5
    "hello"
  end

=== 发送文件

为了发送文件,你可以使用 <tt>send_file</tt> 辅助方法:

  get '/' do
    send_file 'foo.png'
  end

也可以带一些选项:

  send_file 'foo.png', :type => :jpg

可用的选项有:

[filename]
  响应中的文件名,默认是真实文件的名字。

[last_modified]
  Last-Modified 消息头的值默认是文件的mtime修改时间。

[type]
  使用的内容类型,如果没有会从文件扩展名猜测。

[disposition]
  用于 Content-Disposition可能的包括 +nil+ (默认),
  <tt>:attachment</tt> 和 <tt>:inline</tt>

[length]
  Content-Length 的值,默认是文件的大小。

如果Rack处理器支持Ruby进程除streaming以外的方式会被使用。
如果你使用这个辅助方法,
Sinatra会自动处理range请求。

=== 访问请求对象

传入的请求对象可以在请求层(过滤器,路由,错误处理)
通过 <tt>request</tt> 方法被访问:

  # 在 http://example.com/example 上运行的应用
  get '/foo' do
    request.body              # 被客户端设定的请求体(见下)
    request.scheme            # "http"
    request.script_name       # "/example"
    request.path_info         # "/foo"
    request.port              # 80
    request.request_method    # "GET"
    request.query_string      # ""
    request.content_length    # request.body的长度
    request.media_type        # request.body的媒体类型
    request.host              # "example.com"
    request.get?              # true (其他动词也具有类似方法)
    request.form_data?        # false
    request["SOME_HEADER"]    # SOME_HEADER header的值
    request.referrer          # 客户端的referrer 或者 '/'
    request.user_agent        # user agent (被 :agent 条件使用)
    request.cookies           # 浏览器 cookies 哈希
    request.xhr?              # 这是否是ajax请求
    request.url               # "http://example.com/example/foo"
    request.path              # "/example/foo"
    request.ip                # 客户端IP地址
    request.secure?           # false如果是ssl则为true
    request.forwarded?        # true (如果是运行在反向代理之后)
    request.env               # Rack中使用的未处理的env哈希
  end

一些选项,例如 <tt>script_name</tt> 或者 <tt>path_info</tt> 
也是可写的:

  before { request.path_info = "/" }
  
  get "/" do
    "all requests end up here"
  end

<tt>request.body</tt> 是一个IO或者StringIO对象

  post "/api" do
    request.body.rewind  # 如果已经有人读了它
    data = JSON.parse request.body.read
    "Hello #{data['name']}!"
  end

=== 附件

你可以使用 +attachment+ 辅助方法来告诉浏览器响应
应当被写入磁盘而不是在浏览器中显示。

  get '/' do
    attachment
    "store it!"
  end

你也可以传递一个文件名:

  get '/' do
    attachment "info.txt"
    "store it!"
  end

=== 查找模板文件

<tt>find_template</tt> 辅助方法被用于在渲染时查找模板文件:

  find_template settings.views, 'foo', Tilt[:haml] do |file|
    puts "could be #{file}"
  end

这并不是很有用。但是在你需要重载这个方法
来实现你自己的查找机制的时候有用。
比如,如果你想支持多于一个视图目录:

  set :views, ['views', 'templates']

  helpers do
    def find_template(views, name, engine, &block)
      Array(views).each { |v| super(v, name, engine, &block) }
    end
  end

另一个例子是为不同的引擎使用不同的目录:

  set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'

  helpers do
    def find_template(views, name, engine, &block)
      _, folder = views.detect { |k,v| engine == Tilt[k] }
      folder ||= views[:default]
      super(folder, name, engine, &block)
    end
  end

你可以很容易地包装成一个扩展然后与他人分享!

请注意 <tt>find_template</tt> 并不会检查文件真的存在,
而是对任何可能的路径调用给入的代码块。这并不会带来性能问题,
因为 +render+ 会在找到文件的时候马上使用 +break+ 。
同样的模板的路径和内容会在除development mode以外的场合
被缓存。你应该时刻提醒自己这一点,
如果你真的想写一个非常疯狂的方法。

== 配置

运行一次,在启动的时候,在任何环境下:

  configure do
    # setting one option
    set :option, 'value'
    
    # setting multiple options
    set :a => 1, :b => 2
    
    # same as `set :option, true`
    enable :option
    
    # same as `set :option, false`
    disable :option
    
    # you can also have dynamic settings with blocks
    set(:css_dir) { File.join(views, 'css') }
  end

只当环境 (RACK_ENV environment 变量) 被设定为
<tt>:production</tt>的时候运行:

  configure :production do
    ...
  end

当环境被设定为 <tt>:production</tt> 或者
<tt>:test</tt>的时候运行:

  configure :production, :test do
    ...
  end

你可以使用 <tt>settings</tt> 获得这些配置:

  configure do
    set :foo, 'bar'
  end

  get '/' do
    settings.foo? # => true
    settings.foo  # => 'bar'
    ...
  end

=== 可选的设置

[absolute_redirects]  如果被禁用Sinatra会允许使用相对路径重定向
                      但是Sinatra就不再遵守 RFC 2616标准
                      (HTTP 1.1), 该标准只允许绝对路径重定向。
                      
                      如果你的应用运行在一个未恰当设置的反向代理之后,
                      你需要启用这个选项。注意 +url+ 辅助方法
                      仍然会生成绝对 URL除非你传入
                      +false+ 作为第二参数。

                      默认禁用。

[add_charsets]        设定 <tt>content_type</tt> 辅助方法会
                      自动加上字符集信息的多媒体类型。

                      你应该添加而不是覆盖这个选项:

                        settings.add_charsets << "application/foobar"

[app_file]            主应用文件,用来检测项目的根路径,
                      views和public文件夹和内联模板。

[bind]                绑定的IP 地址 (默认: 0.0.0.0)。
                      仅对于内置的服务器有用。

[default_encoding]    默认编码
                      (默认为 <tt>"utf-8"</tt>)。

[dump_errors]         在log中显示错误。

[environment]         当前环境,默认是 <tt>ENV['RACK_ENV']</tt>
                      或者 <tt>"development"</tt> 如果不可用。

[logging]             使用logger

[lock]                对每一个请求放置一个锁,
                      只使用进程并发处理请求。

                      如果你的应用不是线程安全则需启动。
                      默认禁用。

[method_override]     使用 <tt>_method</tt> 魔法以允许在旧的浏览器中在
                      表单中使用 put/delete 方法

[port]                监听的端口号。只对内置服务器有用。

[prefixed_redirects]  是否添加 <tt>request.script_name</tt> 到
                      重定向请求,如果没有设定绝对路径。那样的话
                      <tt>redirect '/foo'</tt> 会和
                      <tt>redirect to('/foo')</tt>起相同作用。默认禁用。

[public]              public文件夹的位置。

[reload_templates]    是否每个请求都重新载入模板。
                      在development mode和 Ruby 1.8.6 中被企业(用来
                      消除一个Ruby内存泄漏的bug。

[root]                项目的根目录。

[raise_errors]        抛出异常(应用会停下)。

[run]                 如果启用Sinatra会开启web服务器。
                      如果使用rackup或其他方式则不要启用。

[running]             内置的服务器在运行吗?
                      不要修改这个设置!

[server]              服务器,或用于内置服务器的列表。
                      默认是 ['thin', 'mongrel', 'webrick'], 顺序表明了
                      优先级。

[sessions]            开启基于cookie的sesson。

[show_exceptions]     在浏览器中显示一个stack trace。

[static]              Sinatra是否处理静态文件。
                      当服务器能够处理则禁用。
                      禁用会增强性能。
                      默认开启。

[views]               views 文件夹。

== 错误处理

错误处理在与路由和前置过滤器相同的上下文中运行,
这意味着你可以使用许多好东西,比如 <tt>haml</tt>, <tt>erb</tt>,
<tt>halt</tt>,等等。

=== 未找到

当一个 <tt>Sinatra::NotFound</tt> 错误被抛出的时候,
或者响应状态码是404<tt>not_found</tt> 处理器会被调用:

  not_found do
    'This is nowhere to be found'
  end

=== 错误

+error+ 处理器,在任何路由代码块或者过滤器抛出异常的时候会被调用。 
异常对象可以通过<tt>sinatra.error</tt> Rack 变量获得:


  error do
    'Sorry there was a nasty error - ' + env['sinatra.error'].name
  end

自定义错误:

  error MyCustomError do
    'So what happened was...' + request.env['sinatra.error'].message
  end

那么,当这个发生的时候:

  get '/' do
    raise MyCustomError, 'something bad'
  end

你会得到:

  So what happened was... something bad

另一种替代方法是,为一个状态码安装错误处理器:

  error 403 do
    'Access forbidden'
  end

  get '/secret' do
    403
  end

或者一个范围:

  error 400..510 do
    'Boom'
  end

在运行在development环境下时Sinatra会安装特殊的
<tt>not_found</tt> 和 <tt>error</tt> 处理器。

== Rack 中间件

Sinatra 依靠 Rack[http://rack.rubyforge.org/], 
一个面向Ruby web框架的最小标准接口。
Rack的一个最有趣的面向应用开发者的能力是支持“中间件”——坐落在服务器和你的应用之间
监视 并/或 操作HTTP请求/响应以
提供多样类型的常用功能。

Sinatra 让建立Rack中间件管道异常简单
通过顶层的 +use+ 方法:

  require 'sinatra'
  require 'my_custom_middleware'

  use Rack::Lint
  use MyCustomMiddleware

  get '/hello' do
    'Hello World'
  end

+use+ 的语义和在 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] 
DSL(在rack文件中最频繁使用)中定义的完全一样。例如,+use+
方法接受 多个/可变 参数,包括代码块:

  use Rack::Auth::Basic do |username, password|
    username == 'admin' && password == 'secret'
  end

Rack中分布有多样的标准中间件针对日志
调试URL路由认证和session处理。
Sinatra会自动使用这里面的大部分组件
所以你一般不需要显示地 +use+ 他们。

== 测试

Sinatra的测试可以使用任何基于Rack的测试程序库或者框架来编写。
{Rack::Test}[http://gitrdoc.com/brynary/rack-test]
是推荐候选:

  require 'my_sinatra_app'
  require 'test/unit'
  require 'rack/test'

  class MyAppTest < Test::Unit::TestCase
    include Rack::Test::Methods

    def app
      Sinatra::Application
    end

    def test_my_default
      get '/'
      assert_equal 'Hello World!', last_response.body
    end

    def test_with_params
      get '/meet', :name => 'Frank'
      assert_equal 'Hello Frank!', last_response.body
    end

    def test_with_rack_env
      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
      assert_equal "You're using Songbird!", last_response.body
    end
  end

请注意: 内置的 Sinatra::Test 模块和 Sinatra::TestHarness 类
在 0.9.2 版本已废弃。

== Sinatra::Base - 中间件,程序库和模块化应用

把你的应用定义在顶层,对于微型应用这会工作得很好,
但是在构建可复用的组件时候会带来客观的不利,
比如构建Rack中间件Rails metal带有服务器组件的简单程序库
或者甚至是Sinatra扩展。顶层的DSL污染了Object命名空间
并假定了一个微型应用风格的配置 (例如, 单一的应用文件,
./public 和 ./views 目录,日志,异常细节页面,等等)。
这时应该让 Sinatra::Base 走到台前了:

  require 'sinatra/base'

  class MyApp < Sinatra::Base
    set :sessions, true
    set :foo, 'bar'

    get '/' do
      'Hello world!'
    end
  end

Sinatra::Base子类可用的方法实际上就是通过顶层 DSL
可用的方法。
大部分顶层应用可以通过两个改变转换成Sinatra::Base组件

* 你的文件应当引入 +sinatra/base+ 而不是 +sinatra+;
  否则所有的Sinatra的 DSL 方法将会被引进到
  主命名空间。
* 把你的应用的路由,错误处理,过滤器和选项放在
  一个Sinatra::Base的子类中。

<tt>+Sinatra::Base+</tt> 是一张白纸。大部分的选项默认是禁用的,
包含内置的服务器。参见 {选项和配置}[http://sinatra.github.com/configuration.html]
查看可用选项的具体细节和他们的行为。

=== 模块化 vs. 传统的方式

与通常的认识相反,传统的方式没有任何错误。
如果它适合你的应用,你不需要转换到模块化的应用。

和模块化方式相比只有两个缺点:

* 你对每个Ruby进程只能定义一个Sinatra应用如果你需要更多
  切换到模块化方式。

* 传统方式使用代理方法污染了 Object 。如果你打算
  把你的应用封装进一个 library/gem转换到模块化方式。

没有任何原因阻止你混合模块化和传统方式。

如果从一种转换到另一种你需要注意settings中的
一些微小的不同:

  Setting             Classic                 Modular

  app_file            file loading sinatra    nil
  run                 $0 == app_file          false
  logging             true                    false
  method_override     true                    false
  inline_templates    true                    false


=== 运行一个模块化应用

有两种方式运行一个模块化应用,使用
<tt>run!</tt>来运行:

  # my_app.rb
  require 'sinatra/base'
  
  class MyApp < Sinatra::Base
    # ... app code here ...
    
    # start the server if ruby file executed directly
    run! if app_file == $0
  end

运行:

  ruby my_app.rb

或者使用一个 <tt>config.ru</tt>允许你使用任何Rack处理器:

  # config.ru
  require 'my_app'
  run MyApp

运行:

  rackup -p 4567

=== 使用config.ru运行传统方式的应用

编写你的应用:

  # app.rb
  require 'sinatra'
  
  get '/' do
    'Hello world!'
  end

加入相应的 <tt>config.ru</tt>:

  require 'app'
  run Sinatra::Application

=== 什么时候用 config.ru?

以下情况你可能需要使用 <tt>config.ru</tt>:

* 你要使用不同的 Rack 处理器部署 (Passenger, Unicorn,
  Heroku, ...).
* 你想使用一个或者多个 <tt>Sinatra::Base</tt>的子类.
* 你只想把Sinatra当作中间件使用而不是端点。

<b>你并不需要切换到<tt>config.ru</tt>仅仅因为你切换到模块化方式,
你同样不需要切换到模块化方式,
仅仅因为要运行 <tt>config.ru</tt>.</b>

=== 把Sinatra当成中间件来使用

不仅Sinatra有能力使用其他的Rack中间件任何Sinatra
应用程序都可以反过来自身被当作中间件被加在任何Rack端点前面。
这个端点可以是任何Sinatra应用或者任何基于Rack的应用程序
(Rails/Ramaze/Camping/...)。

  require 'sinatra/base'
  
  class LoginScreen < Sinatra::Base
    enable :sessions
    
    get('/login') { haml :login }
    
    post('/login') do
      if params[:name] = 'admin' and params[:password] = 'admin'
        session['user_name'] = params[:name]
      else
        redirect '/login'
      end
    end
  end
  
  class MyApp < Sinatra::Base
    # 在前置过滤器前运行中间件
    use LoginScreen
    
    before do
      unless session['user_name']
        halt "Access denied, please <a href='/login'>login</a>."
      end
    end
    
    get('/') { "Hello #{session['user_name']}." }
  end

== 变量域和绑定

当前所在的变量域决定了哪些方法和变量是可用的。


=== 应用/类 变量域

每个Sinatra应用相当与Sinatra::Base的一个子类。
如果你在使用顶层DSL(<tt>require 'sinatra'</tt>),那么这个类就是
Sinatra::Application或者这个类就是你显式创建的子类。
在类层面,你具有的方法类似于 `get` 或者 `before`,但是你不能访问
`request` 对象或者 `session`, 因为对于所有的请求,
只有单一的应用类。

通过 `set` 创建的选项是类层面的方法:

    class MyApp < Sinatra::Base
      # 嘿,我在应用变量域!
      set :foo, 42
      foo # => 42
      
      get '/foo' do
        # 嘿,我不再处于应用变量域了!
      end
    end

在下列情况下你将拥有应用变量域的绑定:

* 在应用类中
* 在扩展中定义的方法
* 传递给 `helpers` 的代码块
* 用作`set`值的过程/代码块

你可以访问变量域对象(就是应用类)就像这样:

* 通过传递给代码块的对象 (<tt>configure { |c| ... }</tt>)
* 在请求变量域中使用`settings`

=== 请求/实例 变量域

对于每个进入的请求,一个新的应用类的实例会被创建
所有的处理器代码块在该变量域被运行。在这个变量域中,
你可以访问 `request` 和 `session` 对象,或者调用渲染方法比如
`erb` 或者 `haml`。你可以在请求变量域当中通过`settings`辅助方法
访问应用变量域:

  class MyApp < Sinatra::Base
    # 嘿,我在应用变量域!
    get '/define_route/:name' do
      # 针对 '/define_route/:name' 的请求变量域
      @value = 42
      
      settings.get("/#{params[:name]}") do
        # 针对 "/#{params[:name]}" 的请求变量域
        @value # => nil (并不是相同的请求)
      end
      
      "Route defined!"
    end
  end

在以下情况将获得请求变量域:

* get/head/post/put/delete 代码块
* 前置/后置 过滤器
* 辅助方法
* 模板/视图

=== 代理变量域

代理变量域只是把方法转送到类变量域。可是,
他并非表现得100%类似于类变量域, 因为你并不能获得类的绑定: 
只有显式地标记为供代理使用的方法才是可用的,
而且你不能和类变量域共享变量/状态。(解释:你有了一个不同的
`self`)。 你可以显式地增加方法代理,通过调用
<tt>Sinatra::Delegator.delegate :method_name</tt>。

在以下情况将获得代理变量域:

* 顶层的绑定,如果你做过 <tt>require "sinatra"</tt>
* 在扩展了 `Sinatra::Delegator` mixin的对象

自己在这里看一下代码: 
{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
已经 {被包含进了主命名空间}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]。

== 命令行

Sinatra 应用可以被直接运行:

  ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]

选项是:

  -h # help
  -p # 设定端口 (默认是 4567)
  -o # 设定主机名 (默认是 0.0.0.0)
  -e # 设定环境 (默认是 development)
  -s # 限定 rack 服务器/处理器 (默认是 thin)
  -x # 打开互斥锁 (默认是 off)

== 必要条件

推荐在 Ruby 1.8.7, 1.9.2, JRuby 或者 Rubinius 上安装Sinatra。

下面的Ruby版本是官方支持的:

[ Ruby 1.8.6 ]
  不推荐在1.8.6上安装Sinatra
  但是直到Sinatra 1.3.0发布才会放弃对它的支持。
  RDoc 和 CoffeScript模板不被这个Ruby版本支持。
  1.8.6在它的Hash实现中包含一个内存泄漏问题
  该问题会被1.1.1版本之前的Sinatra引发。
  当前版本使用性能下降的代价排除了这个问题。你需要把Rack降级到1.1.x
  因为Rack >= 1.2不再支持1.8.6。

[ Ruby 1.8.7 ]
  1.8.7 被完全支持,但是,如果没有特别原因,
  我们推荐你升级到 1.9.2 或者切换到 JRuby 或者 Rubinius.

[ Ruby 1.9.2 ]
  1.9.2 被支持而且推荐。注意 Radius 和 Markaby
  模板并不和1.9兼容。不要使用 1.9.2p0, 它被已知会产生
  segmentation faults.

[ Rubinius ]
  Rubinius 被官方支持 (Rubinius >= 1.2.2)
  除了Textile模板。

[ JRuby ]
  JRuby 被官方支持 (JRuby >= 1.5.6)。
  目前未知和第三方模板库有关的问题,
  但是如果你选择了JRuby请查看一下JRuby rack 处理器,
  因为 Thin web 服务器还没有在JRuby上获得支持。

我们也会时刻关注新的Ruby版本。

下面的 Ruby 实现没有被官方支持,
但是已知可以运行 Sinatra:

* JRuby 和 Rubinius 老版本
* MacRuby
* Maglev
* IronRuby
* Ruby 1.9.0 and 1.9.1

不被官方支持的意思是,如果在不被支持的平台上有运行错误,
我们假定不是我们的问题,而是平台的问题。

Sinatra应该会运行在任何支持上述Ruby实现的操作系统。


== 紧追前沿

如果你喜欢使用 Sinatra 的最新鲜的代码,请放心的使用 master
分支来运行你的程序,它会非常的稳定。
  cd myapp
  git clone git://github.com/sinatra/sinatra.git
  ruby -Isinatra/lib myapp.rb

我们也会不定期的发布预发布gems所以你也可以运行

  gem install sinatra --pre

来获得最新的特性。

=== 通过Bundler
如果你想使用最新的Sinatra运行你的应用通过
{Bundler}[http://gembundler.com/] 是推荐的方式。

首先安装bundler如果你还没有安装:

  gem install bundler

然后,在你的项目目录下,创建一个 +Gemfile+:

  source :rubygems
  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
  
  # 其他的依赖关系
  gem 'haml'                    # 举例如果你想用haml
  gem 'activerecord', '~> 3.0'  # 也许你还需要 ActiveRecord 3.x

请注意在这里你需要列出你的应用的所有依赖关系。
Sinatra的直接依赖关系 (Rack and Tilt) 将会,
自动被Bundler获取和添加。

现在你可以像这样运行你的应用:

  bundle exec ruby myapp.rb

=== 使用自己的
创建一个本地克隆并通过 <tt>sinatra/lib</tt> 目录运行你的应用,
通过 <tt>$LOAD_PATH</tt>:

  cd myapp
  git clone git://github.com/sinatra/sinatra.git
  ruby -Isinatra/lib myapp.rb

为了在未来更新 Sinatra 源代码:

  cd myapp/sinatra
  git pull

=== 全局安装

你可以自行编译 gem :


  git clone git://github.com/sinatra/sinatra.git
  cd sinatra
  rake sinatra.gemspec
  rake install

如果你以root身份安装 gems最后一步应该是

  sudo rake install

== 更多

* {项目主页(英文)}[http://www.sinatrarb.com/] - 更多的文档,
  新闻,和其他资源的链接。
* {贡献}[http://www.sinatrarb.com/contributing] - 找到了一个bug
  需要帮助?有了一个 patch?
* {问题追踪}[http://github.com/sinatra/sinatra/issues]
* {Twitter}[http://twitter.com/sinatra]
* {邮件列表}[http://groups.google.com/group/sinatrarb/topics]
* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net