resque-pool 0.3.0.beta.1 → 0.3.0.beta.2

data/vendor/bundle/ruby/1.8/gems/sinatra-1.3.2/README.fr.rdoc

@@ -0,0 +1,1983 @@
+= Sinatra
+
+<i>Attention : Ce document correspond à la traduction de la version anglaise et
+il n'est peut être plus à jour.</i>
+
+Sinatra est un DSL pour créer rapidement et facilement des applications web en
+Ruby :
+
+  # mon_application.rb
+  require 'sinatra'
+
+  get '/' do
+    'Bonjour le monde !'
+  end
+
+Installez la gem et lancez avec :
+
+  gem install sinatra
+  ruby -rubygems mon_application.rb
+
+Le résultat est visible sur : http://localhost:4567
+
+Il est recommandé d'exécuter également <tt>gem install thin</tt>, pour que
+Sinatra utilise le server Thin quand il est disponible.
+
+== Routes
+
+Dans Sinatra, une route est une méthode HTTP couplée à un masque (pattern)
+URL. Chaque route est associée à un bloc :
+
+  get '/' do
+    .. montrer quelque chose ..
+  end
+
+  post '/' do
+    .. créer quelque chose ..
+  end
+
+  put '/' do
+    .. remplacer quelque chose ..
+  end
+
+  patch '/' do
+    .. changer quelque chose ..
+  end
+
+  delete '/' do
+    .. effacer quelque chose ..
+  end
+
+  options '/' do
+    .. apaiser quelquechose ..
+  end
+
+Les routes sont évaluées  dans l'ordre où elles ont été définies. La première
+route qui correspond à la requête est appelée.
+
+Les masques peuvent inclure des paramètres nommés, accessibles par
+l'intermédiaire du hash <tt>params</tt> :
+
+  get '/bonjour/:nom' do
+    # répond aux requêtes "GET /bonjour/foo" et "GET /bonjour/bar"
+    # params[:nom] est 'foo' ou 'bar'
+    "Bonjour #{params[:nom]} !"
+  end
+
+Vous pouvez aussi accéder aux paramètres nommés directement grâce aux
+paramètres du bloc comme ceci :
+
+  get '/bonjour/:nom' do |n|
+    "Bonjour #{n} !"
+  end
+
+Une route peut contenir un splat (caractère joker), accessible par
+l'intermédiaire du tableau <tt>params[:splat]</tt> :
+
+  get '/dire/*/a/*' do
+    # répond à /dire/bonjour/a/monde
+    params[:splat] # => ["bonjour", "monde"]
+  end
+
+  get '/telecharger/*.*' do
+    # répond à /telecharger/chemin/vers/fichier.xml
+    params[:splat] # => ["chemin/vers/fichier", "xml"]
+  end
+
+Ou par l'intermédiaire des paramètres du bloc :
+
+  get '/telecharger/*.*' do |chemin, ext|
+    [chemin, ext] # => ["path/to/file", "xml"]
+  end
+
+Une route peut aussi être définie par une Expression Régulière :
+
+  get %r{/bonjour/([\w]+)} do
+    "Bonjour, #{params[:captures].first} !"
+  end
+
+Là encore on peut utiliser les paramètres de bloc :
+
+  get %r{/bonjour/([\w]+)} do |c|
+    "Bonjour, #{c} !"
+  end
+
+Les routes peuvent aussi comporter des paramètres optionnels :
+
+  get '/posts.?:format?' do
+    # répond à "GET /posts" et aussi à "GET /posts.json", "GET /posts.xml" etc...
+  end
+
+=== Conditions
+
+Les routes peuvent définir toutes sortes de conditions, comme par exemple le
+"user agent" :
+
+  get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
+    "Vous utilisez Songbird version #{params[:agent][0]}"
+  end
+
+  get '/foo' do
+    # Correspond à tous les autres navigateurs
+  end
+
+Les autres conditions disponibles sont +host_name+ et +provides+ :
+
+  get '/', :host_name => /^admin\./ do
+    "Zone Administrateur, Accès refusé !"
+  end
+
+  get '/', :provides => 'html' do
+    haml :index
+  end
+
+  get '/', :provides => ['rss', 'atom', 'xml'] do
+    builder :feed
+  end
+
+Vous pouvez facilement définir vos propres conditions :
+
+  set(:probability) { |value| condition { rand <= value } }
+
+  get '/gagner_une_voiture', :probability => 0.1 do
+    "Vous avez gagné !"
+  end
+
+  get '/gagner_une_voiture' do
+    "Désolé, vous avez perdu."
+  end
+
+Utilisez un splat (caractère joker) dans le cas d'une condition qui prend
+plusieurs valeurs :
+
+  set(:auth) do |*roles|   # <- ici on utilise un splat
+    condition do
+      unless logged_in? && roles.any? {|role| current_user.in_role? role }
+        redirect "/login/", 303 
+      end
+    end
+  end
+
+  get "/mon/compte/", :auth => [:user, :admin] do
+    "Informations sur votre compte"
+  end
+
+  get "/reserve/aux/admins/", :auth => :admin do  
+    "Seuls les administrateurs sont acceptés ici !"
+  end
+
+=== Valeurs de retour
+
+La valeur renvoyée par le bloc correspondant à une route constitue le corps de
+la réponse qui sera transmise au client HTTP ou du moins au prochain middleware
+dans la pile Rack. Le plus souvent, il s'agit d'une chaîne de caractères,
+comme dans les exemples précédents. Cependant, d'autres valeurs sont
+acceptées.
+
+Vous pouvez renvoyer n'importe quel objet qu'il s'agisse d'une réponse Rack
+valide, d'un corps de réponse Rack ou d'un code statut HTTP :
+
+* Un tableau de 3 éléments : <tt>[code statut (Fixnum), entêtes (Hash), corps
+  de la réponse (répondant à #each)]</tt>
+* Un tableau de 2 élements : <tt>[code statut (Fixnum), corps de la réponse
+  (répondant à #each)]</tt>
+* Un objet qui répond à <tt>#each</tt> et qui ne transmet que des chaînes de
+  caractères au bloc fourni
+* Un Fixnum représentant le code statut
+
+Avec cela, on peut facilement implémenter un streaming par exemple :
+
+    class Stream
+      def each
+        100.times { |i| yield "#{i}\n" }
+      end
+    end
+
+    get('/') { Stream.new }
+
+Vous pouvez aussi utiliser le helper +stream+ (présenté un peu plus loin) pour
+éviter la surcharge et intégrer le traitement relatif au streaming dans le bloc
+de code de la route.
+
+=== Masques de route spécifiques
+
+Comme cela a été vu auparavant, Sinatra offre la possibilité d'utiliser des
+masques sous forme de chaines de caractères ou des expressions régulières
+pour définir les routes. Mais il est possible de faire bien plus. Vous pouvez
+facilement définir vos propres masques :
+
+  class MasqueToutSauf
+    Masque = Struct.new(:captures)
+
+    def initialize(except)
+      @except   = except
+      @captures = Masque.new([])
+    end
+
+    def match(str)
+      @caputres unless @except === str
+    end
+  end
+
+  def tout_sauf(masque)
+    MasqueToutSauf.new(masque)
+  end
+
+  get tout_sauf("/index") do
+    # ...
+  end
+
+Notez que l'exemple ci-dessus est bien trop compliqué et que le même résultat
+peut être obtenu avec :
+
+  get // do
+    pass if request.path_info == "/index"
+    # ...
+  end
+
+Ou bien en utilisant la forme négative :
+
+  get %r{^(?!/index$)} do
+    # ...
+  end
+
+== Fichiers statiques
+
+Les fichiers du dossier <tt>./public</tt> sont servis de façon statique. Vous
+avez la possibilité d'utiliser un autre répertoire en définissant le paramètre
+<tt>:public_folder</tt> :
+
+  set :public_folder, File.dirname(__FILE__) + '/statique'
+
+Notez que le nom du dossier public n'apparait pas dans l'URL. Le fichier
+<tt>./public/css/style.css</tt> sera appelé via l'URL : 
+<tt>http://exemple.com/css/style.css</tt>.
+
+Utilisez le paramètre <tt>:static_cache_control</tt> pour ajouter l'information
+d'en-tête <tt>Cache-Control</tt> (voir plus loin).
+
+== Vues / Templates
+
+Chaqie langage de template est disponible via sa propre méthode de rendu,
+lesquelles renvoient tout simplement une chaîne de caractères.
+
+  get '/' do
+    erb :index
+  end
+
+Ceci effectue le rendu de la vue <tt>views/index.erb</tt>.
+
+Plutôt que d'utiliser le nom d'un template, vous pouvez directement passer
+le contenu du template :
+
+  get '/' do
+    code = "<%= Time.now %>"
+    erb code
+  end
+
+Les méthodes de templates acceptent un second paramètre, un hash d'options :
+
+  get '/' do
+    erb :index, :layout => :post
+  end
+
+Ceci effectuera le rendu de la vue <tt>views/index.erb</tt> en l'intégrant
+au +layout+ <tt>views/post.erb</tt> (les vues Erb sont intégrées par défaut
+au +layout+ <tt>views/layout.erb</tt> quand ce fichier existe).
+
+Toute option que Sinatra ne comprend pas sera passée au moteur de rendu :
+
+  get '/' do
+    haml :index, :format => :html5
+  end
+
+Vous pouvez également définir des options par langage de template de façon
+générale :
+
+  set :haml, :format => html5
+
+  get '/' do
+    haml :index
+  end
+
+Les options passées à la méthode de rendu prennent le pas sur les options
+définies au moyen de +set+.
+
+Options disponibles :
+
+[locals]
+  Liste de variables locales passées au document. Pratique pour les vues
+  partielles.
+  Exemple : <tt>erb "<%= foo %>", :locals => {:foo => "bar"}</tt>.
+
+[default_encoding]
+  Encodage de caractères à utiliser en cas d'incertitude. Par défaut, c'est
+  <tt>settings.default_encoding</tt>.
+
+[views]
+  Dossier de vues dans lequel chercher les templates. Par défaut
+  <tt>settings.views</tt>.
+
+[layout]
+  S'il faut ou non utiliser un +layout+ (+true+ or +false+). Indique le
+  template à utiliser lorsque c'est un symbole. Exemple : <tt>erb :index,
+  :layout => !request.xhr?</tt>.
+
+[content_type]
+  Content-Type que le template produit, dépend par défaut du langage de
+  template.
+
+[scope]
+  Contexte sous lequel effectuer le rendu du template. Par défaut il s'agit
+  de l'instance de l'application. Si vous changez cela, les variables
+  d'instance et les méthodes utilitaires ne seront pas disponibles.
+
+[layout_engine]
+  Moteur de rendu à utiliser pour le +layout+. Utile pour les langages ne
+  supportant pas les +layouts+. Il s'agit par défaut du moteur utilisé pour
+  le rendu du template. Exemple : <tt>set :rdoc, :layout_engine => :erb</tt>
+
+Les templates sont supposés se trouver directement dans le dossier
+<tt>./views</tt>. Pour utiliser un dossier de vues différent :
+
+  set :views, settings.root + '/templates'
+
+Il est important de se souvenir que les templates sont toujours référencés
+sous forme de symboles, même lorsqu'ils sont dans un sous-répertoire (dans
+ce cas, utilisez <tt>:'sous_repertoire/template'</tt>). Il faut utiliser
+un symbole car les méthodes de rendu évaluent le contenu des chaînes de
+caractères au lieu de les considérer comme un chemin vers un fichier.
+
+=== Langages de template disponibles
+
+Certains langages ont plusieurs implémentations. Pour préciser l'implémentation
+à utiliser (et garantir l'aspect thread-safe), vous devez simplement l'avoir
+chargée au préalable :
+
+  require 'rdiscount' # ou require 'bluecloth'
+  get('/') { markdown :index }
+
+=== Templates Haml
+
+Dépendances::             {haml}[http://haml-lang.com/]
+Extensions de fichier::   <tt>.haml</tt>
+Exemple::                 <tt>haml :index, :format => :html5</tt>
+
+=== Templates Erb
+
+Dépendances::             {erubis}[http://www.kuwata-lab.com/erubis/] ou
+                          erb (inclus avec Ruby)
+Extensions de fichier::   <tt>.erb</tt>, <tt>.rhtml</tt> ou <tt>.erubis</tt>
+                          (Erubis seulement)
+Exemple::                 <tt>erb :index</tt>
+
+=== Templates Builder
+
+Dépendances::             {builder}[http://builder.rubyforge.org/]
+Extensions de fichier::   <tt>.builder</tt>
+Exemple::                 <tt>builder { |xml| xml.em "salut" }</tt>
+
+Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).
+
+=== Templates Nokogiri
+
+Dépendances::             {nokogiri}[http://nokogiri.org/]
+Extensions de fichier::   <tt>.nokogiri</tt>
+Exemple::                 <tt>builder { |xml| xml.em "salut" }</tt>
+
+Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).
+
+=== Templates Sass
+
+Dépendances::             {sass}[http://sass-lang.com/]
+Extensions de fichier::   <tt>.sass</tt>
+Exemple::                 <tt>sass :stylesheet, :style => :expanded</tt>
+
+=== Templates SCSS
+
+Dépendances::             {sass}[http://sass-lang.com/]
+Extensions de fichier::   <tt>.scss</tt>
+Exemple::                 <tt>scss :stylesheet, :style => :expanded</tt>
+
+=== Templates Less
+
+Dépendances::             {less}[http://www.lesscss.org/]
+Extensions de fichier::   <tt>.less</tt>
+Exemple::                 <tt>less :stylesheet</tt>
+
+=== Templates Liquid
+
+Dépendances::             {liquid}[http://www.liquidmarkup.org/]
+Extensions de fichier::   <tt>.liquid</tt>
+Exemple::                 <tt>liquid :index, :locals => { :key => 'value' }</tt>
+
+Comme vous ne pouvez appeler de méthodes Ruby (autres que +yield+) dans un
+template Liquid, vous aurez sûrement à lui passer des variables locales.
+
+=== Templates Markdown
+
+Dépendances::             {rdiscount}[https://github.com/rtomayko/rdiscount],
+                          {redcarpet}[https://github.com/tanoku/redcarpet],
+                          {bluecloth}[http://deveiate.org/projects/BlueCloth],
+                          {kramdown}[http://kramdown.rubyforge.org/] *ou*
+                          {maruku}[http://maruku.rubyforge.org/]
+Extensions de fichier::   <tt>.markdown</tt>, <tt>.mkd</tt> et <tt>.md</tt>
+Exemple::                 <tt>markdown :index, :layout_engine => :erb</tt>
+
+Il n'est pas possible d'appeler des méthodes depuis markdown, ni de lui
+passer des variables locales. Par conséquent, il sera souvent utilisé en
+combinaison avec un autre moteur de rendu :
+
+  erb :overview, :locals => { :text => markdown(:introduction) }
+
+Notez que vous pouvez également appeler la méthode +markdown+ au sein d'autres
+templates :
+
+  %h1 Hello From Haml !
+  %p= markdown(:greetings)
+
+Comme vous ne pouvez pas appeler de Ruby au sein de Markdown, vous ne pouvez
+pas utiliser de +layouts+ écrits en Markdown. Toutefois, il est possible
+d'utiliser un moteur de rendu différent pour le template et pour le +layout+
+en utilisant l'option <tt>:layout_engine</tt>.
+
+=== Templates Textile
+
+Dépendances::             {RedCloth}[http://redcloth.org/]
+Extensions de fichier::   <tt>.textile</tt>
+Exemple::                 <tt>textile :index, :layout_engine => :erb</tt>
+
+Il n'est pas possible d'appeler des méthodes depuis textile, ni de lui
+passer des variables locales. Par conséquent, il sera souvent utilisé en
+combinaison avec un autre moteur de rendu :
+
+  erb :overview, :locals => { :text => textile(:introduction) }
+
+Notez que vous pouvez également appeler la méthode +textile+ au sein d'autres
+templates :
+
+  %h1 Hello From Haml !
+  %p= textile(:greetings)
+
+Comme vous ne pouvez pas appeler de Ruby au sein de Textile, vous ne pouvez
+pas utiliser de +layouts+ écrits en Textile. Toutefois, il est possible
+d'utiliser un moteur de rendu différent pour le template et pour le +layout+
+en utilisant l'option <tt>:layout_engine</tt>.
+
+=== Templates RDoc
+
+Dépendances::             {rdoc}[http://rdoc.rubyforge.org/]
+Extensions de fichier::   <tt>.rdoc</tt>
+Exemple::                 <tt>rdoc :README, :layout_engine => :erb</tt>
+
+Il n'est pas possible d'appeler des méthodes depuis rdoc, ni de lui
+passer des variables locales. Par conséquent, il sera souvent utilisé en
+combinaison avec un autre moteur de rendu :
+
+  erb :overview, :locals => { :text => rdoc(:introduction) }
+
+Notez que vous pouvez également appeler la méthode +rdoc+ au sein d'autres
+templates :
+
+  %h1 Hello From Haml !
+  %p= rdoc(:greetings)
+
+Comme vous ne pouvez pas appeler de Ruby au sein de RDoc, vous ne pouvez
+pas utiliser de +layouts+ écrits en RDoc. Toutefois, il est possible
+d'utiliser un moteur de rendu différent pour le template et pour le +layout+
+en utilisant l'option <tt>:layout_engine</tt>.
+
+=== Templates Radius
+
+Dépendances::             {radius}[http://radius.rubyforge.org/]
+Extensions de fichier::   <tt>.radius</tt>
+Exemple::                 <tt>radius :index, :locals => { :key => 'value' }</tt>
+
+Comme vous ne pouvez pas appeler de méthodes Ruby depuis un template Radius,
+vous aurez sûrement à lui passer des variables locales.
+
+=== Templates Markaby
+
+Dépendances::             {markaby}[http://markaby.github.com/]
+Extensions de fichier::   <tt>.mab</tt>
+Exemple::                 <tt>markaby { h1 "Bienvenue !" }</tt>
+
+Ce moteur accepte également un bloc pour des templates en ligne (voir exemple).
+
+=== Templates Slim
+
+Dépendances::             {slim}[http://slim-lang.com/]
+Extensions de fichier::   <tt>.slim</tt>
+Exemple::                 <tt>slim :index</tt>
+
+=== Templates Creole
+
+Dépendances::             {creole}[https://github.com/minad/creole]
+Extensions de fichier::   <tt>.creole</tt>
+Exemple::                 <tt>creole :wiki, :layout_engine => :erb</tt>
+
+Il n'est pas possible d'appeler des méthodes depuis creole, ni de lui
+passer des variables locales. Par conséquent, il sera souvent utilisé en
+combinaison avec un autre moteur de rendu :
+
+  erb :overview, :locals => { :text => creole(:introduction) }
+
+Notez que vous pouvez également appeler la méthode +creole+ au sein d'autres
+templates :
+
+  %h1 Hello From Haml !
+  %p= creole(:greetings)
+
+Comme vous ne pouvez pas appeler de Ruby au sein de Creole, vous ne pouvez
+pas utiliser de +layouts+ écrits en Creole. Toutefois, il est possible
+d'utiliser un moteur de rendu différent pour le template et pour le +layout+
+en utilisant l'option <tt>:layout_engine</tt>.
+
+=== Templates CoffeeScript
+
+Dépendances::             {coffee-script}[https://github.com/josh/ruby-coffee-script]
+                          et un {moyen d'exécuter javascript}[https://github.com/sstephenson/execjs/blob/master/README.md#readme]
+Extensions de fichier::   <tt>.coffee</tt>
+Exemple::                 <tt>coffee :index</tt>
+
+=== Templates embarqués
+
+  get '/' do
+    haml '%div.title Bonjour le monde'
+  end
+
+Générera le code du template spécifié dans la chaîne de caractères.
+
+=== Accéder aux variables dans un Template
+
+Un template est évalué dans le même contexte que l'endroit d'où il a été
+appelé (gestionnaire de route). Les variables d'instance déclarées dans le
+gestionnaire de route sont directement accessibles dans le template :
+
+  get '/:id' do
+    @foo = Foo.find(params[:id])
+    haml '%h1= @foo.nom'
+  end
+
+Alternativement, on peut passer un hash contenant des variables locales :
+
+  get '/:id' do
+    foo = Foo.find(params[:id])
+    haml '%h1= foo.nom', :locals => { :foo => foo }
+  end
+
+Ceci est généralement utilisé lorsque l'on veut utiliser un template comme
+partiel (depuis un autre template) et qu'il est donc nécessaire d'adapter les
+noms de variables.
+
+=== Templates dans le fichier source
+
+Des templates peuvent être définis dans le fichier source comme ceci :
+
+  require 'sinatra'
+
+  get '/' do
+    haml :index
+  end
+
+  __END__
+
+  @@ layout
+  %html
+    = yield
+
+  @@ index
+  %div.title Bonjour le monde !
+
+NOTE : Les templates du fichier source qui contient <tt>require 'sinatra'</tt>
+sont automatiquement chargés. Si vous avez des templates dans d'autres
+fichiers source, il faut explicitement les déclarer avec
+<tt>enable :inline_templates</tt>.
+
+=== Templates nommés
+
+Les templates peuvent aussi être définis grâce à la méthode de haut niveau
+<tt>template</tt> :
+
+  template :layout do
+    "%html\n  =yield\n"
+  end
+
+  template :index do
+    '%div.title Bonjour le monde !'
+  end
+
+  get '/' do
+    haml :index
+  end
+
+Si un template nommé "layout" existe, il sera utilisé à chaque fois qu'un
+template sera affiché. Vous pouvez désactivez les layouts au cas par cas en
+passant <tt>:layout => false</tt> ou bien les désactiver par défaut au moyen
+de <tt>set :haml, :layout => false</tt> :
+
+  get '/' do
+    haml :index, :layout => !request.xhr?
+  end
+
+=== Associer des extensions de fichier
+
+Pour associer une extension de fichier avec un moteur de rendu, utilisez
+<tt>Tilt.register</tt>. Par exemple, si vous désirez utiliser l'extension
+de fichier +tt+ pour les templates Textile, vous pouvez faire comme suit :
+
+  Tilt.register :tt, Tilt[:textile]
+
+=== Ajouter son propre moteur de rendu
+
+En premier lieu, déclarez votre moteur de rendu avec Tilt, ensuite créez
+votre méthode de rendu :
+
+  Tilt.register :monmoteur, MonMerveilleurMoteurDeRendu
+
+  helpers do
+    def monmoteur(*args) render(:monmoteur, *args) end
+  end
+
+  get '/' do
+    monmoteur :index
+  end
+
+Utilisera <tt>./views/index.monmoteur</tt>. Voir
+https://github.com/rtomayko/tilt pour en savoir plus sur Tilt.
+
+== Filtres
+
+Un filtre <tt>before</tt> est évalué avant n'importe quelle requête, dans le
+contexte de celle-ci, et peut modifier la requête ou la réponse. Les variables
+d'instance déclarées dans le filtre sont accessibles au gestionnaire de route
+et au template :
+
+  before do
+    @note = 'Coucou !'
+    request.path_info = '/foo/bar/baz'
+  end
+
+  get '/foo/*' do
+    @note #=> 'Coucou !'
+    params[:splat] #=> 'bar/baz'
+  end
+
+Un filtre <tt>after</tt> est évalué après chaque requête, dans le contexte
+de celle-ci et peut également modifier la requête et/ou la réponse. Toutes les
+variables d'instance déclarées dans un filtre <tt>before</tt> et dans le
+gestionnaire de route sont accessibles dans le filtre <tt>after</tt> :
+
+  after do
+    puts response.status
+  end
+
+Note : Sauf si vous utilisez la méthode +body+ au lieu de renvoyer une chaîne
+de caractères dans vos gestionnaires de routes, le corps de la réponse ne sera
+pas disponible dans le filtre <tt>after</tt>, étant donné qu'il est généré
+plus tard.
+
+En option, on peut passer un masque au filtre, ce qui le rend actif uniquement
+si la requête correspond au masque en question :
+
+  before '/secret/*' do
+    authentification!
+  end
+
+  after '/faire/:travail' do |travail|
+    session[:dernier_travail] = travail
+  end
+
+Tout comme les routes, les filtres acceptent également les conditions :
+
+  before :agent => /Songbird/ do
+    # ...
+  end
+
+  after '/blog/*', :host_name => 'example.com' do
+    # ...
+  end
+
+== Helpers
+
+Utilisez la méthode de haut niveau <tt>helpers</tt> pour définir des routines
+qui seront accessibles dans vos gestionnaires de route et dans vos templates :
+
+  helpers do
+    def bar(nom)
+      "#{nom}bar"
+    end
+  end
+
+  get '/:nom' do
+    bar(params[:nom])
+  end
+
+=== Utiliser les sessions
+
+Une session est utilisée pour conserver un état entre les requêtes. Une fois
+activées, vous avez un +hash+ de session par session utilisateur :
+
+  enable :sessions
+
+  get '/' do
+    "valeur = " << session[:valeur].inspect
+  end
+
+  get '/:value' do
+    session[:valeur] = params[:valeur]
+  end
+
+Notez que <tt>enable :sessions</tt> enregistre en fait toutes les données dans
+un +cookie+. Ce n'est pas toujours ce que vous voulez (enregistrer beaucoup de
+données va augmenter le traffic par exemple). Vous pouvez utiliser n'importe
+quel +middleware+ Rack de session afin d'éviter cela. N'utiliser *pas*
+<tt>enable :sessions</tt> dans ce cas mais charger le +middleware+ de votre
+choix comme vous le feriez pour n'importe quel autre +middleware+ :
+
+  use Rack::Session::Pool, :expire_after => 2592000
+
+  get '/' do
+    "valeur = " << session[:valeur].inspect
+  end
+
+  get '/:value' do
+    session[:valeur] = params[:valeur]
+  end
+
+Pour renforcer la sécurité, les données de session dans le cookie sont signées
+avec une clé secrète de session. Une clé secrète est générée pour vous au
+hasard par Sinatra. Toutefois, comme cette clé change à chaque démarrage de
+votre application, vous pouvez définir cette clé vous-même afin que toutes
+les instances de votre application la partage :
+
+  set :session_secret, 'super secret'
+
+Si vous souhaitez avoir plus de contrôle, vous pouvez également enregistrer un
++hash+ avec des options lors de la configuration de +sessions+ :
+
+  set :sessions, :domain => 'foo.com'
+
+=== Halt
+
+Pour arrêter immédiatement la requête dans un filtre ou un gestionnaire de
+route :
+
+  halt
+
+Vous pouvez aussi passer le code retour ...
+
+  halt 410
+
+Ou le texte ...
+
+  halt 'Ceci est le texte'
+
+Ou les deux ...
+
+  halt 401, 'Partez !'
+
+Ainsi que les entêtes ...
+
+  halt 402, {'Content-Type' => 'text/plain'}, 'revanche'
+
+Bien sûr il est possible de combiner un template avec +halt+ :
+
+  halt erb(:erreur)
+
+=== Passer
+
+Une route peut passer le relais aux autres routes qui correspondent également
+avec <tt>pass</tt> :
+
+  get '/devine/:qui' do
+    pass unless params[:qui] == 'Frank'
+    "Tu m'as eu !"
+  end
+
+  get '/devine/*' do
+    'Manqué !'
+  end
+
+On sort donc immédiatement de ce gestionnaire et on continue à chercher,
+dans les masques suivants, le prochain qui correspond à la requête.
+Si aucun des masques suivants ne correspond, un code 404 est retourné.
+
+=== Déclencher une autre route
+
+Parfois, +pass+ n'est pas ce que vous recherchez, au lieu de cela vous
+souhaitez obtenir le résultat d'une autre route. Pour cela, utilisez
+simplement +call+ :
+
+  get '/foo' do
+    status, headers, body = call env.merge("PATH_INFO" => '/bar')
+    [status, headers, body.map(&:upcase)]
+  end
+
+  get '/bar' do
+    "bar"
+  end
+
+Notez que dans l'exemple ci-dessus, vous faciliterez les tests et améliorerez
+la performance en déplaçant simplement <tt>"bar"</tt> dans un +helper+
+utilisé à la fois par <tt>/foo</tt> et <tt>/bar</tt>.
+
+Si vous souhiatez que la requête soit envoyée à la même instance de
+l'application plutôt qu'à une copie, utilisez <tt>call!</tt> au lieu de
+<tt>call</tt>.
+
+Lisez la spécification Rack si vous souhaitez en savoir plus sur
+<tt>call</tt>.
+
+=== Définir le corps, le code retour et les entêtes
+
+Il est possible et recommandé de définir le code retour et le corps de la
+réponse au moyen de la valeur de retour d'un bloc définissant une route.
+Quoiqu'il en soit, dans certains cas vous pourriez avoir besoin de définir
+le coprs de la réponse à un moment arbitraire de l'exécution. Vous pouvez le
+faire au moyen de la méthode +body+. Si vous faites ainsi, vous pouvez alors
+utiliser cette même méthode pour accéder au corps de la réponse :
+
+  get '/foo' do
+    body "bar"
+  end
+
+  after do
+    puts body
+  end
+
+Il est également possible de passer un bloc à +body+, qui sera exécuté par le
+gestionnaire Rack (ceci peut être utilisé pour implémenter un +streaming+,
+voir "Valeurs de retour").
+
+Pareillement au corps de la réponse, vous pouvez également définir le code
+retour et les entêtes :
+
+  get '/foo' do
+    status 418
+    headers \
+      "Allow"   => "BREW, POST, GET, PROPFIND, WHEN",
+      "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
+    body "Je suis une théière !"
+  end
+
+Comme +body+, +headers+ et +status+ peuvent être utilisés sans arguments
+pour accéder à leurs valeurs.
+
+=== Faire du streaming
+
+Il y a des cas où vous voulez commencer à renvoyer des données pendant que
+vous êtes en train de générer le reste de la réponse. Dans les cas les plus
+extrèmes, vous souhaitez continuer à envoyer des données tant que le client
+n'abandonne pas la connection. Vous pouvez alors utiliser le helper +stream+
+pour éviter de créer votre propre système :
+
+  get '/' do
+    stream do |out|
+      out << "Ca va être hallu -\n"
+      sleep 0.5
+      out << " (attends la suite) \n"
+      sleep 1
+      out << "- cinant !\n"
+    end
+  end
+
+Cela permet d'implémenter des API de streaming ou de
+{Server Sent Events}[http://dev.w3.org/html5/eventsource/] et peut servir de
+base pour des {WebSockets}[http://en.wikipedia.org/wiki/WebSocket]. Vous
+pouvez aussi l'employer pour augmenter le débit quand une partie du contenu
+provient d'une resource lente.
+
+Le fonctionnement du streaming, notamment le nombre de requêtes simultanées,
+dépend énormément du serveur web utilisé. Certains ne prennent pas du tout en
+charge le streaming (WEBRick par exemple). Lorsque le serveur ne gère pas le
+streaming, la partie body de la réponse sera envoyée au client en une seule
+fois, après que l'exécution du bloc passé au helper +stream+ sera terminée.
+
+En utilisant le helper +stream+ avec le paramètre +keep_open+, il n'appelera
+pas la méthode +close+ du flux, vous laissant la possibilité de le fermer à
+tout moment au cours de l'exécution. Ceci ne fonctionne qu'avec les serveurs
+evented (ie non threadés) tels que Thin et Rainbows. Les autres serveurs
+fermeront malgré tout le flux.
+
+  set :server, :thin
+  connections = []
+
+  get '/' do
+    # conserve le flux ouvert
+    stream(:keep_open) { |out| connections << out }
+  end
+
+  post '/' do
+    # écrit dans tous les flux ouverts
+    connections.each { |out| out << params[:message] << "\n" }
+    "message sent"
+  end
+
+=== Journalisation (Logging)
+
+Dans le contexte de la requête, la méthode utilitaire +logger+ expose une
+instance de +logger+ :
+
+  get '/' do
+    logger.info "chargement des données"
+    # ...
+  end
+
+Ce +logger+ va automatiquement prendre en compte les paramètres de
+configuration pour la journalisation de votre gestionnaire Rack. Si la
+journalisation est désactivée, cette méthode renverra un objet factice et
+vous n'avez pas à vous en inquiéter dans vos routes en le filtrant.
+
+Notez que la journalisation est seulement activée par défaut pour
+<tt>Sinatra::Application</tt>, donc si vous héritez de <tt>Sinatra::Base</tt>,
+vous aurez à l'activer vous-même :
+
+  class MonApp < Sinatra::Base
+    configure(:production, :development) do
+      enable :logging
+    end
+  end
+
+=== Types Mime
+
+Quand vous utilisez <tt>send_file</tt> ou des fichiers statiques, vous
+pouvez rencontrer des types mime que Sinatra ne connaît pas. Utilisez
++mime_type+ pour les déclarer par extension de fichier :
+
+  configure do
+    mime_type :foo, 'text/foo'
+  end
+
+Vous pouvez également les utiliser avec la méthode +content_type+ :
+
+  get '/' do
+    content_type :foo
+    "foo foo foo"
+  end
+
+=== Former des URLs
+
+Pour former des URLs, vous devriez utiliser la méthode +url+, par exemple en
+Haml :
+
+  %a{:href => url('/foo')} foo
+
+Cela prend en compte les proxy inverse et les routeurs Rack, s'ils existent.
+
+Cette méthode est également disponible sous l'alias +to+ (voir ci-dessous
+pour un exemple).
+
+=== Redirection du navigateur
+
+Vous pouvez déclencher une redirection du navigateur avec la méthode
++redirect+ :
+
+  get '/foo' do
+    redirect to('/bar')
+  end
+
+Tout paramètre additionnel est géré comme des arguments pour la méthode
++halt+ :
+
+  redirect to('/bar'), 303
+  redirect 'http://google.com', 'mauvais endroit mon pote'
+
+Vous pouvez aussi rediriger vers la page dont l'utilisateur venait au moyen de
+<tt>redirect back</tt> :
+
+  get '/foo' do
+    "<a href='/bar'>faire quelque chose</a>"
+  end
+
+  get '/bar' do
+    faire_quelque_chose
+    redirect back
+  end
+
+Pour passer des arguments à une redirection, ajoutez-les soit à la requête :
+
+  redirect to('/bar?sum=42')
+
+Ou bien utilisez une session :
+
+  enable :sessions
+
+  get '/foo' do
+    session[:secret] = 'foo'
+    redirect to('/bar')
+  end
+
+  get '/bar' do
+    session[:secret]
+  end
+
+=== Contrôle du cache
+
+Définir correctement vos entêtes à la base pour un bon cache HTTP.
+
+Vous pouvez facilement définir l'entête Cache-Control de la manière suivante :
+
+  get '/' do
+    cache_control :public
+    "met le en cache !"
+  end
+
+Conseil de pro : définir le cache dans un filtre +before+ :
+
+  before do
+    cache_control :public, :must_revalidate, :max_age => 60
+  end
+
+Si vous utilisez la méthode +expires+ pour définir l'entête correspondant,
+<tt>Cache-Control</tt> sera alors défini automatiquement :
+
+  before do
+    expires 500, :public, :must_revalidate
+  end
+
+Pour utiliser correctement les caches, vous devriez utiliser +etag+ ou
++last_modified+. Il est recommandé d'utiliser ces méthodes *avant* de faire
+d'importantes modifications, car elles vont immédiatement déclencher la réponse
+si le client a déjà la version courante dans son cache :
+
+  get '/article/:id' do
+    @article = Article.find params[:id]
+    last_modified @article.updated_at
+    etag @article.sha1
+    erb :article
+  end
+
+Il est également possible d'utiliser un
+{weak ETag}[http://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation] :
+
+  etag @article.sha1, :weak
+
+Ces méthodes ne sont pas chargées de mettre des données en cache, mais elles
+fournissent les informations nécessaires pour votre cache. Si vous êtes à la
+recherche de solutions rapides pour un reverse-proxy de cache, essayez
+{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
+
+=== Envoyer des fichiers
+
+Pour envoyer des fichiers, vous pouvez utiliser la méthode
+<tt>send_file</tt> :
+
+  get '/' do
+    send_file 'foo.png'
+  end
+
+Quelques options sont également acceptées :
+
+  send_file 'foo.png', :type => :jpg
+
+Les options sont :
+
+[filename]
+  le nom du fichier dans la réponse, par défaut le nom du fichier envoyé.
+
+[last_modified]
+  valeur pour l'entête Last-Modified, par défaut la date de modification du
+  fichier
+
+[type]
+  type de contenu à utiliser, deviné à partir de l'extension de fichier si
+  absent
+
+[disposition]
+  utilisé pour Content-Disposition, les valuers possibles étant : +nil+ (par
+  défaut), <tt>:attachment</tt> et <tt>:inline</tt>
+
+[length]
+  entête Content-Length, par défaut la taille du fichier
+
+Si le gestionnaire Rack le supporte, d'autres moyens que le +streaming+ via le
+processus Ruby seront utilisés. Si vous utilisez cette méthode, Sinatra gérera
+automatiquement les requêtes de type +range+.
+
+=== Accéder à l'objet requête
+
+L'objet correspondant à la requête envoyée peut être récupéré dans le contexte
+de la requête (filtres, routes, gestionnaires d'erreur) au moyen de la méthode
++request+ :
+
+  # application tournant à l'adresse http://exemple.com/exemple
+  get '/foo' do
+    t = %w[text/css text/html application/javascript]
+    request.accept              # ['text/html', '*/*']
+    request.accept? 'text/xml'  # true
+    request.preferred_type(t)   # 'text/html'
+    request.body                # corps de la requête envoyée par le client
+                                # (voir ci-dessous)
+    request.scheme              # "http"
+    request.script_name         # "/exemple"
+    request.path_info           # "/foo"
+    request.port                # 80
+    request.request_method      # "GET"
+    request.query_string        # ""
+    request.content_length      # taille de request.body
+    request.media_type          # type de média pour request.body
+    request.host                # "exemple.com"
+    request.get?                # true (méthodes similaires pour les autres
+                                # verbes HTTP)
+    request.form_data?          # false
+    request["UN_ENTETE"]        # valeur de l'entête UN_ENTETE
+    request.referer             # référant du client ou '/'
+    request.user_agent          # user agent (utilisé par la condition :agent)
+    request.cookies             # tableau contenant les cookies du navigateur
+    request.xhr?                # requête AJAX ?
+    request.url                 # "http://exemple.com/exemple/foo"
+    request.path                # "/exemple/foo"
+    request.ip                  # adresse IP du client
+    request.secure?             # false
+    request.forwarded?          # vrai (si on est derrière un proxy inverse)
+    request.env                 # tableau brut de l'environnement fourni par
+                                # Rack
+  end
+
+Certaines options, telles que <tt>script_name</tt> ou <tt>path_info</tt>
+peuvent également être modifiées :
+
+  before { request.path_info = "/" }
+
+  get "/" do
+    "toutes les requêtes arrivent ici"
+  end
+
+<tt>request.body</tt> est un objet IO ou StringIO :
+
+  post "/api" do
+    request.body.rewind  # au cas où il a déjà été lu
+    donnees = JSON.parse request.body.read
+    "Bonjour #{donnees['nom']} !"
+  end
+
+=== Fichiers joints
+
+Vous pouvez utiliser la méthode +attachment+ pour indiquer au navigateur que
+la réponse devrait être stockée sur le disque plutôt qu'affichée :
+
+  get '/' do
+    attachment
+    "enregistre-le !"
+  end
+
+Vous pouvez également lui passer un nom de fichier :
+
+  get '/' do
+    attachment "info.txt"
+    "enregistre-le !"
+  end
+
+=== Gérer Date et Time
+
+Sinatra fourni un helper +time_for+ pour convertir une valeur donnée en
+objet +Time+. Il peut aussi faire la conversion à partir d'objets +DateTime+,
++Date+ ou de classes similaires.
+
+  get '/' do
+    pass if Time.now > time_for('Dec 23, 2012')
+    "encore temps"
+  end
+
+Cette méthode est utilisée en interne par +expires+, +last_modified+ et
+consorts. Par conséquent, vous pouvez très facilement étendre le
+fonctionnement de ces méthodes en surchargeant le helper +time_for+ dans
+votre application :
+
+  helpers do
+    def time_for(value)
+      case value
+      when :yesterday then Time.now - 24*60*60
+      when :tomorrow  then Time.now + 24*60*60
+      else super
+      end
+    end
+  end
+
+  get '/' do
+    last_modified :yesterday
+    expires :tomorrow
+    "salut"
+  end
+
+=== Chercher les fichiers de templates
+
+La méthode <tt>find_template</tt> est utilisée pour trouver les fichiers de
+templates à générer :
+
+  find_template settings.views, 'foo', Tilt[:haml] do |file|
+    puts "pourrait être #{file}"
+  end
+
+Ce n'est pas très utilise. En revanche, il est utile de pouvoir surcharger
+cette méthode afin de définir son propre mécanisme de recherche. Par exemple,
+vous pouvez utiliser plus d'un répertoire de vues :
+
+  set :views, ['views', 'templates']
+
+  helpers do
+    def find_template(views, name, engine, &block)
+      Array(views).each { |v| super(v, name, engine, &block) }
+    end
+  end
+
+Un autre exemple est d'utiliser des répertoires différents pour des moteurs
+de rendu différents :
+
+  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
+
+Vous pouvez également écrire cela dans une extension et la partager avec
+d'autres !
+
+Notez que <tt>find_template</tt> ne vérifie pas que le fichier existe mais
+va plutôt exécuter le bloc pour tous les chemins possibles. Cela n'induit pas
+un problème de performance dans le sens où +render+ va utiliser +break+ dès
+qu'un fichier est trouvé. De plus, l'emplacement des templates (et leur
+contenu) est mis en cache si vous n'êtes pas en mode développement. Vous
+devriez garder cela en tête si vous écrivez une méthode vraiment dingue.
+
+== Configuration
+
+Lancé une seule fois au démarrage de tous les environnements :
+
+  configure do
+    # définir un paramètre
+    set :option, 'value'
+
+    # définir plusieurs paramètre
+    set :a => 1, :b => 2
+
+    # identique à "set :option, true"
+    enable :option
+
+    # identique à "set :option, false""
+    disable :option
+
+    # vous pouvez également avoir des paramètres dynamiques avec des blocs
+    set(:css_dir) { File.join(views, 'css') }
+  end
+
+Lancé si l'environnement (variable d'environnement RACK_ENV) est défini comme
+<tt>:production</tt> :
+
+  configure :production do
+    ...
+  end
+
+Lancé si l'environnement est <tt>:production</tt> ou
+<tt>:test</tt> :
+
+  configure :production, :test do
+    ...
+  end
+
+Vous pouvez accéder à ces paramètres via <tt>settings</tt> :
+
+  configure do
+    set :foo, 'bar'
+  end
+
+  get '/' do
+    settings.foo? # => true
+    settings.foo  # => 'bar'
+    ...
+  end
+
+=== Paramètres disponibles
+
+[absolute_redirects]  Si désactivé, Sinatra permettra les redirections
+                      relatives. Toutefois, Sinatra ne sera plus conforme à la
+                      RFC 2616 (HTTP 1.1), qui n'autorise que les redirections
+                      absolues.
+
+                      Activez si votre application tourne derrière un proxy
+                      inverse qui n'a pas été correctement configuré. Notez
+                      que la méthode +url+ continuera de produire des URLs
+                      absolues, sauf si vous lui passez +false+ comme second
+                      argument.
+
+                      Désactivé par défaut.
+
+[add_charsets]        types mime pour lesquels la méthode
+                      <tt>content_type</tt> va automatiquement ajouter
+                      l'information du +charset+.
+
+                      Vous devriez lui ajouter des valeurs plutôt que de
+                      l'écraser :
+
+                        settings.add_charsets << "application/foobar"
+
+[app_file]            fichier de l'application principale, utilisé pour
+                      détecterla racine du projet, le dossier public et le
+                      dossier de vues ainsi que pour les templates en ligne.
+
+[bind]                adresse IP sur laquelle se brancher
+                      (par défaut : 0.0.0.0).
+                      Utiliser seulement pour le serveur intégré.
+
+[default_encoding]    encodage à utiliser si inconnu (par défaut
+                      <tt>"utf-8"</tt>).
+
+[dump_errors]         afficher les erreurs dans le +log+.
+
+[environment]         environnement courant, par défaut
+                      <tt>ENV['RACK_ENV']</tt>, ou
+                      <tt>"development"</tt> si absent.
+
+[logging]             utiliser le +logger+.
+
+[lock]                Place un +lock+ autour de chaque requête, n'exécutant
+                      donc qu'une seule requête par processus Ruby.
+
+                      Activé si votre application n'est pas +thread-safe+.
+                      Désactivé par défaut.
+
+[method_override]     utilise la magie de <tt>_method</tt> afin de permettre
+                      des formulaires put/delete dans des navigateurs qui ne
+                      le permettent pas.
+
+[port]                port à écouter. Utiliser seulement pour le serveur
+                      intégré.
+
+[prefixed_redirects]  si oui ou non <tt>request.script_name</tt> doit être
+                      inséré dans les redirections si un chemin non absolu
+                      est utilisé. Ainsi, <tt>redirect '/foo'</tt> se
+                      comportera comme <tt>redirect to('/foo')</tt>.
+                      Désactivé par défaut.
+
+[public_folder]       dossier duquel les fichiers publics sont servis
+
+[reload_templates]    si oui ou non les templates doivent être rechargés
+                      entre les requêtes. Activé en mode développement.
+
+[root]                dossier racine du projet.
+
+[raise_errors]        soulever les erreurs (ce qui arrêtera l'application).
+
+[run]                 si activé, Sinatra s'occupera de démarrer le serveur,
+                      ne pas activer si vous utiliser rackup ou autres.
+
+[running]             est-ce que le serveur intégré est en marche ?
+                      ne changez pas ce paramètre !
+
+[server]              serveur ou liste de serveurs à utiliser pour le serveur
+                      intégré.
+                      Par défaut ['thin', 'mongrel', 'webrick'], l'ordre
+                      indiquant la priorité.
+
+[sessions]            active l'enregistrement des sessions en utilisant les
+                      cookies.
+
+[show_exceptions]     affiche la trace de l'erreur dans le navigateur.
+
+[static]              Si oui ou non Sinatra doit s'occuper de servir les
+                      fichiers statiques.
+                      Désactivez si vous utilisez un serveur capable de le
+                      gérer lui même. Le désactiver augmentera la performance.
+                      Activé par défaut pour le style classique, désactivé pour
+                      le style modulaire.
+
+[threaded]            à définir à +true+ pour indiquer à Thin d'utiliser
+                      <tt>EventMachine.defer</tt> pour traiter la requête.
+
+[views]               dossier des vues.
+
+== Gérer les erreurs
+
+Les gestionnaires d'erreur s'exécutent dans le même contexte que les routes ou
+les filtres, ce qui veut dire que vous avez accès (entre autres) aux bons
+vieux <tt>haml</tt>, <tt>erb</tt>, <tt>halt</tt>, etc.
+
+=== NotFound
+
+Quand une exception <tt>Sinatra::NotFound</tt> est soulevée, ou que le code
+retour est 404, le gestionnaire <tt>not_found</tt> est invoqué :
+
+  not_found do
+    'Pas moyen de trouver ce que vous cherchez'
+  end
+
+=== Error
+
+Le gestionnaire +error+ est invoqué à chaque fois qu'une exception est
+soulevée dans une route ou un filtre. L'objet exception est accessible via la
+variable Rack <tt>sinatra.error</tt> :
+
+  error do
+    'Désolé mais une méchante erreur est survenue - ' + env['sinatra.error'].name
+  end
+
+Erreur sur mesure :
+
+  error MonErreurSurMesure do
+    'Donc il est arrivé ceci...' + env['sinatra.error'].message
+  end
+
+Donc si ceci arrive :
+
+  get '/' do
+    raise MonErreurSurMesure, 'quelque chose de mal'
+  end
+
+Vous obtenez ça :
+
+  Donc il est arrivé ceci... quelque chose de mal
+
+Alternativement, vous pouvez avoir un gestionnaire d'erreur associé à un code
+particulier :
+
+  error 403 do
+    'Accès interdit'
+  end
+
+  get '/secret' do
+    403
+  end
+
+Ou un intervalle :
+
+  error 400..510 do
+    'Boom'
+  end
+
+Sinatra installe pour vous quelques gestionnaires <tt>not_found</tt> et
+<tt>error</tt> génériques lorsque vous êtes en environnement
+<tt>development</tt>.
+
+== Les Middlewares Rack
+
+Sinatra tourne avec Rack[http://rack.rubyforge.org/], une interface standard
+et minimale pour les web frameworks Ruby. Un des points forts de Rack est le
+support de ce que l'on appelle des "middlewares" -- composant qui vient se
+situer entre le serveur et votre application, et dont le but est de
+visualiser/manipuler la requête/réponse HTTP, et d'offrir diverses
+fonctionnalités classiques.
+
+Sinatra permet de construire facilement des middlewares Rack via la méthode de
+haut niveau +use+ :
+
+  require 'sinatra'
+  require 'mon_middleware_perso'
+
+  use Rack::Lint
+  use MonMiddlewarePerso
+
+  get '/bonjour' do
+    'Bonjour le monde'
+  end
+
+La sémantique de +use+ est identique à celle définie dans le DSL de
+Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html]
+(le plus souvent utilisé dans un fichier rackup). Par exemple, la méthode
++use+ accepte divers arguments ainsi que des blocs :
+
+  use Rack::Auth::Basic do |login, password|
+    login == 'admin' && password == 'secret'
+  end
+
+Rack est distribué avec une bonne variété de middlewares standards pour les
+logs, débuguer, faire du routage URL, de l'authentification, gérer des
+sessions. Sinatra utilise beaucoup de ces composants automatiquement via la
+configuration, donc pour ceux-ci vous n'aurez pas à utiliser la méthode +use+.
+
+== Tester
+
+Les tests pour Sinatra peuvent être écrit avec n'importe quelle bibliothèque
+basée sur Rack. {Rack::Test}[http://gitrdoc.com/brynary/rack-test] est
+recommandé :
+
+  require 'mon_application_sinatra'
+  require 'test/unit'
+  require 'rack/test'
+
+  class MonTest < Test::Unit::TestCase
+    include Rack::Test::Methods
+
+    def app
+      Sinatra::Application
+    end
+
+    def test_ma_racine
+      get '/'
+      assert_equal 'Bonjour le monde !', last_response.body
+    end
+
+    def test_avec_des_parametres
+      get '/rencontrer', :name => 'Frank'
+      assert_equal 'Salut Frank !', last_response.body
+    end
+
+    def test_avec_rack_env
+      get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
+      assert_equal "Vous utilisez Songbird !", last_response.body
+    end
+  end
+
+== Sinatra::Base - Les Middlewares, les Bibliothèques, et les Applications Modulaires
+
+Définir votre application au niveau supérieur fonctionne bien pour les
+micro-applications, mais peut s'avérer moins pratique lorsqu'il s'agit
+de créer des composants réutilisables comme des middlewares Rack, faire
+du Rails metal, ou de simples bibliothèques avec un composant serveur, ou
+même une extension pour Sinatra. Le DSL de haut niveau pollue l'espace de noms
+et est une configuration adaptée à une micro-application (un fichier unique
+pour l'application, les dossiers <tt>./public</tt> et <tt>./views</tt>, les
+logs, pages d'erreur, etc.). C'est là que <tt>Sinatra::Base</tt> entre en jeu :
+
+  require 'sinatra/base'
+
+  class MonApplication < Sinatra::Base
+    set :sessions, true
+    set :foo, 'bar'
+
+    get '/' do
+      'Bonjour le monde !'
+    end
+  end
+
+Les méthodes disponibles dans <tt>Sinatra::Base</tt> sont exactement identiques
+à celles disponibles dans le DSL de haut niveau. La plupart des applications
+de haut niveau peuvent être converties en composant <tt>Sinatra::Base</tt> avec
+deux modifications :
+
+* Votre fichier doit charger +sinatra/base+ au lieu de +sinatra+ ;
+  autrement, toutes les méthodes de la DSL seront chargées dans l'espace
+  de noms.
+* Mettre vos gestionnaires de route, vos gestionnaires d'erreur, vos filtres
+  et options dans une sous-classe de <tt>Sinatra::Base</tt>.
+
+<tt>Sinatra::Base</tt> est plutôt épuré. La plupart des options sont
+désactivées par défaut, ceci inclus le serveur. Voir {Options et
+Configuration}[http://sinatra.github.com/configuration.html]
+pour plus de détails sur les options et leur comportement.
+
+=== Style modulaire vs. style classique
+
+Contrairement aux croyanaces, le style classique n'a rien de mauvais. Si cela
+convient à votre application, vous n'avez pas à changer pour une application
+modulaire.
+
+Il n'y a que deux inconvénient au style classique comparé au style modulaire :
+
+* Vous ne pouvez avoir qu'une seule application Sinatra par processus Ruby. Si
+  vous envisagez d'en utiliser plus, passez au style modulaire
+
+* Le style classique pollue  la classe Object avec des méthodes déléguantes.
+  Si vous prévoyez de diffuser votre application dans une bibliothèque/gem,
+  passez au style modulaire.
+
+Il n'y pas d'empêchement à mélanger style classic et style modulaire.
+
+Si vous passez d'un style à l'autre, vous devriez être vigilant à quelques
+légères différences dans les paramètres par défaut :
+
+  Paramètre           Classique                     Modulaire
+
+  app_file            fichier chargeant sinatra     nil
+  run                 $0 == app_file                false
+  logging             true                          false
+  method_override     true                          false
+  inline_templates    true                          false
+  static              true                          false
+
+
+=== Servir une application modulaire
+
+Il y a deux façons de faire pour démarrer une application modulaire, démarrez
+avec <tt>run!</tt> :
+
+  # my_app.rb
+  require 'sinatra/base'
+
+  class MyApp < Sinatra::Base
+    # ... code de l'application ici ...
+
+    # démarre le serveur si ce fichier est directement exécuté
+    run! if app_file == $0
+  end
+
+Démarrez ensuite avec :
+
+  ruby my_app.rb
+
+Ou alors avec un fichier <tt>config.ru</tt>, qui permet d'utiliser n'importe
+quel gestionnaire Rack :
+
+  # config.ru
+  require './my_app'
+  run MyApp
+
+Exécutez :
+
+  rackup -p 4567
+
+=== Utiliser une application de style classique avec un fichier config.ru
+
+Ecrivez votre application :
+
+  # app.rb
+  require 'sinatra'
+
+  get '/' do
+    'Bonjour le monde !'
+  end
+
+Et un fichier <tt>config.ru</tt> correspondant :
+
+  require './app'
+  run Sinatra::Application
+
+=== Quand utiliser un fichier config.ru ?
+
+Quelques cas où vous devriez utiliser un fichier <tt>config.ru</tt> :
+
+* Vous souhaitez déployer avec un autre gestionnaire Rack (Passenger, Unicorn,
+  Heroku, ...).
+* Vous souhaitez utiliser plus d'une sous-classe de <tt>Sinatra::Base</tt>.
+* Vous voulez utiliser Sinatra comme un +middleware+, non en tant que
+  +endpoint+.
+
+<b>Il n'est pas nécessaire de passer par un fichier <tt>config.ru</tt> pour la
+seule raison que vous êtes passé au style modulaire, et vous n'avez pas besoin
+de passer au style modulaire pour utiliser un fichier <tt>config.ru</tt>.</b>
+
+=== Utiliser Sinatra comme Middleware
+
+Non seulement Sinatra peut utiliser d'autres middlewares Rack, il peut
+également être à son tour utilisé au-dessus de n'importe quel +endpoint+ Rack
+en tant que middleware. Ce +endpoint+ peut très bien être une autre
+application Sinatra, ou n'importe quelle application basée sur Rack
+(Rails/Ramaze/Camping/...) :
+
+  require 'sinatra/base'
+
+  class EcranDeConnexion < Sinatra::Base
+    enable :sessions
+
+    get('/connexion') { haml :connexion }
+
+    post('/connexion') do
+      if params[:nom] = 'admin' && params[:motdepasse] = 'admin'
+        session['nom_utilisateur'] = params[:nom]
+      else
+        redirect '/connexion'
+      end
+    end
+  end
+
+  class MonApp < Sinatra::Base
+    # le middleware sera appelé avant les filtres
+    use EcranDeConnexion
+
+    before do
+      unless session['nom_utilisateur']
+        halt "Accès refusé, merci de vous <a href='/connexion'>connecter</a>."
+      end
+    end
+
+    get('/') { "Bonjour #{session['nom_utilisateur']}." }
+  end
+
+=== Création dynamique d'applications
+
+Il se peut que vous ayez besoin de créer une nouvelle application à l'exécution
+sans avoir à les assigner à une constante, vous pouvez le faire grâce à
+<tt>Sinatra.new</tt> :
+
+  require 'sinatra/base'
+  mon_app = Sinatra.new { get('/') { "salut" } }
+  mon_app.run!
+
+L'application dont elle hérite peut être passé en argument optionnel :
+
+  # config.ru
+  require 'sinatra/base'
+
+  controleur = Sinatra.new do
+    enable :logging
+    helpers MyHelpers
+  end
+
+  map('/a') do
+    run Sinatra.new(controleur) { get('/') { 'a' } }
+  end
+
+  map('/b') do
+    run Sinatra.new(controleur) { get('/') { 'b' } }
+  end
+
+C'est notamment utile pour tester des extensions à Sinatra ou bien pour
+utiliser Sinatra dans votre propre bibliothèque.
+
+Cela permet également d'utiliser très facilement Sinatra comme middleware :
+
+  require 'sinatra/base'
+
+  use Sinatra do
+    get('/') { ... }
+  end
+
+  run RailsProject::Application
+
+== Contextes et Binding
+
+Le contexte dans lequel vous êtes détermine les méthodes et variables
+disponibles.
+
+=== Contexte de l'application/classe
+
+Toute application Sinatra correspond à une sous-classe de <tt>Sinatra::Base</tt>.
+Si vous utilisez le DSL haut niveau (<tt>require 'sinatra'</tt>), alors cette
+classe est <tt>Sinatra::Application</tt>, sinon il s'agit de la sous-classe que
+vous avez définie. Dans le contexte de la classe, vous avez accès aux méthodes
+telles que +get+ ou +before+, mais vous n'avez pas accès aux objets +request+
+ou +session+ car c'est la même classe d'application qui traitera toutes les
+requêtes.
+
+Les options définies au moyen de +set+ deviennent des méthodes de classe :
+
+    class MonApp < Sinatra::Base
+      # Eh, je suis dans le contexte de l'application !
+      set :foo, 42
+      foo # => 42
+
+      get '/foo' do
+        # Eh, je ne suis plus dans le contexte de l'application !
+      end
+    end
+
+Vous avez le binding du contexte de l'application dans :
+
+* Le corps de la classe d'application
+* Les méthodes définies par les extensions
+* Le bloc passé à +helpers+
+* Les procs/blocs utilisés comme argument pour +set+
+* Le bloc passé à <tt>Sinatra.new</tt>
+
+Vous pouvez atteindre ce contexte (donc la classe) de la façon suivante :
+
+* Via l'objet passé dans les blocs +configure+ (<tt>configure { |c| ... }</tt>)
+* En utilisant +settings+ dans le contexte de la requête
+
+=== Contexte de la requête/instance
+
+Pour tout traitement d'une requête, une nouvelle instance de votre classe
+d'application est créée et tous vos gestionnaires sont exécutés dans ce
+contexte. Dans ce dernier, vous pouvez accéder aux objets +request+ et
++session+ et faire appel aux fonctions de rendu telles que +erb+ ou +haml+.
+Vous pouvez accéder au contexte de l'application depuis le contexte de la
+requête au moyen de +settings+ :
+
+  class MonApp < Sinatra::Base
+    # Eh, je suis dans le contexte de l'application !
+    get '/ajouter_route/:nom' do
+      # Contexte de la requête pour '/ajouter_route/:nom'
+      @value = 42
+
+      settings.get("/#{params[:nom]}") do
+        # Contexte de la requête pour "/#{params[:nom]}"
+        @value # => nil (on est pas au sein de la même requête)
+      end
+
+      "Route ajoutée !"
+    end
+  end
+
+Vous avez le binding du contexte de la requête dans :
+
+* les blocs get/head/post/put/delete/options
+* les filtres before/after
+* les méthodes utilitaires (définies au moyen de +helpers+)
+* les vues/templates
+
+=== Le contexte de délégation
+
+Le contexte de délégation se contente de transmettre les appels de méthodes au
+contexte de classe. Toutefois, il ne se comporte pas à 100% comme le contexte
+de classe car vous n'avez pas le binding de la classe : seules les méthodes
+spécifiquement déclarées pour délégation sont disponibles et il n'est pas
+possible de partager des variables/états avec le contexte de classe
+(comprenez : +self+ n'est pas le même). Vous pouvez ajouter des délégation de
+méthodes en appelant <tt>Sinatra::Delegator.delegate :method_name</tt>.
+
+Vous avez le binding du contexte de délégation dans :
+
+* Le binding de haut niveau, si vous avez utilisé <tt>require "sinatra"</tt>
+* Un objet qui inclut le module +Sinatra::Delegator+
+
+Jetez un oeil pour vous faire une idée : voici le mixin
+{Sinatra::Delegator}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/base.rb#L1128]
+qui est {inclus dans l'espace de noms principal}[http://github.com/sinatra/sinatra/blob/ceac46f0bc129a6e994a06100aa854f606fe5992/lib/sinatra/main.rb#L28]
+
+== Ligne de commande
+
+Les applications en Sinatra peuvent être lancées directement :
+
+  ruby mon_application.rb [-h] [-x] [-e ENVIRONNEMENT] [-p PORT] [-o HOTE] [-s SERVEUR]
+
+Les options sont :
+
+  -h # aide
+  -p # déclare le port (4567 par défaut)
+  -o # déclare l'hôte (0.0.0.0 par défaut)
+  -e # déclare l'environnement (+development+ par défaut)
+  -s # déclare le serveur/gestionnaire à utiliser (thin par défaut)
+  -x # active le mutex lock (off par défaut)
+
+== Configuration nécessaire
+
+Les versions suivantes de Ruby sont officiellement supportées :
+
+[ Ruby 1.8.7 ]
+  1.8.7 est complètement supporté, toutefois si rien ne vous y retient, nous
+  vous recommandons de passer à 1.9.2 ou bien de passer à JRuby ou Rubinius.
+
+[ Ruby 1.9.2 ]
+  1.9.2 est supporté et recommandé. Notez que Radius et Markaby ne sont
+  actuellement pas compatible avec 1.9. N'utilisez pas 1.9.2p0 qui est
+  réputé causer des erreurs de segmentation lorque Sinatra est utilisé.
+
+[ Rubinius ]
+  Rubinius est officiellement supporté (Rubinius >= 1.2.3), tout fonctionne,
+  y compris tous les langages de template.
+
+[ JRuby ]
+  JRuby est officiellement supporté (JRuby >= 1.6.1). Aucune anomalie avec
+  des bibliothèques de templates tierces ne sont connues. Toutefois, si vous
+  choisissez JRuby, alors tournez vous vers des gestionnaires Rack JRuby car
+  le serveur Thin n'est pas complètement supporté par JRuby. Le support des
+  extensions C dans JRuby est encore expérimental, ce qui n'affecte que
+  RDiscount.
+
+<b>Ruby 1.8.6 n'est plus supporté.</b>
+
+Nous gardons également un oeil sur les versions Ruby à venir.
+
+Les implémentations Ruby suivantes ne sont pas officiellement supportées mais
+sont toujours connues comme permettant à Sinatra de fonctionner :
+
+* Plus anciennes versions de JRuby et Rubinius
+* MacRuby, Maglev, IronRuby
+* Ruby 1.9.0 et 1.9.1
+
+Ne pas être officiellement supporté signifie que si les choses se passent mal
+sur ces plateformes et non sur celles supportées, nous considérons que
+l'anomalie est de le ressort, pas du nôtre.
+
+Nous faisons également notre intégration continue (CI) avec ruby-head (la
+future 1.9.3), mais nous ne pouvons rien garantir étant donné que c'est
+constant mouvement. Vous pouvez vous attendre à ce que 1.9.3p0 soit supporté.
+
+Sinatra devrait fonctionner sur n'importe quel système d'exploitation
+supportant l'implémentation Ruby choisie.
+
+== Essuyer les plâtres
+
+Si vous voulez utiliser la toute dernière version de Sinatra, n'ayez pas peur
+de faire tourner votre application sur la branche master, cela devrait être
+stable.
+
+Nous publions également une gem de +prerelease+ de temps en temps que vous 
+pouvez installer comme suit :
+
+  gem install sinatra --pre
+
+afin d'avoir les toutes dernières fonctionnalités.
+
+=== Avec Bundler
+
+Si vous voulez faire tourner votre application avec le tout dernier
+Sinatra, {Bundler}[http://gembundler.com/] est recommandé.
+
+Tout d'abord, installer bundler si vous ne l'avez pas :
+
+  gem install bundler
+
+Ensuite, dans le dossier de votre projet, créez un fichier +Gemfile+ :
+
+  source :rubygems
+  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+
+  # autres dépendances
+  gem 'haml'                    # par exemple, si vous utilisez haml
+  gem 'activerecord', '~> 3.0'  # peut-être que vous avez également besoin
+                                # de ActiveRecord 3.x
+
+Notez que vous aurez à lister toutes les dépendances de votre application dans
+ce fichier. Les dépendances directes de Sinatra (Rack et Tilt) seront
+automatiquement téléchargées et ajoutées par Bundler.
+
+Maintenant, vous pouvez faire tourner votre application de la façon suivante :
+
+  bundle exec ruby myapp.rb
+
+=== Faites le vous-même
+
+Créez un clone local et démarrez votre application avec le dossier
+<tt>sinatra/lib</tt> dans le <tt>$LOAD_PATH</tt> :
+
+  cd myapp
+  git clone git://github.com/sinatra/sinatra.git
+  ruby -Isinatra/lib myapp.rb
+
+A l'avenir, pour mettre à jour le code source de Sinatra :
+
+  cd myapp/sinatra
+  git pull
+
+=== Installez globalement
+
+Vous pouvez construire la gem vous-même :
+
+  git clone git://github.com/sinatra/sinatra.git
+  cd sinatra
+  rake sinatra.gemspec
+  rake install
+
+Si vous installez les gems en tant que +root+, la dernière étape sera :
+
+  sudo rake install
+
+== Versions
+
+Sinatra se conforme aux {versions sémantiques}[http://semver.org/], aussi bien
+SemVer que SemVerTag.
+
+== Mais encore
+
+* {Site internet}[http://www.sinatrarb.com/] - Plus de documentation,
+  de news, et des liens vers d'autres ressources.
+* {Contribuer}[http://www.sinatrarb.com/contributing] - Vous avez trouvé un
+  bug ? Besoin d'aide ? Vous avez un patch ?
+* {Suivi des problèmes}[http://github.com/sinatra/sinatra/issues]
+* {Twitter}[http://twitter.com/sinatra]
+* {Mailing List}[http://groups.google.com/group/sinatrarb/topics]
+* {IRC : #sinatra}[irc://chat.freenode.net/#sinatra] sur http://freenode.net
+* {IRC : #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net
+* {Sinatra Book}[http://sinatra-book.gittr.com] Tutoriels et recettes
+* {Sinatra Recipes}[http://recipes.sinatrarb.com/] Recettes contribuées
+  par la communauté
+* Documentation API de la {dernière version}[http://rubydoc.info/gems/sinatra]
+  ou du {HEAD courant}[http://rubydoc.info/github/sinatra/sinatra] sur
+  http://rubydoc.info/
+