sinatra 1.4.0.c → 1.4.0.d

data/README.pt-pt.rdoc

@@ -1,647 +0,0 @@
-= Sinatra
-<i>Atenção: Este documento é apenas uma tradução da versão em inglês e pode estar desatualizado.</i>
-
-Sinatra é uma
-{DSL}[http://pt.wikipedia.org/wiki/Linguagem_de_domínio_específico]
-para criar rapidamente aplicações web em Ruby com o mínimo de esforço:
-
-  # minhaapp.rb
-  require 'rubygems'
-  require 'sinatra'
-  get '/' do
-    'Olá Mundo!'
-  end
-
-Instale a gem e execute com:
-
-  sudo gem install sinatra
-  ruby minhaapp.rb
-
-Aceda em: http://localhost:4567
-
-== Rotas
-
-No Sinatra, uma rota é um metodo HTTP associado a uma URL correspondente padrão.
-Cada rota é associada a um bloco:
-
-  get '/' do
-    .. mostrar algo ..
-  end
-
-  post '/' do
-    .. criar algo ..
-  end
-
-  put '/' do
-    .. atualizar algo ..
-  end
-
-  delete '/' do
-    .. apagar algo ..
-  end
-
-Rotas são encontradas na ordem em que são definidas. A primeira rota que
-é encontrada invoca o pedido.
-
-Padrões de rota podem incluir parâmetros nomeados, acessíveis através da
-hash <tt>params</tt>:
-
-  get '/ola/:nome' do
-    # corresponde a "GET /ola/foo" e "GET /ola/bar"
-    # params[:nome] é 'foo' ou 'bar'
-    "Olá #{params[:nome]}!"
-  end
-
-Pode também aceder a parâmetros nomeados através do bloco de parâmetros:
-
-  get '/ola/:nome' do |n|
-    "Olá #{n}!"
-  end
-
-Padrões de rota podem também incluir parâmetros splat (asteriscos), acessíveis
-através do array <tt>params[:splat]</tt>.
-
-  get '/diga/*/ao/*' do
-    # corresponde a /diga/ola/ao/mundo
-    params[:splat] # => ["ola", "mundo"]
-  end
-
-  get '/download/*.*' do
-    # corresponde a /download/pasta/do/arquivo.xml
-    params[:splat] # => ["pasta/do/arquivo", "xml"]
-  end
-
-Rotas correspondem-se com expressões regulares:
-
-  get %r{/ola/([\w]+)} do
-    "Olá, #{params[:captures].first}!"
-  end
-
-Ou com um bloco de parâmetro:
-
-  get %r{/ola/([\w]+)} do |c|
-    "Olá, #{c}!"
-  end
-
-Rotas podem incluir uma variedade de condições correspondentes, por exemplo, o agente usuário:
-
-  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
-    "Você está a utilizar a versão #{params[:agent][0]} do Songbird."
-  end
-
-  get '/foo' do
-    # Corresponde a um navegador não Songbird
-  end
-
-== Arquivos estáticos
-
-Arquivos estáticos são disponibilizados a partir do directório <tt>./public</tt>. Você pode especificar
-um local diferente através da opção <tt>:public_folder</tt>
-
-  set :public_folder, File.dirname(__FILE__) + '/estatico'
-
-Note que o nome do directório público não é incluido no URL. Um arquivo
-<tt>./public/css/style.css</tt> é disponibilizado como
-<tt>http://example.com/css/style.css</tt>.
-
-== Views / Templates
-
-Templates presumem-se estar localizados sob o directório <tt>./views</tt>.
-Para utilizar um directório de views diferente:
-
-  set :views, File.dirname(__FILE__) + '/modelo'
-
-Uma coisa importante a ser lembrada é que você sempre tem as referências dos
-templates como símbolos, mesmo se eles estiverem num sub-directório (nesse
-caso utilize <tt>:'subdir/template'</tt>). Métodos de renderização irão processar
-qualquer string passada directamente para elas.
-
-=== Haml Templates
-
-A gem/biblioteca haml é necessária para renderizar templates HAML:
-
-  # É necessário requerir 'haml' na aplicação.
-  require 'haml'
-
-  get '/' do
-    haml :index
-  end
-
-Renderiza <tt>./views/index.haml</tt>.
-
-{Opções Haml}[http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options]
-podem ser definidas globalmente através das configurações do sinatra,
-veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
-e substitua em uma requisição individual.
-
-  set :haml, {:format => :html5 } # o formato padrão do Haml é :xhtml
-
-  get '/' do
-    haml :index, :haml_options => {:format => :html4 } # substituido
-  end
-
-
-=== Erb Templates
-
-  # É necessário requerir 'erb' na aplicação.
-  require 'erb'
-
-  get '/' do
-    erb :index
-  end
-
-Renderiza <tt>./views/index.erb</tt>
-
-=== Erubis
-
-A gem/biblioteca erubis é necessária para renderizar templates erubis:
-
-  # É necessário requerir 'erubis' na aplicação.
-  require 'erubis'
-
-  get '/' do
-    erubis :index
-  end
-
-Renderiza <tt>./views/index.erubis</tt>
-
-=== Builder Templates
-
-A gem/biblioteca builder é necessária para renderizar templates builder:
-
-  # É necessário requerir 'builder' na aplicação.
-  require 'builder'
-
-  get '/' do
-    content_type 'application/xml', :charset => 'utf-8'
-    builder :index
-  end
-
-Renderiza <tt>./views/index.builder</tt>.
-
-=== Sass Templates
-
-A gem/biblioteca sass é necessária para renderizar templates sass:
-
-  # É necessário requerir 'haml' ou 'sass' na aplicação.
-  require 'sass'
-
-  get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
-    sass :stylesheet
-  end
-
-Renderiza <tt>./views/stylesheet.sass</tt>.
-
-{Opções Sass}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options]
-podem ser definidas globalmente através das configurações do sinatra,
-veja {Opções e Configurações}[http://www.sinatrarb.com/configuration.html],
-e substitua em uma requisição individual.
-
-  set :sass, {:style => :compact } # o estilo padrão do Sass é :nested
-
-  get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
-    sass :stylesheet, :style => :expanded # substituido
-  end
-
-=== Less Templates
-
-A gem/biblioteca less é necessária para renderizar templates Less:
-
-  # É necessário requerir 'less' na aplicação.
-  require 'less'
-
-  get '/stylesheet.css' do
-    content_type 'text/css', :charset => 'utf-8'
-    less :stylesheet
-  end
-
-Renderiza <tt>./views/stylesheet.less</tt>.
-
-=== Templates Inline
-
-  get '/' do
-    haml '%div.title Olá Mundo'
-  end
-
-Renderiza a string, em uma linha, no template.
-
-=== Acedendo a Variáveis nos Templates
-
-Templates são avaliados dentro do mesmo contexto que os manipuladores de rota. Variáveis
-de instância definidas em rotas manipuladas são directamente acedidas por templates:
-
-  get '/:id' do
-    @foo = Foo.find(params[:id])
-    haml '%h1= @foo.nome'
-  end
-
-Ou, especifique um hash explícito para variáveis locais:
-
-  get '/:id' do
-    foo = Foo.find(params[:id])
-    haml '%h1= foo.nome', :locals => { :foo => foo }
-  end
-
-Isso é tipicamente utilizado quando renderizamos templates parciais (partials) dentro
-de outros templates.
-
-=== Templates Inline
-
-Templates podem ser definidos no final do arquivo fonte(.rb):
-
-  require 'rubygems'
-  require 'sinatra'
-
-  get '/' do
-    haml :index
-  end
-
-  __END__
-
-  @@ layout
-  %html
-    = yield
-
-  @@ index
-  %div.title Olá Mundo!!!!!
-
-NOTA: Templates inline definidos no arquivo fonte são automaticamente carregados
-pelo sinatra. Digite `enable :inline_templates` se tem templates inline no outro 
-arquivo fonte.
-
-=== Templates nomeados
-
-Templates também podem ser definidos utilizando o  método top-level <tt>template</tt>:
-
-  template :layout do
-    "%html\n  =yield\n"
-  end
-
-  template :index do
-    '%div.title Olá Mundo!'
-  end
-
-  get '/' do
-    haml :index
-  end
-
-Se existir um template com nome "layout", ele será utilizado sempre que um
-template for renderizado. Pode desactivar layouts usando <tt>:layout => false</tt>.
-
-  get '/' do
-    haml :index, :layout => !request.xhr?
-  end
-
-== Helpers
-
-Use o método de alto nível <tt>helpers</tt> para definir métodos auxiliares para utilizar em
-manipuladores de rotas e modelos:
-
-  helpers do
-    def bar(nome)
-      "#{nome}bar"
-    end
-  end
-
-  get '/:nome' do
-    bar(params[:nome])
-  end
-
-== Filtros
-
-Filtros Before são avaliados antes de cada requisição dentro do contexto da requisição
-e podem modificar a requisição e a reposta. Variáveis de instância definidas nos
-filtros são acedidas através de rotas e templates:
-
-  before do
-    @nota = 'Olá!'
-    request.path_info = '/foo/bar/baz'
-  end
-
-  get '/foo/*' do
-    @nota #=> 'Olá!'
-    params[:splat] #=> 'bar/baz'
-  end
-
-Filtros After são avaliados após cada requisição dentro do contexto da
-requisição e também podem modificar o pedido e a resposta. Variáveis de instância
-definidas nos filtros before e rotas são acedidas através dos filtros after:
-
-  after do
-    puts response.status
-  end
-
-Filtros opcionalmente têm um padrão, fazendo com que sejam avaliados somente se o caminho
-do pedido coincidir com esse padrão:
-
-  before '/protected/*' do
-    autenticar!
-  end
-
-  after '/create/:slug' do |slug|
-    session[:last_slug] = slug
-  end
-
-== Halting
-
-Para parar imediatamente uma requisição dentro de um filtro ou rota utilize:
-
-  halt
-
-Pode também especificar o status ao parar...
-
-  halt 410
-
-Ou com um corpo de texto...
-
-  halt 'isto será o corpo de texto'
-
-Ou também...
-
-  halt 401, 'vamos embora!'
-
-Com cabeçalhos...
-
-  halt 402, {'Content-Type' => 'text/plain'}, 'revanche'
-
-== Passing
-
-Dentro de uma rota, pode passar para a próxima rota correspondente usando <tt>pass</tt>:
-
-  get '/adivinhar/:quem' do
-    pass unless params[:quem] == 'Frank'
-    'Apanhaste-me!'
-  end
-
-  get '/adivinhar/*' do
-    'Falhaste!'
-  end
-
-O bloqueio da rota é imediatamente encerrado e o controle continua com a próxima
-rota de parâmetro. Se o parâmetro da rota não for encontrado, um 404 é retornado.
-
-== Configuração
-
-Correndo uma vez, na inicialização, em qualquer ambiente:
-
-  configure do
-    ...
-  end
-
-Correndo somente quando o ambiente (RACK_ENV environment variável) é definido para
-<tt>:production</tt>:
-
-  configure :production do
-    ...
-  end
-
-Correndo quando o ambiente é definido para <tt>:production</tt> ou
-<tt>:test</tt>:
-
-  configure :production, :test do
-    ...
-  end
-
-== Lidar com Erros
-
-Lida-se com erros no mesmo contexto das rotas e filtros before, o que signifca que
-<tt>haml</tt>, <tt>erb</tt>, etc, estão disponíveis.
-
-=== Não Encontrado
-
-Quando um <tt>Sinatra::NotFound</tt> exception é levantado, ou o código de status
-da reposta é 404, o manipulador <tt>not_found</tt> é invocado:
-
-  not_found do
-    'Isto está longe de ser encontrado'
-  end
-
-=== Erro
-
-O manipulador +error+ é invocado sempre que uma exceção é lançada a partir de
-um bloco de rota ou um filtro. O objecto da exceção pode ser obtido a partir da variável
-Rack <tt>sinatra.error</tt>:
-
-  error do
-    'Peço desculpa, houve um erro desagradável - ' + env['sinatra.error'].name
-  end
-
-Erros personalizados:
-
-  error MeuErroPersonalizado do
-    'O que aconteceu foi...' + env['sinatra.error'].message
-  end
-
-Então, se isso acontecer:
-
-  get '/' do
-    raise MeuErroPersonalizado, 'alguma coisa desagradável'
-  end
-
-O resultado será:
-
-  O que aconteceu foi...alguma coisa desagradável
-
-Alternativamente, pode definir um manipulador de erro para um código de status:
-
-  error 403 do
-    'Accesso negado'
-  end
-
-  get '/secreto' do
-    403
-  end
-
-Ou um range (alcance):
-
-  error 400..510 do
-    'Boom'
-  end
-
-O Sinatra define os manipuladores especiais <tt>not_found</tt> e <tt>error</tt> quando
-corre no ambiente de desenvolvimento.
-
-== Mime Types
-
-Quando utilizamos <tt>send_file</tt> ou arquivos estáticos pode ter mime types Sinatra
-não entendidos. Use +mime_type+ para os registar por extensão de arquivos:
-
-  mime_type :foo, 'text/foo'
-
-Pode também utilizar isto com o helper +content_type+:
-
-  content_type :foo
-
-== Middleware Rack
-
-O Sinatra corre no Rack[http://rack.rubyforge.org/], uma interface padrão mínima para
-frameworks web em Ruby. Uma das capacidades mais interessantes do Rack, para desenvolver
-aplicações, é o suporte de "middleware" -- componentes que residem entre o servidor e
-a aplicação, monitorizando e/ou manipulando o pedido/resposta (request/response) HTTP
-para providenciar varios tipos de funcionalidades comuns.
-
-O Sinatra torna a construção de pipelines do middleware Rack fácil a um nível superior
-utilizando o método +use+:
-
-  require 'sinatra'
-  require 'meu_middleware_personalizado'
-
-  use Rack::Lint
-  use MeuMiddlewarePersonalizado
-
-  get '/ola' do
-    'Olá mundo'
-  end
-
-A semântica de +use+ é idêntica aquela definida para a DSL
-Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html]
-(mais frequentemente utilizada para arquivos rackup). Por exemplo, o método +use+
-aceita múltiplos argumentos/variáveis, bem como blocos:
-
-  use Rack::Auth::Basic do |utilizador, senha|
-    utilizador == 'admin' && senha == 'secreto'
-  end
-
-O Rack é distribuido com uma variedade de middleware padrões para logs,
-debugs, rotas de URL, autenticação, e manipuladores de sessão.Sinatra utiliza 
-muitos desses componentes automaticamente dependendo da configuração, por isso, 
-tipicamente nao é necessário utilizar +use+ explicitamente.
-
-== Testando
-
-Testes no Sinatra podem ser escritos utilizando qualquer biblioteca ou framework
-de teste baseados no Rack. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] é
-recomendado:
-
-  require 'minha_aplicacao_sinatra'
-  require 'rack/test'
-
-  class MinhaAplicacaoTeste < Test::Unit::TestCase
-    include Rack::Test::Methods
-
-    def app
-      Sinatra::Application
-    end
-
-    def meu_test_default
-      get '/'
-      assert_equal 'Ola Mundo!', last_response.body
-    end
-
-    def teste_com_parametros
-      get '/atender', :name => 'Frank'
-      assert_equal 'Olá Frank!', last_response.bodymeet
-    end
-
-    def test_com_ambiente_rack
-      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
-      assert_equal "Você está utilizando o Songbird!", last_response.body
-    end
-  end
-
-NOTA: Os módulos de classe embutidos Sinatra::Test e Sinatra::TestHarness
-são depreciados na versão 0.9.2.
-
-== Sinatra::Base - Middleware, Bibliotecas e aplicativos modulares
-
-Definir sua aplicação a um nível superior de trabalho funciona bem para micro aplicativos, mas tem
-consideráveis incovenientes na construção de componentes reutilizáveis como um middleware Rack,
-metal Rails, bibliotecas simples como um componente de servidor, ou
-mesmo extensões Sinatra. A DSL de nível superior polui o espaço do objeto
-e assume um estilo de configuração de micro aplicativos (exemplo: um simples arquivo de
-aplicação, directórios ./public e ./views, logs, página de detalhes de excepção,
-etc.). É onde o Sinatra::Base entra em jogo:
-
-  require 'sinatra/base'
-
-  class MinhaApp < Sinatra::Base
-    set :sessions, true
-    set :foo, 'bar'
-
-    get '/' do
-      'Olá mundo!'
-    end
-  end
-
-A classe MinhaApp é um componente Rack independente que pode utilizar como um
-middleware Rack, uma aplicação Rack, ou metal Rails. Pode +utilizar+ ou
-+executar+ esta classe com um arquivo rackup +config.ru+; ou, controlar um componente
-de servidor fornecendo como biblioteca:
-
-   MinhaApp.run! :host => 'localhost', :port => 9090
-
-Os métodos disponíveis para subclasses Sinatra::Base são exatamente como aqueles
-disponíveis via a DSL de nível superior. Aplicações de nível mais alto podem ser convertidas para
-componentes Sinatra::Base com duas modificações:
-
-* Seu arquivo deve requerer +sinatra/base+  ao invés de +sinatra+;
-  outra coisa, todos os métodos DSL do Sinatra são importados para o espaço
-  principal.
-* Coloque as rotas da sua aplicação, manipuladores de erro, filtros e opções na subclasse de
-  um Sinatra::Base.
-
-+Sinatra::Base+ é um quadro branco. Muitas opções são desactivadas por padrão,
-incluindo o servidor embutido. Veja {Opções e Configurações}[http://sinatra.github.com/configuration.html]
-para detalhes de opções disponíveis e seus comportamentos.
-
-SIDEBAR: A DSL de alto nível do Sinatra é implementada utilizando um simples sistema de
-delegação. A classe +Sinatra::Application+ -- uma subclasse especial da
-Sinatra::Base -- recebe todos os :get, :put, :post, :delete, :before,
-:error, :not_found, :configure, e :set messages enviados para o
-alto nível. Dê você mesmo uma vista de olhos ao código: aqui está o
-{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
-sendo {incluido dentro de um espaço principal}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]
-
-== Linha de Comandos
-
-As aplicações Sinatra podem ser executadas directamente:
-
-  ruby minhaapp.rb [-h] [-x] [-e AMBIENTE] [-p PORTA] [-o HOST] [-s SERVIDOR]
-
-As opções são:
-
-  -h # ajuda
-  -p # define a porta (padrão é 4567)
-  -o # define o host (padrão é 0.0.0.0)
-  -e # define o ambiente (padrão é development)
-  -s # especifica o servidor/manipulador rack (padrão é thin)
-  -x # activa o bloqueio (padrão é desligado)
-
-== A última versão
-
-Se gostaria de utilizar o código da última versão do Sinatra, crie um clone
-local e execute sua aplicação com o directório <tt>sinatra/lib</tt> no
-<tt>LOAD_PATH</tt>:
-
-  cd minhaapp
-  git clone git://github.com/sinatra/sinatra.git
-  ruby -I sinatra/lib minhaapp.rb
-
-Alternativamente, pode adicionar o directório do <tt>sinatra/lib</tt> no
-<tt>LOAD_PATH</tt> do seu aplicativo:
-
-  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
-  require 'rubygems'
-  require 'sinatra'
-
-  get '/sobre' do
-    "Estou correndo a versão" + Sinatra::VERSION
-  end
-
-Para actualizar o código do Sinatra no futuro:
-
-  cd meuprojeto/sinatra
-  git pull
-
-== Mais
-
-* {Website do Projeto}[http://www.sinatrarb.com/] - Documentação adicional,
-  novidades e links para outros recursos.
-* {Contribuir}[http://www.sinatrarb.com/contributing] - Encontrou um bug? Precisa
-  de ajuda? Tem um patch?
-* {Acompanhar Questões}[http://github.com/sinatra/sinatra/issues]
-* {Twitter}[http://twitter.com/sinatra]
-* {Lista de Email}[http://groups.google.com/group/sinatrarb/topics]
-* {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] em http://freenode.net