sinatra 1.2.0.c → 1.2.0.d

data/AUTHORS

@@ -36,8 +36,17 @@ Sinatra would not be possible:
 * Rick Olson (technoweenie) for the killer plug at RailsConf '08.
 * Steven Garcia for the amazing custom artwork you see on 404's and 500's
 * Pat Nakajima (nakajima) for fixing non-nested params in nested params Hash's.
-* Konstantin Haase for his hard work and ongoing commitment to improving 
+* Konstantin Haase for his hard work and ongoing commitment to improving
   Sinatra, for 1.1.0, 1.2.0 and beyond..
+* Zachary Scott for adding Konstantin to the AUTHORS file. He also did help
+  writing the book, but mainly for adding Konstantin.
+* Gabriel Andretta for having people wonder whether our documentation is
+  actually in English or in Spanish.
+* Vasily Polovnyov, Nickolay Schwarz, Luciano Sousa, Wu Jiang, Mickael Riga,
+  Bernhard Essl, Janos Hardi, Kouhei Yanagita and "burningTyger" for willingly
+  translating whatever ends up in the README.
+* [Wordy](http://www.wordy.com/) for proofreading our README. 73e137d
+* cactus for digging through code and specs, multiple times.
 
 and last but not least:
 

data/Gemfile

@@ -4,9 +4,11 @@
 # development dependencies of our dependencies, and those are not conflict free.
 # So, here we are, `bundle install`.
 #
-# If you have issues with on gem: `bundle install --without-coffee-script`.
+# If you have issues with a gem: `bundle install --without-coffee-script`.
 
-source :rubygems
+RUBY_ENGINE = 'ruby' unless defined? RUBY_ENGINE
+
+source :rubygems unless ENV['QUICK']
 gemspec
 
 gem 'rake'
@@ -17,12 +19,16 @@ gem 'builder', :group => 'builder'
 gem 'erubis', :group => 'erubis'
 gem 'less', :group => 'less'
 gem 'liquid', :group => 'liquid'
-gem 'RedCloth', :group => 'redcloth'
-gem 'rdoc', :group => 'rdoc'
 gem 'nokogiri', :group => 'nokogiri'
 gem 'slim', :group => 'slim'
 
-gem 'coffee-script', '>= 2.0', :group => 'coffee-script'
+
+if RUBY_VERSION > '1.8.6'
+  gem 'coffee-script', '>= 2.0', :group => 'coffee-script'
+  gem 'rdoc', :group => 'rdoc'
+else
+  gem 'rack', '~> 1.1.0'
+end
 
 platforms :ruby do
   gem 'rdiscount', :group => 'rdiscount'
@@ -32,4 +38,16 @@ platforms :ruby_18, :jruby do
   gem 'json', :group => 'coffee-script'
   gem 'markaby', :group => 'markaby'
   gem 'radius', :group => 'radius'
-end
+end
+
+platforms :mri do
+  # bundler platforms are broken
+  next unless RUBY_ENGINE == 'ruby'
+  gem 'RedCloth', :group => 'redcloth'
+end
+
+platforms :mri_18 do
+  # bundler platforms are broken
+  next unless RUBY_ENGINE == 'ruby'
+  gem 'rcov', :group => 'rcov'
+end

data/README.de.rdoc

@@ -1,5 +1,6 @@
 = Sinatra
-<i>Wichtig: Dieses Dokument ist eine Übersetzung aus dem Englischen und unter Umständen nicht auf dem aktuellsten Stand.</i>
+<i>Wichtig: Dieses Dokument ist eine Übersetzung aus dem Englischen und unter
+Umständen nicht auf dem aktuellsten Stand.</i>
 
 Sinatra ist eine DSL, die das schnelle Erstellen von Webanwendungen in Ruby
 mit minimalen Aufwand ermöglicht:
@@ -10,7 +11,7 @@ mit minimalen Aufwand ermöglicht:
     'Hallo Welt!'
   end
 
-Einfach via rubygems installieren und starten:
+Einfach via +rubygems+ installieren und starten:
 
   gem install sinatra
   ruby -rubygems myapp.rb
@@ -19,8 +20,8 @@ Die Seite kann nun unter http://localhost:4567 betrachtet werden.
 
 == Routen
 
-In Sinatra wird eine Route durch eine HTTP-Methode und ein URL-Muster definiert. Jeder dieser Routen wird ein
-Ruby-Block zugeordnet.
+In Sinatra wird eine Route durch eine HTTP-Methode und ein URL-Muster
+definiert. Jeder dieser Routen wird ein Ruby-Block zugeordnet.
 
   get '/' do
     .. zeige etwas ..
@@ -37,6 +38,10 @@ Ruby-Block zugeordnet.
   delete '/' do
     .. entferne etwas ..
   end
+  
+  options '/' do
+    .. lege etwas fest ..
+  end
 
 Die Routen werden in der Reihenfolge durchlaufen, in der sie definiert wurden.
 Das erste Routemuster, das mit dem Request übereinstimmt, wird ausgeführt.
@@ -126,16 +131,19 @@ Man kann auch relativ einfach eigene Bedingungen hinzufügen:
 Durch den Rückgabewert eines Routenblocks wird mindestens der Response Body
 festgelegt, der an den HTTP Client, bzw die nächste Rack Middleware
 weitergegeben wird. Im Normalfall handelt es sich hierbei, wie
-in den vorangehenden Beispielen zu sehen war, um einen String. Es werden allerdings auch andere
-Werte akzeptiert.
+in den vorangehenden Beispielen zu sehen war, um einen String. Es werden
+allerdings auch andere Werte akzeptiert.
 
 Man kann jedes Objekt zurückgeben, bei dem es sich entweder um einenen validen
 Rack-Rückgabewert, einen validen Rack-Body oder einen HTTP Status Code
 handelt:
 
-* Ein Array mit drei Elementen: <tt>[Status (Fixnum), Headers (Hash), Response Body (hört auf #each)]</tt>
-* Ein Array mit zwei Elementen: <tt>[Status (Fixnum), Response Body (hört auf #each)]</tt>
-* Ein Objekt, das auf <tt>#each</tt> hört und den an diese Methode übergebenen Block nur mit Strings als Übergabewerte aufruft.
+* Ein Array mit drei Elementen: <tt>[Status (Fixnum), Headers (Hash), Response
+  Body (hört auf #each)]</tt>
+* Ein Array mit zwei Elementen: <tt>[Status (Fixnum), Response Body (hört auf
+  #each)]</tt>
+* Ein Objekt, das auf <tt>#each</tt> hört und den an diese Methode übergebenen
+  Block nur mit Strings als Übergabewerte aufruft.
 * Ein Fixnum, das den Status Code festlegt.
 
 Damit lässt sich relativ einfach Streaming implementieren:
@@ -175,7 +183,7 @@ Renderingmethoden rendern jeden String direkt.
 
 === Haml-Templates
 
-Das haml gem wird benötigt, um Haml-Templates rendern zu können:
+Das +haml+ gem wird benötigt, um Haml-Templates rendern zu können:
 
   # haml muss eingebunden werden
   require 'haml'
@@ -210,7 +218,7 @@ Dieser Code rendert <tt>./views/index.erb</tt>.
 
 === Erubis
 
-Das erubis gem wird benötigt, um Erubis-Templates rendern zu können:
+Das +erubis+ gem wird benötigt, um Erubis-Templates rendern zu können:
 
   # erbubis muss eingebunden werden
   require 'erubis'
@@ -221,9 +229,20 @@ Das erubis gem wird benötigt, um Erubis-Templates rendern zu können:
 
 Dieser Code rendert <tt>./views/index.erubis</tt>.
 
+Es ist auch möglich Erb mit Erubis zu ersetzen:
+
+  require 'erubis'
+  Tilt.register :erb, Tilt[:erubis]
+  
+  get '/' do
+    erb :index
+  end
+
+Dieser Code rendert ebenfalls <tt>./views/index.erb</tt>.
+
 === Builder-Templates
 
-Das buidler gem wird benötigt, um Builder-Templates rendern zu können:
+Das +builder+ gem wird benötigt, um Builder-Templates rendern zu können:
 
   # builder muss eingebunden werden
   require 'builder'
@@ -236,7 +255,7 @@ Dieser Code rendert <tt>./views/index.builder</tt>.
 
 === Nokogiri-Templates
 
-Das nokogiri gem wird benötigt, um Nokogiri-Templates rendern zu können:
+Das +nokogiri+ gem wird benötigt, um Nokogiri-Templates rendern zu können:
 
   # nokogiri muss eingebunden werden
   require 'nokogiri'
@@ -249,7 +268,7 @@ Dieser Code rendert <tt>./views/index.nokogiri</tt>.
 
 === Sass-Templates
 
-Das haml gem wird benötigt, um SASS-Templates rendern zu können:
+Das +haml+ oder +sass+ gem wird benötigt, um Sass-Templates rendern zu können:
 
   # sass muss eingebunden werden
   require 'sass'
@@ -273,7 +292,7 @@ und individuell überschrieben werden.
 
 === Scss-Templates
 
-Das haml gem wird benötigt, um SCSS-Templates rendern zu können:
+Das +haml+ oder +sass+ gem wird benötigt, um SCSS-Templates rendern zu können:
 
   # sass muss eingebunden werden
   require 'sass'
@@ -297,7 +316,7 @@ und individuell überschrieben werden.
 
 === Less-Templates
 
-Das less gem wird benötigt, um Less-Templates rendern zu können:
+Das +less+ gem wird benötigt, um Less-Templates rendern zu können:
 
   # less muss eingebunden werden
   require 'less'
@@ -310,7 +329,7 @@ Dieser Code rendert <tt>./views/stylesheet.less</tt>.
 
 === Liquid-Templates
 
-Das liquid gem wird benötigt, um Liquid-Templates rendern zu können:
+Das +liquid+ gem wird benötigt, um Liquid-Templates rendern zu können:
 
   # liquid muss eingebunden werden
   require 'liquid'
@@ -328,7 +347,7 @@ aufrufen kann, will man nahezu in allen Fällen +locals+ übergeben:
 
 === Markdown-Templates
 
-Das rdiscount gem wird benötigt, um Markdown-Templates rendern zu können:
+Das +rdiscount+ gem wird benötigt, um Markdown-Templates rendern zu können:
 
   # rdiscount muss eingebunden werden
   require "rdiscount"
@@ -352,9 +371,45 @@ aufzurufen:
   %h1 Hallo von Haml!
   %p= markdown(:greetings)
 
+Da man Ruby aus Markdown heraus nicht aufrufen kann, ist es nicht
+möglich Layouts zu verwenden, die in Markdown geschrieben sind. Es ist aber
+möglich einen anderen Renderer für das Template zu verwenden als für das
+Layout, indem man die <tt>:layout_engine</tt> option angibt:
+
+  get '/' do
+    markdown :index, :layout_engine => :erb
+  end
+
+Das wird <tt>./views/index.md</tt> mit <tt>./views/layout.erb</tt> als Layout
+rendern.
+
+Denk dran, dass man solche Einstellungen auch global setzen kann:
+
+  set :markdown, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    markdown :index
+  end
+
+Das wird <tt>./views/index.md</tt> (und jedes andere Markdown Template) mit
+<tt>./views/post.haml</tt> als Layout rendern.
+
+Ebenso ist es möglich Markdown mit BlueCloth anstelle von RDiscount zu parsen:
+
+  require 'bluecloth'
+  
+  Tilt.register 'markdown', BlueClothTemplate
+  Tilt.register 'mkd',      BlueClothTemplate
+  Tilt.register 'md',       BlueClothTemplate
+  
+  get '/' do
+    markdown :index
+  end
+
+Das sollte <tt>./views/index.md</tt> mit BlueCloth rendern.
 === Textile-Templates
 
-Das RedCloth gem wird benötigt, um Textile-Templates rendern zu können:
+Das +redcloth+ gem wird benötigt, um Textile-Templates rendern zu können:
 
   # redcloth muss eingebunden werden
   require "redcloth"
@@ -377,12 +432,36 @@ aufzurufen:
   %h1 Hallo von Haml!
   %p= textile(:greetings)
 
+Da man Ruby aus Textile heraus nicht aufrufen kann, ist es nicht
+möglich Layouts zu verwenden, die in Textile geschrieben sind. Es ist aber
+möglich einen anderen Renderer für das Template zu verwenden als für das
+Layout, indem man die <tt>:layout_engine</tt> option angibt:
+
+  get '/' do
+    textile :index, :layout_engine => :erb
+  end
+
+Das wird <tt>./views/index.textile</tt> mit
+<tt>./views/layout.erb</tt> als Layout
+rendern.
+
+Denk dran, dass man solche Einstellungen auch global setzen kann:
+
+  set :textile, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    textile :index
+  end
+
+Das wird <tt>./views/index.textile</tt> (und jedes andere Markdown Template)
+mit <tt>./views/post.haml</tt> als Layout rendern.
+
 === RDoc-Templates
 
-Das rdoc gem wird benötigt, um RDoc-Templates rendern zu können:
+Das +rdoc+ gem wird benötigt, um RDoc-Templates rendern zu können:
 
   # RDoc muss eingebunden werden
-  require "rdoc"
+  require "rdoc/markup/to_html"
 
   get '/' do
     rdoc :index
@@ -402,9 +481,34 @@ aufzurufen:
   %h1 Hallo von Haml!
   %p= rdoc(:greetings)
 
+Da man Ruby aus RDoc heraus nicht aufrufen kann, ist es nicht
+möglich Layouts zu verwenden, die in RDoc geschrieben sind. Es ist aber
+möglich einen anderen Renderer für das Template zu verwenden als für das
+Layout, indem man die <tt>:layout_engine</tt> option angibt:
+
+  get '/' do
+    rdoc :index, :layout_engine => :erb
+  end
+
+Das wird <tt>./views/index.rdoc</tt> mit
+<tt>./views/layout.erb</tt> als Layout
+rendern.
+
+Denk dran, dass man solche Einstellungen auch global setzen kann:
+
+  set :rdoc, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    rdoc :index
+  end
+
+Das wird <tt>./views/index.rdoc</tt> (und jedes andere Markdown Template) mit
+<tt>./views/post.haml</tt> als Layout rendern.
+
+
 === Radius-Templates
 
-Das radius gem wird benötigt, um Radius-Templates rendern zu können:
+Das +radius+ gem wird benötigt, um Radius-Templates rendern zu können:
 
   # radius muss eingebunden werden
   require 'radius'
@@ -422,7 +526,7 @@ aufrufen kann, will man nahezu in allen Fällen +locals+ übergeben:
 
 === Markaby-Templates
 
-Das markaby gem wird benötigt, um Markaby-Templates rendern zu können:
+Das +markaby+ gem wird benötigt, um Markaby-Templates rendern zu können:
 
   # markaby muss eingebunden werden
   require 'markaby'
@@ -435,7 +539,7 @@ Dieser Code rendert <tt>./views/index.mab</tt>.
 
 === Slim-Templates
 
-Das slim gem wird benötigt, um Slim-Templates rendern zu können:
+Das +slim+ gem wird benötigt, um Slim-Templates rendern zu können:
 
   # slim muss eingebunden werden
   require 'slim'
@@ -448,7 +552,17 @@ Dieser Code rendert <tt>./views/index.slim</tt>.
 
 === CoffeeScript-Templates
 
-Das coffee-script gem und das `coffee`-Programm werden benötigt, um CoffeScript-Templates rendern zu können:
+Das +coffee+-script gem und  mindestens eine der folgenden Optionen werden
+benötigt, um JavaScript auf dem Server ausführen zu können:
+
+* +node+ (von Node.js) befindet sich im Pfad
+* du bist unter OS X
+* +therubyracer+ gem/library
+
+Siehe auch http://github.com/josh/ruby-coffee-script für eine vollständige
+Liste aller Optionen.
+
+Nun kannst Du CoffeeScript Templates in Deiner App rendern:
 
   # coffee-script muss eingebunden werden
   require 'coffee-script'
@@ -535,21 +649,32 @@ verwendet. Durch <tt>:layout => false</tt> kann das Ausführen verhindert werden
     haml :index, :layout => !request.xhr?
   end
 
-== Helfer
+=== Datieendungen zuordnen
 
-Durch die Top-Level <tt>helpers</tt>-Methode, werden sogenannte Helfer-Methoden
-definiert, die in Routen und Templates verwendet werden können:
+Um eine Dateiendung einer Template Engine zuzuordnen, benutzt man am besten
+<tt>Tilt.register</tt>. Wenn man zum Beispiel die Dateiendung +tt+ für Textile
+Templates nutzen möchte, so lässt sich das wie folgt bewerkstelligen:
+
+  Tilt.register :tt, Tilt[:textile]
+
+=== Eine eigene Template Engine hinzufügen
+
+Zu allererst muss man die Engine bei Tilt registrieren und danach eine
+Rendering-Methode erstellen:
+
+  Tilt.register :mtt, MeineTolleTemplateEngine
 
   helpers do
-    def bar(name)
-      "#{name}bar"
-    end
+    def mtt(*args) render(:mtt, *args) end
   end
 
-  get '/:name' do
-    bar(params[:name])
+  get '/' do
+    mtt :index
   end
 
+Dieser Code rendert <tt>./views/application.mtt</tt>. Siehe
+https://github.com/rtomayko/tilt um mehr über Tilt zu lernen.
+
 == Filter
 
 Before-Filter werden immer vor jedem Request in dem selben Kontext wie danach
@@ -574,7 +699,8 @@ Instanzvariablen können in After-Filterm verwendet werden:
     puts response.status
   end
 
-Filter können optional auch mit einem Pattern ausgestattet werden, welche auf den Request-Pfad passen müssen, damit der Filter ausgeführt wird:
+Filter können optional auch mit einem Pattern ausgestattet werden, welche auf
+den Request-Pfad passen müssen, damit der Filter ausgeführt wird:
 
   before '/protected/*' do
     authenticate!
@@ -584,7 +710,8 @@ Filter können optional auch mit einem Pattern ausgestattet werden, welche auf d
     session[:last_slug] = slug
   end
 
-Ähnlich wie Routen können Filter auch mit weiteren Bedingungen eingeschränkt werden:
+Ähnlich wie Routen können Filter auch mit weiteren Bedingungen eingeschränkt
+werden:
 
   before :agent => /Songbird/ do
     # ...
@@ -594,6 +721,21 @@ Filter können optional auch mit einem Pattern ausgestattet werden, welche auf d
     # ...
   end
 
+== Helfer
+
+Durch die Top-Level <tt>helpers</tt>-Methode, werden sogenannte Helfer-Methoden
+definiert, die in Routen und Templates verwendet werden können:
+
+  helpers do
+    def bar(name)
+      "#{name}bar"
+    end
+  end
+
+  get '/:name' do
+    bar(params[:name])
+  end
+
 == Anhalten
 
 Zum sofortigen stoppen eines Request in einem Filter oder einer Route:
@@ -633,9 +775,173 @@ Der Block wird sofort verlassen und es wird nach der nächsten treffenden Route
 gesucht. Ein 404 Fehler wird zurückgegeben, wenn kein treffendes Routen-Muster
 gefunden wird.
 
+=== Eine andere Route ansteuern
+
+Manchmal entspricht +pass+ nicht den Anforderungen, wenn das Ergebnis einer
+anderen Route gefordert wird. Um das zu erreichen, lässt sich +call+ nutzen:
+
+  get '/foo' do
+    status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
+    [status, body.upcase]
+  end
+
+  get '/bar' do
+    "bar"
+  end
+
+Beachte, dass in dem oben angegeben Beispiel die Performance erheblich erhöht
+werden kann, wenn man +"bar"+ in eine Helfermethode umwandelt, auf die +/foo+
+und +/bar+ zugreifen können.
+
+Wenn der Request innerhalb der gleichen App-Instanz aufgerufen und keine
+Kopie der Instanz erzeugt werden soll, dann verwende +call!+ anstelle von
++call+.
+
+Die Rack Spezifikationen enthalten weitere Informationen zu +call+.
+
+=== Body, Status Code und Header setzen
+
+Es ist möglich und empfohlen den Status Code sowie den Response Body mit einem
+Returnwert in der Route zu setzen. In manchen Situationen kann es jedoch sein,
+dass der Body an irgendeiner anderen Stelle während der Ausführung gesetzt
+wird. Das lässt sich mit der Helfermethode +body+ bewerkstelligen. Wird +body+
+verwendet, dann lässt sich der Body jederzeit über diese Methode aufrufen:
+
+  get '/foo' do
+    body "bar"
+  end
+  
+  after do
+    puts body
+  end
+
+Ebenso ist es möglich einen Block an +body+ weiterzureichen, der dann vom Rack
+Handler ausgeführt wird (lässt sich z.B. zur Umsetzung von Streaming einsetzen,
+siehe auch "Rückgabewerte").
+
+Vergleichbar mit +body+ lassen sich auch Status Code und Header setzen:
+
+  get '/foo' do
+    status 418
+    headers \
+      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN"
+      "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
+    halt "Ich bin ein Teekesselchen"
+  end
+
+Genau wie bei +body+, liest ein Aufrufen von +headers+ oder +status+ ohne
+Argumente den aktuellen Wert aus.
+
+== Mime-Types
+
+Wenn <tt>send_file</tt> oder statische Dateien verwendet werden, kann es
+vorkommen, dass Sinatra den Mime-Typ nicht kennt. Registriert wird dieser mit
++mime_type+ per Dateiendung:
+
+  mime_type :foo, 'text/foo'
+
+Es kann aber auch der +content_type+ Helfer verwendet werden:
+
+  get '/' do
+    content_type :foo
+    "foo foo foo"
+  end
+
+=== URLs generieren
+
+Zum Generieren von URLs sollte man die +url+ Helfermethode nutzen, so z.B.
+beim Einsatz von Haml:
+
+  %a{:href => url('/foo')} foo
+
+Soweit vorhanden, wird Rücksicht auf Proxies und Rack Router genommen.
+
+Diese Methode ist ebenso über den Alias +to+ zu erreichen (siehe Beispiel
+unten).
+
+=== Browserumleitung
+
+Eine Browserumleitung kann mit Hilfe der +redirect+ Hilfsmethode erreicht
+werden:
+
+  get '/foo' do
+    redirect to('/bar')
+  end
+
+Weitere Parameter werden wie Argumente der +halt+ Methode behandelt:+:
+
+  redirect to('/bar'), 303
+  redirect 'http://google.com', 'Hier bist Du falsch'
+
+Ebenso leicht lässt sich ein Schritt zurück mit dem Alias
+<tt>redirect back</tt> erreichen:
+
+  get '/foo' do
+    "<a href='/bar'>mach was</a>"
+  end
+
+  get '/bar' do
+    mach_was
+    redirect back
+  end
+
+Um Argumente an ein Redirect weiterzugeben, fügt man sie entweder dem Query
+hinzu:
+
+  redirect to('/bar?summe=42')
+
+Oder man verwendet eine Session:
+
+  enable :session
+  
+  get '/foo' do
+    session[:secret] = 'foo'
+    redirect to('/bar')
+  end
+  
+  get '/bar' do
+    session[:secret]
+  end
+
+=== Dateien versenden
+
+Zum versenden von Dateien kann die <tt>send_file</tt> Helfermethode verwende
+werden:
+
+  get '/' do
+    send_file 'foo.png'
+  end
+
+Für <tt>send_file</tt> stehen einige Hash-Optionen zur Verfügung:
+
+  send_file 'foo.png', :type => :jpg
+
+[filename]
+  Dateiname als Response. Standartwert ist der eigentliche Dateiname
+
+[last_modified]
+  Wert für den Last-Modified Header, Standardwert ist +mtime+ der Datei.
+
+[type]
+  content type der verwendet werden soll. Wird, wenn nicht angegeben, von der
+  Dateiendung abgeleitet.
+  
+[disposition]
+  Verwendet für Content-Disposition. Mögliche Werte sind: +nil+ (Standard),
+  <tt>:attachment</tt> und <tt>:inline</tt>
+
+[length]
+  Content-Length Header. Standardwert ist die Dateigröße
+
+Soweit vom Rack Handler unterstützt, werden neben der Übertragung über den Ruby
+Prozess auch andere Möglichkeiten genutzt. Bei Verwendung der
+<tt>send_file</tt> Helfermethode kümmert sich Sinatra selbständig um die
+Range Requests.
+
 == Das Request-Objekt
 
-Auf das `request`-Objeket der eigehenden Anfrage kann man vom Anfragescope aus zugreifen:
+Auf das +request+-Objeket der eigehenden Anfrage kann man vom Anfragescope aus
+zugreifen:
 
   # App läuft unter http://example.com/example
   get '/foo' do
@@ -652,14 +958,15 @@ Auf das `request`-Objeket der eigehenden Anfrage kann man vom Anfragescope aus z
     request.get?              # true (ähnliche Methoden für andere Verben)
     request.form_data?        # false
     request["SOME_HEADER"]    # Wert des SOME_HEADER-headers
-    request.referer           # der Referrer des Clients oder '/'
+    request.referrer          # der Referrer des Clients oder '/'
     request.user_agent        # User Agent (genutzt von :agent-Bedingung)
     request.cookies           # Hash der Cookies
     request.xhr?              # Ist dies eine Ajax-Anfrage?
     request.url               # "http://example.com/example/foo"
     request.path              # "/example/foo"
     request.ip                # Client IP-Addresse
-    request.secure?           # false
+    request.secure?           # false (wäre true bei SSL)
+    request.forwarded?        # true (wenn hinter Reverse Proxy)
     requuest.env              # env-Hash den Rack durchreicht
   end
 
@@ -680,12 +987,71 @@ Der <tt>request.body</tt> ist einn IO- oder StringIO-Objekt:
     "Hallo #{daten['name']}!"
   end
 
+
+=== Nachschlagen von Template Dateien
+
+Die <tt>find_template</tt> Helfermethode wird genutzt, um Template Dateien zum
+Rendern aufzufinden:
+
+  find_template settings.views, 'foo', Tilt[:haml] do |file|
+    puts "könnte diese hier sein: #{file}"
+  end
+
+Das ist zwar nicht wirklich brauchbar, aber wenn man sie überschreibt, kann sie
+nützlich werden, um eigene Nachschlagemechanismen einzubauen. Zum Beispiel
+dann, wenn man mehr als nur ein view-Verzeichnis verwenden möchte:
+
+  set :views, ['views', 'templates']
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      Array(views).each { |v| super(v, name, engine, &block) }
+    end
+  end
+
+Ein anderes Beispiel wäre es verschiedene Vereichnisse für verschiedene Engines
+zu verwenden:
+
+  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
+
+Ebensogut könnte man eine Extension schreiben und diese dann mit anderen
+teilen!
+
+Beachte, dass <tt>find_template</tt> nicht prüft, ob eine Datei tatsächlich
+existiert. Es wird lediglich der angegebene Block aufgerufen und nach allen
+möglichen Pfaden gesucht. Das ergibt kein Performanceproblem, da +render+
++block+ verwendet, sobald eine Datei gefunden wurde. Ebenso werden
+Templatepfade samt Inhalt gecached, solange man nicht im Entwicklungsmodus ist.
+Das sollte man im Hinterkopf behalten, wenn man irgendwelche verrückten
+Methoden zusammenbastelt.
+
 == Konfiguration
 
 Wird einmal beim Starten in jedweder Umgebung ausgeführt:
 
   configure do
-    ...
+    # setze eine Option
+    set :option, 'wert'
+    
+    # setze mehrere Optionen
+    set :a => 1, :b => 2
+    
+    # das gleiche wie `set :option, true`
+    enable :option
+    
+    # das gleiche wie `set :option, false`
+    disable :option
+    
+    # Dynamische Einstellungen mit Blöcken
+    set(:css_dir) { File.join(views, 'css') }
   end
 
 Läuft nur, wenn die Umgebung (RACK_ENV Umgebungsvariable) auf
@@ -702,6 +1068,116 @@ gesetzt ist:
     ...
   end
 
+Zugang zu diesen Einstellungen bekommt man über +settings+:
+
+  configure do
+    set :foo, 'bar'
+  end
+
+  get '/' do
+    settings.foo? # => true
+    settings.foo  # => 'bar'
+    ...
+  end
+
+=== Mögliche Einstellungen
+
+[absolute_redirects]  Wenn ausgeschaltet wird Sinatra relative Redirects
+                      zulassen. Jedoch ist Sinatra dann nicht mehr mit RFC 2616
+                      (HTTP 1.1) konform, das nur absolute Redirects zulässt.
+                      
+                      Sollte eingeschaltet werden, wenn man hinter einem
+                      Reverse Proxy ist, der nicht ordentlich eingerichtet ist.
+                      Beachte, dass die +url+ Helfermethode nach wie vor
+                      absolute URLs erstellen wird, es sei denn man gibt als
+                      zweiten Parameter +false+ an.
+                      
+                      Standardmäßig nicht aktiviert.
+                      
+
+[add_charsets]        Mime Types werden hier automatisch der Helfermethode
+                      <tt>content_type</tt> zugeordnet.
+                      
+                      Es empfielt sich Werte hinzuzufügen anstellen von
+                      überschreiben:
+                      
+                        settings.add_charsets << "application/foobar"
+
+[app_file]            Hauptdatei der Applikation. Wird verwendet, um das
+                      Wurzel-, Inline-, View- und öffentliche Verzeichnis des
+                      Projekts festzustellen.
+                      
+[bind]                IP Address an die gebunden wird (Standardwert: 0.0.0.0).
+                      Wird nur für den eingebauten Server verwendet.
+
+[default_encoding]    Das Encoding, falls keines angegeben wurde.
+                      Standardwert ist <tt>"utf-8"</tt>.
+
+[dump_errors]         Fehler im Log anzeigen.
+
+[environment]         Momentane Umgebung. Standardmäßig auf
+                      <tt>content_type</tt> eingestellt oder
+                      <tt>"development"</tt> soweit ersteres nicht vorhanden.
+
+[logging]             Den Logger verwenden.
+
+[lock]                Jeder Request wird gelocked. Es kann nur ein Request pro
+                      Ruby Prozess gleichzeitig verarbeitet werden.
+                      
+                      Eingeschaltet wenn die Application Thread-Safe ist.
+                      Standardmäßig nicht aktiviert.
+
+[method_override]     Verwende <tt>_method</tt>, um put/delete Formulardaten in
+                      Browsern zu verwenden, die dies normalerweise nicht
+                      unterstützen.
+
+[port]                Port für die Applikation. Wird nur im internen Server
+                      verwendet.
+
+[prefixed_redirects]  Entscheidet, ob <tt>request.script_name</tt> in Redirects
+                      eingefügt wird oder nicht, wenn kein absoluter Pfad
+                      angegeben ist. Auf diese Art und Weise verhält sich
+                      <tt>redirect '/foo'</tt> so als ob es ein
+                      <tt>redirect to('/foo')</tt> wäre.
+                      Standardmäßig nicht aktiviert.
+
+[public]              Das öffentliche Verzeichnis aus dem Daten zur Verfügung
+                      gestellt werden können.
+
+[reload_templates]    Entscheidet, ob Templates zwischen Anfragen neu geladen
+                      werden sollen oder nicht. Unter Ruby 1.8.6 ist es im
+                      Entwicklungsmodus eingeschaltet (um einen Fehler in Ruby
+                      auszugleichen, der ein Speicherleck verursacht).
+
+[root]                Wurzelverzeichnis des Projekts.
+
+[raise_errors]        Einen Ausnahmezustand aufrufen. Beendet die Applikation.
+
+[run]                 Wenn aktiviert, wird Sinatra versuchen den Webserver zu
+                      starten. Nicht verwenden, wenn Rackup oder anderes
+                      verwendet werden soll.
+
+[running]             Läuft der eingebaute Server? Diese Einstellung nicht
+                      ändern!
+
+[server]              Server oder Liste von Servern die als eingebaute Server
+                      zur Verfügung stehen.
+                      Standardmäßig auf ['thin', 'mongrel', 'webrick']
+                      voreingestellt. Die Anordnung gibt die Priorität vor.
+
+[sessions]            Sessions auf Cookiebasis aktivieren.
+
+[show_exceptions]     Stacktrace im Browser bei Fehlern anzeigen.
+
+[static]              Entscheidet, ob Sinatra statische Dateien zur Verfügung
+                      stellen soll oder nicht.
+                      Sollte nicht aktiviert werden, wenn ein Server verwendet
+                      wird, der dies auch selbständig erledigen kann.
+                      Deaktivieren wird die Performance erhöhen.
+                      Standardmäßig aktiviert.
+
+[views]               Verzeichnis der Views.
+
 == Fehlerbehandlung
 
 Error Handler laufen im selben Kontext wie Routen und Filter, was bedeutet,
@@ -710,7 +1186,8 @@ verwendet werden können.
 
 === Nicht gefunden
 
-Wenn eine <tt>Sinatra::NotFound</tt> Exception geworfen wird oder der Statuscode 404 ist, wird der <tt>not_found</tt> Handler ausgeführt:
+Wenn eine <tt>Sinatra::NotFound</tt> Exception geworfen wird oder der
+Statuscode 404 ist, wird der <tt>not_found</tt> Handler ausgeführt:
 
   not_found do
     'Seite kann nirgendwo gefunden werden.'
@@ -718,8 +1195,8 @@ Wenn eine <tt>Sinatra::NotFound</tt> Exception geworfen wird oder der Statuscode
 
 === Fehler
 
-Der +error+ Handler wird immer ausgeführt, wenn eine Exception in einem Routenblock
-oder in einen Filter geworfen wurde. Die Exception kann über die
+Der +error+ Handler wird immer ausgeführt, wenn eine Exception in einem
+Routenblock oder in einen Filter geworfen wurde. Die Exception kann über die
 <tt>sinatra.error</tt> Rack-Variable angesprochen werden:
 
   error do
@@ -761,21 +1238,10 @@ Oder ein Statuscode-Bereich:
 Sinatra setzt verschiedene <tt>not_found</tt> und <tt>error</tt>
 Handler in der Development Umgebung.
 
-== Mime-Types
-
-Wenn <tt>send_file</tt> oder statische Dateien verwendet werden, kann es
-vorkommen, dass Sinatra den Mime-Typ nicht kennt. Registriert wird dieser mit
-+mime_type+ per Dateiendung:
-
-  mime_type :foo, 'text/foo'
-
-Es kann aber auch der +content_type+ Helfer verwendet werden:
-
-  content_type :foo
-
 == Rack Middleware
 
-Sinatra baut auf Rack[http://rack.rubyforge.org/], einem minimalen Standardinterface für Ruby Webframeworks. Eines der interessantesten
+Sinatra baut auf Rack[http://rack.rubyforge.org/], einem minimalen
+Standardinterface für Ruby Webframeworks. Eines der interessantesten
 Features für Entwickler ist der Support von Middleware, die
 zwischen den Server und die Anwendung geschaltet wird und so HTTP
 Request und/oder Antwort überwachen und/oder manipulieren kann.
@@ -848,7 +1314,8 @@ Das Definitieren einer Top-Level Anwendung funktioniert gut für
 Microanwendungen, hat aber Nachteile, wenn man wiederverwendbare Komponenten
 wie Middleware, Rails Metal, einfache Bibliotheken mit Server Komponenten
 oder auch Sinatra Erweiterungen bauen will.
-Die Top-Level DSL belastet den Objekt-Namespace und setzt einen Microanwendungsstil voraus (eine einzelne Anwendungsdatei, ./public und ./views
+Die Top-Level DSL belastet den Objekt-Namespace und setzt einen
+Microanwendungsstil voraus (eine einzelne Anwendungsdatei, ./public und ./views
 Ordner, Logging, Exception-Detail-Seite, usw.). Genau hier kommt Sinatra::Base
 ins Spiel:
 
@@ -871,7 +1338,8 @@ einer Bibliothek:
    MyApp.run! :host => 'localhost', :port => 9090
 
 Die Methoden der Sinatra::Base-Subklasse sind genau die selben wie die
-der Top-Level DSL. Die meisten Top-Level Anwendungen können mit nur zwei Veränderungen zu Sinatra::Base-Komponenten konvertiert werden:
+der Top-Level DSL. Die meisten Top-Level Anwendungen können mit nur zwei
+Veränderungen zu Sinatra::Base-Komponenten konvertiert werden:
 
 * Die Datei sollte <tt>require 'sinatra/base'</tt> anstelle von
   <tt>require 'sinatra/base'</tt> aufrufen, ansonsten werden alle von
@@ -879,7 +1347,100 @@ der Top-Level DSL. Die meisten Top-Level Anwendungen können mit nur zwei Verän
 * Alle Routen, Error Handler, Filter und Optionen der Applikation müssen in
   einer Subklasse von Sinatra::Base definiert werden.
 
-<tt>Sinatra::Base</tt> ist ein unbeschriebenes Blatt. Die meisten Optionen sind per default deaktiviert. Das betrifft auch den eingebauten Server. Siehe {Optionen und Konfiguration}[http://sinatra.github.com/configuration.html] für Details über mögliche Optionen.
+<tt>Sinatra::Base</tt> ist ein unbeschriebenes Blatt. Die meisten Optionen sind
+per default deaktiviert. Das betrifft auch den eingebauten Server. Siehe
+{Optionen und Konfiguration}[http://sinatra.github.com/configuration.html] für
+Details über mögliche Optionen.
+
+=== Modularer vs. klassischer Stil
+
+Entgegen häufiger Meinungen gibt es nichts gegen den klassischen Stil
+einzuwenden. Solange es die Applikation nicht beeinträchtigt, besteht kein
+Grund eine modulare Applikation zu erstellen.
+
+Lediglich zwei Nachteile gegenüber dem modularen Stil sollten beachtet werden:
+
+* Es kann nur eine Sinatra Applikation pro Ruby Prozess laufen. Sollten mehrere
+  zum Einsatz kommen, muss auf modular umgestiegen werden.
+  
+* Der klassische Stil füllt Object mit Delegationsmethoden. Sollte die
+  Applikation als gem/Bibliothek zum Einsatz kommen, sollte auf modular
+  umgestiegen werden.
+  
+Es gibt keinen Grund, warum  man modulare und klassische Elemente nicht
+vermischen sollte.
+
+Will man jedoch von einem Stil auf den anderen umsteigen, sollten einige
+Unterschiede beachtet werden:
+
+  Szenario            Classic                 Modular
+
+  app_file            file loading sinatra    nil
+  run                 $0 == app_file          false
+  logging             true                    false
+  method_override     true                    false
+  inline_templates    true                    false
+
+
+=== Eine modulare Applikation bereitstellen
+
+Es gibt zwei übliche Wege eine modulare Anwendung zu starten. Zum einen über
+<tt>run!</tt>:
+
+  # mein_app.rb
+  require 'sinatra/base'
+  
+  class MeinApp < Sinatra::Base
+    # ... Anwendungscode hierhin ...
+    
+    # starte den Server, wenn die Ruby Datei direkt ausgeführt wird
+    run! if app_file == $0
+  end
+
+Starte mit:
+
+  ruby mein_app.rb
+
+Oder über eine <tt>config.ru</tt>, die es erlaubt irgendeinen Rack Handler zu
+verwenden:
+
+  # config.ru
+  require 'mein_app'
+  run MeineApp
+
+Starte:
+
+  rackup -p 4567
+
+=== Eine klassische Anwendung mit einer config.ru verwenden
+
+Schreibe eine Anwendungsdatei:
+
+  # app.rb
+  require 'sinatra'
+  
+  get '/' do
+    'Hallo Welt!'
+  end
+
+Sowie eine dazugehörige <tt>config.ru</tt>:
+
+  require 'app'
+  run Sinatra::Application
+
+=== Wann verwendet man eine config.ru?
+
+Anzeichen dafür, dass man eine <tt>config.ru</tt> braucht:
+
+* Man möchte einen anderen Rack Handler verwenden (Passenger, Unicorn,
+  Heroku, ...).
+* Man möchte mehr als eine Subklasse von <tt>Sinatra::Base</tt>.
+* Man möchte Sinatra als Middleware verwenden, nicht als Endpoint.
+
+<b>Es gibt keinen Grund eine <tt>config.ru</tt> zu verwenden, nur weil man eine
+Anwendung im modularen Stil betreiben möchte. Ebenso braucht man keine
+Anwendung im modularen Stil, um eine <tt>config.ru</tt> verwenden zu können.
+</b>
 
 === Sinatra als Middleware nutzen
 
@@ -918,16 +1479,22 @@ Sinatra-Anwendung handen, es kann jede andere Rack-Anwendung sein
     get('/') { "Hallo #{session['user_name']}." }
   end
 
-== Scopes und Bindung
+== Geltungsbereich und Bindung
 
-In welchem Scope man sich gerade befinded legt fest, welche Methoden und
-Variablen zur Verfügung stehen.
+Der Geltungsbereich (scope) legt fest, welche Methoden und Variablen zur
+Verfügung stehen.
 
 === Anwendungs- oder Klassenscope
 
-Jede Sinatra-Anwendung entspricht einer Sinatra::Base-Subklasse. Falls man die Top-Level-DSL verwendet (<tt>require 'sinatra'</tt>), so handelt es sich hierbei um Sinatra::Application, andernfalls is es jene Subklasse, die man explizit angelegt hat. Auf Klassenebene stehen Methoden wie `get` oder `before` zur Verfügung, man hat aber keinen Zugriff auf das `request`-Object oder die `session`, da nur eine einzige Klasse für alle eingehenden Anfragen genutzt wird.
+Jede Sinatra-Anwendung entspricht einer Sinatra::Base-Subklasse. Falls man die
+Top-Level-DSL verwendet (<tt>require 'sinatra'</tt>), so handelt es sich
+hierbei um Sinatra::Application, andernfalls is es jene Subklasse, die man
+explizit angelegt hat. Auf Klassenebene stehen Methoden wie +get+ oder +before+
+zur Verfügung, man hat aber keinen Zugriff auf das +request+-Object oder die
++session+, da nur eine einzige Klasse für alle eingehenden Anfragen genutzt
+wird.
 
-Optionen die via `set` gesetzt werden, sind Methoden auf Klassenebene:
+Optionen die via +set+ gesetzt werden, sind Methoden auf Klassenebene:
 
   class MyApp < Sinatra::Base
     # Hey, ich bin im Anwendungsscope!
@@ -943,18 +1510,22 @@ Im Anwendungsscope befindet man sich:
 
 * In der Anwendungsklasse.
 * In Methoden die von Erweiterungen definiert werden.
-* Im Block, der an `helpers` übergeben wird.
-* In Procs und Blöcken die an `set` übergeben werden.
+* Im Block, der an +helpers+ übergeben wird.
+* In Procs und Blöcken die an +set+ übergeben werden.
 
 Man kann auf das Scope-Object (die Klasse) wie folgt zugreifen:
 
-* Über das Objekt, dass an den `configure`-Block übergeben wird (<tt>configure
+* Über das Objekt, dass an den +configure+-Block übergeben wird (<tt>configure
   { |c| ... }</tt>).
-* `settings` aus den anderen Scopes heraus.
+* +settings+ aus den anderen Scopes heraus.
 
 === Anfrage- oder Instanzscope
 
-Für jede eingehende Anfrage wird eine neue Instanz der Anwendungsklasse erstellt und alle Handlers werden in diesem Scope ausgeführt. Aus diesem Scope heraus kann man auf `request` oder `session` zugreifen und Methoden wie `erb` oder `haml` aufrufen. Man kann mit der `settings` Methode außerdem auf den Anwengungsscope zugreifen.
+Für jede eingehende Anfrage wird eine neue Instanz der Anwendungsklasse
+erstellt und alle Handlers werden in diesem Scope ausgeführt. Aus diesem Scope
+heraus kann man auf +request+ oder +session+ zugreifen und Methoden wie +erb+
+oder +haml+ aufrufen. Man kann mit der +settings+ Methode außerdem auf den
+Anwengungsscope zugreifen.
 
   class MyApp < Sinatra::Base
     # Hey, ich bin im Anwendungsscope!
@@ -985,15 +1556,18 @@ weitergeleitet. Dieser verhält sich jedoch nicht 100%ig wie der Klassenscope,
 da man nicht die Bindung der Klasse besitzt: Nur Methoden, die explizit als
 delegierbar markiert wurden stehen hier zur Verfügung und man kann nicht auf
 die Variablen des Klassenscopes zugreifen (mit anderen Worten: man hat ein
-anderes `self`). Man kann mit <tt>Sinatra::Delegator.delegate
+anderes +self+). Man kann mit <tt>Sinatra::Delegator.delegate
 :methoden_name</tt> auch weitere Delegationen hinzufügen.
 
 Im Delegation-Scop befindet man sich:
 
 * Im Top-Level, wenn man <tt>require 'sinatra'</tt> aufgerufen hat.
-* In einem Objekt, dass mit dem `Sinatra::Delegator` mixin erweitert wurde.
+* In einem Objekt, dass mit dem <tt>Sinatra::Delegator</tt> mixin erweitert wurde.
 
-Schau am besten im Code nach: Hier ist {Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064] definiert und wird in den {globalen Namespace eingebunden}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].
+Schau am besten im Code nach: Hier ist
+{Sinatra::Delegator mixin}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/base.rb#L1064]
+definiert und wird in den
+{globalen Namespace eingebunden}[http://github.com/sinatra/sinatra/blob/master/lib/sinatra/main.rb#L25].
 
 == Kommandozeile
 
@@ -1011,7 +1585,40 @@ Die Optionen sind:
   -x # Mutex lock einschalten (Standard ist off)
 
 == Der neueste Stand (The Bleeding Edge)
+Um auf dem neusten Stand zu bleiben, kannst Du den Master Branch verwenden. Er
+sollte recht stabil sein. Ebenso gibt es von Zeit zu Zeit prerelease Gems, die
+du so installierst:
+  
+  gem install sinatra --pre
+
+=== Mit Bundler
+Wenn du deine App mit der neusten Version von Sinatra mit
+{Bundler}[http://gembundler.com/] nutzen willst, dann ist dies der
+vorgeschlagene Weg:
+
+Soweit du Bundler noch nicht installiert hast, folgendes:
+
+  gem install bundler
+  
+Dann erstellst Du in deinem Projektverzeichnis eine sog. +Gemfile+ Datei mit
+folgendem Inhalt:
+
+  source :rubygems
+  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+  
+  # evtl. andere Abhängigkeiten
+  gem 'haml'                    # z.B. wenn du haml verwendest...
+  gem 'activerecord', '~> 3.0'  # ...oder ActiveRecord 3.x
+
+Beachte: Du solltest hier alle Abhängigkeiten eintragen. Sinatras eigenen,
+direkten Abhängigkeiten (Tilt und Rack) werden von Bundler automatisch aus dem
+Gemfile von Sinatra hinzugefügt.
+
+Jetzt kannst du deine App starten:
 
+  bundle exec ruby myapp.rb
+  
+=== Eigenes Repository
 Um auf den neuesten Stand von Sinatras Code zu sein, kann eine lokale Kopie
 angelegt werden. Gestartet wird in der Anwendung mit dem <tt>sinatra/lib</tt>
 Ordner im <tt>LOAD_PATH</tt>:
@@ -1036,11 +1643,28 @@ Um Sinatra Code von Zeit zu Zeit zu aktualisieren:
   cd myproject/sinatra
   git pull
 
+=== Gem erstellen
+
+Aus der eigenen lokalen Kopie kann nun auch ein globales gem gebaut werden:
+
+  git clone git://github.com/sinatra/sinatra.git
+  cd sinatra
+  rake sinatra.gemspec
+  rake install
+
+Falls du normalerweise gems als root installierst, sollte die letzte Zeile
+so lauten:
+
+  sudo rake install
+
+
+
 == Mehr
 
 * {Projekt Website}[http://sinatra.github.com/] - Ergänzende Dokumentation,
   News und Links zu anderen Ressourcen.
-* {Hilfe beisteuern}[http://sinatra.github.com/contributing.html] - Einen Fehler gefunden? Brauchst du Hilfe? Hast du einen Patch?
+* {Hilfe beisteuern}[http://sinatra.github.com/contributing.html] - Einen
+Fehler gefunden? Brauchst du Hilfe? Hast du einen Patch?
 * {Issue Tracker}[http://github.com/sinatra/sinatra/issues]
 * {Twitter}[http://twitter.com/sinatra]
 * {Mailingliste}[http://groups.google.com/group/sinatrarb]