sinatra 2.2.2 → 3.0.2

data/README.md

@@ -1,8 +1,7 @@
 # Sinatra
 
 [![Gem Version](https://badge.fury.io/rb/sinatra.svg)](https://badge.fury.io/rb/sinatra)
-[![Build Status](https://secure.travis-ci.org/sinatra/sinatra.svg)](https://travis-ci.org/sinatra/sinatra)
-[![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=sinatra&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=sinatra&package-manager=bundler&version-scheme=semver)
+[![Testing](https://github.com/sinatra/sinatra/actions/workflows/test.yml/badge.svg)](https://github.com/sinatra/sinatra/actions/workflows/test.yml)
 
 Sinatra is a [DSL](https://en.wikipedia.org/wiki/Domain-specific_language) for
 quickly creating web applications in Ruby with minimal effort:
@@ -20,6 +19,7 @@ Install the gem:
 
 ```shell
 gem install sinatra
+gem install puma # or any other server
 ```
 
 And run with:
@@ -31,101 +31,92 @@ ruby myapp.rb
 View at: [http://localhost:4567](http://localhost:4567)
 
 The code you changed will not take effect until you restart the server.
-Please restart the server every time you change or use
-[sinatra/reloader](http://www.sinatrarb.com/contrib/reloader).
+Please restart the server every time you change or use a code reloader
+like [rerun](https://github.com/alexch/rerun) or
+[rack-unreloader](https://github.com/jeremyevans/rack-unreloader).
 
 It is recommended to also run `gem install puma`, which Sinatra will
 pick up if available.
 
 ## Table of Contents
 
-* [Sinatra](#sinatra)
-    * [Table of Contents](#table-of-contents)
-    * [Routes](#routes)
-    * [Conditions](#conditions)
-    * [Return Values](#return-values)
-    * [Custom Route Matchers](#custom-route-matchers)
-    * [Static Files](#static-files)
-    * [Views / Templates](#views--templates)
-        * [Literal Templates](#literal-templates)
-        * [Available Template Languages](#available-template-languages)
-            * [Haml Templates](#haml-templates)
-            * [Erb Templates](#erb-templates)
-            * [Builder Templates](#builder-templates)
-            * [Nokogiri Templates](#nokogiri-templates)
-            * [Sass Templates](#sass-templates)
-            * [SCSS Templates](#scss-templates)
-            * [Less Templates](#less-templates)
-            * [Liquid Templates](#liquid-templates)
-            * [Markdown Templates](#markdown-templates)
-            * [Textile Templates](#textile-templates)
-            * [RDoc Templates](#rdoc-templates)
-            * [AsciiDoc Templates](#asciidoc-templates)
-            * [Radius Templates](#radius-templates)
-            * [Markaby Templates](#markaby-templates)
-            * [RABL Templates](#rabl-templates)
-            * [Slim Templates](#slim-templates)
-            * [Creole Templates](#creole-templates)
-            * [MediaWiki Templates](#mediawiki-templates)
-            * [CoffeeScript Templates](#coffeescript-templates)
-            * [Stylus Templates](#stylus-templates)
-            * [Yajl Templates](#yajl-templates)
-            * [WLang Templates](#wlang-templates)
-        * [Accessing Variables in Templates](#accessing-variables-in-templates)
-        * [Templates with `yield` and nested layouts](#templates-with-yield-and-nested-layouts)
-        * [Inline Templates](#inline-templates)
-        * [Named Templates](#named-templates)
-        * [Associating File Extensions](#associating-file-extensions)
-        * [Adding Your Own Template Engine](#adding-your-own-template-engine)
-        * [Using Custom Logic for Template Lookup](#using-custom-logic-for-template-lookup)
-    * [Filters](#filters)
-    * [Helpers](#helpers)
-        * [Using Sessions](#using-sessions)
-            * [Session Secret Security](#session-secret-security)
-            * [Session Config](#session-config)
-            * [Choosing Your Own Session Middleware](#choosing-your-own-session-middleware)
-        * [Halting](#halting)
-        * [Passing](#passing)
-        * [Triggering Another Route](#triggering-another-route)
-        * [Setting Body, Status Code and Headers](#setting-body-status-code-and-headers)
-        * [Streaming Responses](#streaming-responses)
-        * [Logging](#logging)
-        * [Mime Types](#mime-types)
-        * [Generating URLs](#generating-urls)
-        * [Browser Redirect](#browser-redirect)
-        * [Cache Control](#cache-control)
-        * [Sending Files](#sending-files)
-        * [Accessing the Request Object](#accessing-the-request-object)
-        * [Attachments](#attachments)
-        * [Dealing with Date and Time](#dealing-with-date-and-time)
-        * [Looking Up Template Files](#looking-up-template-files)
-    * [Configuration](#configuration)
-        * [Configuring attack protection](#configuring-attack-protection)
-        * [Available Settings](#available-settings)
-    * [Environments](#environments)
-    * [Error Handling](#error-handling)
-        * [Not Found](#not-found)
-        * [Error](#error)
-    * [Rack Middleware](#rack-middleware)
-    * [Testing](#testing)
-    * [Sinatra::Base - Middleware, Libraries, and Modular Apps](#sinatrabase---middleware-libraries-and-modular-apps)
-        * [Modular vs. Classic Style](#modular-vs-classic-style)
-        * [Serving a Modular Application](#serving-a-modular-application)
-        * [Using a Classic Style Application with a config.ru](#using-a-classic-style-application-with-a-configru)
-        * [When to use a config.ru?](#when-to-use-a-configru)
-        * [Using Sinatra as Middleware](#using-sinatra-as-middleware)
-        * [Dynamic Application Creation](#dynamic-application-creation)
-    * [Scopes and Binding](#scopes-and-binding)
-        * [Application/Class Scope](#applicationclass-scope)
-        * [Request/Instance Scope](#requestinstance-scope)
-        * [Delegation Scope](#delegation-scope)
-    * [Command Line](#command-line)
-        * [Multi-threading](#multi-threading)
-    * [Requirement](#requirement)
-    * [The Bleeding Edge](#the-bleeding-edge)
-        * [With Bundler](#with-bundler)
-    * [Versioning](#versioning)
-    * [Further Reading](#further-reading)
+- [Sinatra](#sinatra)
+  - [Table of Contents](#table-of-contents)
+  - [Routes](#routes)
+  - [Conditions](#conditions)
+  - [Return Values](#return-values)
+  - [Custom Route Matchers](#custom-route-matchers)
+  - [Static Files](#static-files)
+  - [Views / Templates](#views--templates)
+    - [Literal Templates](#literal-templates)
+    - [Available Template Languages](#available-template-languages)
+      - [Haml Templates](#haml-templates)
+      - [Erb Templates](#erb-templates)
+      - [Builder Templates](#builder-templates)
+      - [Nokogiri Templates](#nokogiri-templates)
+      - [Liquid Templates](#liquid-templates)
+      - [Markdown Templates](#markdown-templates)
+      - [RDoc Templates](#rdoc-templates)
+      - [AsciiDoc Templates](#asciidoc-templates)
+      - [Markaby Templates](#markaby-templates)
+      - [RABL Templates](#rabl-templates)
+      - [Slim Templates](#slim-templates)
+      - [Yajl Templates](#yajl-templates)
+    - [Accessing Variables in Templates](#accessing-variables-in-templates)
+    - [Templates with `yield` and nested layouts](#templates-with-yield-and-nested-layouts)
+    - [Inline Templates](#inline-templates)
+    - [Named Templates](#named-templates)
+    - [Associating File Extensions](#associating-file-extensions)
+    - [Adding Your Own Template Engine](#adding-your-own-template-engine)
+    - [Using Custom Logic for Template Lookup](#using-custom-logic-for-template-lookup)
+  - [Filters](#filters)
+  - [Helpers](#helpers)
+    - [Using Sessions](#using-sessions)
+      - [Session Secret Security](#session-secret-security)
+      - [Session Config](#session-config)
+      - [Choosing Your Own Session Middleware](#choosing-your-own-session-middleware)
+    - [Halting](#halting)
+    - [Passing](#passing)
+    - [Triggering Another Route](#triggering-another-route)
+    - [Setting Body, Status Code, and Headers](#setting-body-status-code-and-headers)
+    - [Streaming Responses](#streaming-responses)
+    - [Logging](#logging)
+    - [Mime Types](#mime-types)
+    - [Generating URLs](#generating-urls)
+    - [Browser Redirect](#browser-redirect)
+    - [Cache Control](#cache-control)
+    - [Sending Files](#sending-files)
+    - [Accessing the Request Object](#accessing-the-request-object)
+    - [Attachments](#attachments)
+    - [Dealing with Date and Time](#dealing-with-date-and-time)
+    - [Looking Up Template Files](#looking-up-template-files)
+  - [Configuration](#configuration)
+    - [Configuring attack protection](#configuring-attack-protection)
+    - [Available Settings](#available-settings)
+  - [Environments](#environments)
+  - [Error Handling](#error-handling)
+    - [Not Found](#not-found)
+    - [Error](#error)
+  - [Rack Middleware](#rack-middleware)
+  - [Testing](#testing)
+  - [Sinatra::Base - Middleware, Libraries, and Modular Apps](#sinatrabase---middleware-libraries-and-modular-apps)
+    - [Modular vs. Classic Style](#modular-vs-classic-style)
+    - [Serving a Modular Application](#serving-a-modular-application)
+    - [Using a Classic Style Application with a config.ru](#using-a-classic-style-application-with-a-configru)
+    - [When to use a config.ru?](#when-to-use-a-configru)
+    - [Using Sinatra as Middleware](#using-sinatra-as-middleware)
+    - [Dynamic Application Creation](#dynamic-application-creation)
+  - [Scopes and Binding](#scopes-and-binding)
+    - [Application/Class Scope](#applicationclass-scope)
+    - [Request/Instance Scope](#requestinstance-scope)
+    - [Delegation Scope](#delegation-scope)
+  - [Command Line](#command-line)
+    - [Multi-threading](#multi-threading)
+  - [Requirement](#requirement)
+  - [The Bleeding Edge](#the-bleeding-edge)
+    - [With Bundler](#with-bundler)
+  - [Versioning](#versioning)
+  - [Further Reading](#further-reading)
 
 ## Routes
 
@@ -382,15 +373,16 @@ stop there. You can easily define your own matchers:
 
 ```ruby
 class AllButPattern
-  Match = Struct.new(:captures)
-
   def initialize(except)
-    @except   = except
-    @captures = Match.new([])
+    @except = except
+  end
+
+  def to_pattern(options)
+    return self
   end
 
-  def match(str)
-    @captures unless @except === str
+  def params(route)
+    return {} unless @except === route
   end
 end
 
@@ -407,20 +399,12 @@ Note that the above example might be over-engineered, as it can also be
 expressed as:
 
 ```ruby
-get // do
+get /.*/ do
   pass if request.path_info == "/index"
   # ...
 end
 ```
 
-Or, using negative look ahead:
-
-```ruby
-get %r{(?!/index)} do
-  # ...
-end
-```
-
 ## Static Files
 
 Static files are served from the `./public` directory. You can specify
@@ -584,7 +568,7 @@ Some languages have multiple implementations. To specify what implementation
 to use (and to be thread-safe), you should simply require it first:
 
 ```ruby
-require 'rdiscount' # or require 'bluecloth'
+require 'rdiscount'
 get('/') { markdown :index }
 ```
 
@@ -612,14 +596,12 @@ get('/') { markdown :index }
     <td>Dependency</td>
     <td>
       <a href="https://github.com/jeremyevans/erubi" title="erubi">erubi</a>
-      or <a href="http://www.kuwata-lab.com/erubis/" title="erubis">erubis</a>
       or erb (included in Ruby)
     </td>
   </tr>
   <tr>
     <td>File Extensions</td>
-    <td><tt>.erb</tt>, <tt>.rhtml</tt> or <tt>.erubi</tt> (Erubi only)
- or <tt>.erubis</tt> (Erubis only)</td>
+    <td><tt>.erb</tt>, <tt>.rhtml</tt> or <tt>.erubi</tt> (Erubi only)</td>
   </tr>
   <tr>
     <td>Example</td>
@@ -667,56 +649,6 @@ It also takes a block for inline templates (see [example](#inline-templates)).
 
 It also takes a block for inline templates (see [example](#inline-templates)).
 
-#### Sass Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.sass</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>sass :stylesheet, :style => :expanded</tt></td>
-  </tr>
-</table>
-
-#### SCSS Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://sass-lang.com/" title="sass">sass</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.scss</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>scss :stylesheet, :style => :expanded</tt></td>
-  </tr>
-</table>
-
-#### Less Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="http://lesscss.org/" title="less">less</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.less</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>less :stylesheet</tt></td>
-  </tr>
-</table>
 
 #### Liquid Templates
 
@@ -747,9 +679,7 @@ template, you almost always want to pass locals to it.
       Anyone of:
         <a href="https://github.com/davidfstr/rdiscount" title="RDiscount">RDiscount</a>,
         <a href="https://github.com/vmg/redcarpet" title="RedCarpet">RedCarpet</a>,
-        <a href="https://github.com/ged/bluecloth" title="BlueCloth">BlueCloth</a>,
         <a href="https://kramdown.gettalong.org/" title="kramdown">kramdown</a>,
-        <a href="https://github.com/bhollis/maruku" title="maruku">maruku</a>
         <a href="https://github.com/gjtorikian/commonmarker" title="commonmarker">commonmarker</a>
         <a href="https://github.com/alphabetum/pandoc-ruby" title="pandoc">pandoc</a>
     </td>
@@ -784,42 +714,6 @@ Since you cannot call Ruby from Markdown, you cannot use layouts written in
 Markdown. However, it is possible to use another rendering engine for the
 template than for the layout by passing the `:layout_engine` option.
 
-#### Textile Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="http://redcloth.org/" title="RedCloth">RedCloth</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.textile</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>textile :index, :layout_engine => :erb</tt></td>
-  </tr>
-</table>
-
-It is not possible to call methods from Textile, nor to pass locals to
-it. You therefore will usually use it in combination with another
-rendering engine:
-
-```ruby
-erb :overview, :locals => { :text => textile(:introduction) }
-```
-
-Note that you may also call the `textile` method from within other templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= textile(:greetings)
-```
-
-Since you cannot call Ruby from Textile, you cannot use layouts written in
-Textile. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
 #### RDoc Templates
 
 <table>
@@ -875,26 +769,6 @@ template than for the layout by passing the `:layout_engine` option.
 Since you cannot call Ruby methods directly from an AsciiDoc template, you
 almost always want to pass locals to it.
 
-#### Radius Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/jlong/radius" title="Radius">Radius</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.radius</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>radius :index, :locals => { :key => 'value' }</tt></td>
-  </tr>
-</table>
-
-Since you cannot call Ruby methods directly from a Radius template, you
-almost always want to pass locals to it.
-
 #### Markaby Templates
 
 <table>
@@ -948,139 +822,6 @@ It also takes a block for inline templates (see [example](#inline-templates)).
   </tr>
 </table>
 
-#### Creole Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/minad/creole" title="Creole">Creole</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.creole</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>creole :wiki, :layout_engine => :erb</tt></td>
-  </tr>
-</table>
-
-It is not possible to call methods from Creole, nor to pass locals to it. You
-therefore will usually use it in combination with another rendering engine:
-
-```ruby
-erb :overview, :locals => { :text => creole(:introduction) }
-```
-
-Note that you may also call the `creole` method from within other templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= creole(:greetings)
-```
-
-Since you cannot call Ruby from Creole, you cannot use layouts written in
-Creole. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
-#### MediaWiki Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/nricciar/wikicloth" title="WikiCloth">WikiCloth</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.mediawiki</tt> and <tt>.mw</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>mediawiki :wiki, :layout_engine => :erb</tt></td>
-  </tr>
-</table>
-
-It is not possible to call methods from MediaWiki markup, nor to pass
-locals to it. You therefore will usually use it in combination with
-another rendering engine:
-
-```ruby
-erb :overview, :locals => { :text => mediawiki(:introduction) }
-```
-
-Note that you may also call the `mediawiki` method from within other
-templates:
-
-```ruby
-%h1 Hello From Haml!
-%p= mediawiki(:greetings)
-```
-
-Since you cannot call Ruby from MediaWiki, you cannot use layouts written in
-MediaWiki. However, it is possible to use another rendering engine for the
-template than for the layout by passing the `:layout_engine` option.
-
-#### CoffeeScript Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td>
-      <a href="https://github.com/josh/ruby-coffee-script" title="Ruby CoffeeScript">
-        CoffeeScript
-      </a> and a
-      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
-        way to execute javascript
-      </a>
-    </td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.coffee</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>coffee :index</tt></td>
-  </tr>
-</table>
-
-#### Stylus Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td>
-      <a href="https://github.com/forgecrafted/ruby-stylus" title="Ruby Stylus">
-        Stylus
-      </a> and a
-      <a href="https://github.com/sstephenson/execjs" title="ExecJS">
-        way to execute javascript
-      </a>
-    </td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.styl</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>stylus :index</tt></td>
-  </tr>
-</table>
-
-Before being able to use Stylus templates, you need to load `stylus` and
-`stylus/tilt` first:
-
-```ruby
-require 'sinatra'
-require 'stylus'
-require 'stylus/tilt'
-
-get '/' do
-  stylus :example
-end
-```
-
 #### Yajl Templates
 
 <table>
@@ -1122,27 +863,6 @@ var resource = {"foo":"bar","baz":"qux"};
 present(resource);
 ```
 
-#### WLang Templates
-
-<table>
-  <tr>
-    <td>Dependency</td>
-    <td><a href="https://github.com/blambeau/wlang" title="WLang">WLang</a></td>
-  </tr>
-  <tr>
-    <td>File Extension</td>
-    <td><tt>.wlang</tt></td>
-  </tr>
-  <tr>
-    <td>Example</td>
-    <td><tt>wlang :index, :locals => { :key => 'value' }</tt></td>
-  </tr>
-</table>
-
-Since calling ruby methods is not idiomatic in WLang, you almost always
-want to pass locals to it. Layouts written in WLang and `yield` are
-supported, though.
-
 ### Accessing Variables in Templates
 
 Templates are evaluated within the same context as route handlers. Instance
@@ -1201,7 +921,7 @@ end
 ```
 
 Currently, the following rendering methods accept a block: `erb`, `haml`,
-`liquid`, `slim `, `wlang`. Also, the general `render` method accepts a block.
+`liquid`, `slim `. Also, the general `render` method accepts a block.
 
 ### Inline Templates
 
@@ -1261,10 +981,10 @@ end
 
 To associate a file extension with a template engine, use
 `Tilt.register`. For instance, if you like to use the file extension
-`tt` for Textile templates, you can do the following:
+`tt` for Haml templates, you can do the following:
 
 ```ruby
-Tilt.register :tt, Tilt[:textile]
+Tilt.register :tt, Tilt[:haml]
 ```
 
 ### Adding Your Own Template Engine
@@ -2136,7 +1856,7 @@ end
 Another example would be using different directories for different engines:
 
 ```ruby
-set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
+set :views, :haml => 'templates', :default => 'views'
 
 helpers do
   def find_template(views, name, engine, &block)
@@ -3085,9 +2805,9 @@ rainbows -c rainbows.conf
 
 The following Ruby versions are officially supported:
 <dl>
-  <dt>Ruby 2.3</dt>
+  <dt>Ruby 2.6</dt>
   <dd>
-    2.3 is fully supported and recommended. There are currently no plans to
+    2.6 is fully supported and recommended. There are currently no plans to
     drop official support for it.
   </dd>
 
@@ -3105,32 +2825,15 @@ The following Ruby versions are officially supported:
   </dd>
 </dl>
 
-Versions of Ruby before 2.3 are no longer supported as of Sinatra 2.1.0.
-
-We also keep an eye on upcoming Ruby versions.
-
-The following Ruby implementations are not officially supported but still are
-known to run Sinatra:
+Versions of Ruby before 2.6 are no longer supported as of Sinatra 3.0.0.
 
-* Older versions of JRuby and Rubinius
-* Ruby Enterprise Edition
-* MacRuby, Maglev, IronRuby
-* Ruby 1.9.0 and 1.9.1 (but we do recommend against using those)
-
-Not being officially supported means if things only break there and not on a
-supported platform, we assume it's not our issue but theirs.
-
-We also run our CI against ruby-head (future releases of MRI), but we
-can't guarantee anything, since it is constantly moving. Expect upcoming
-2.x releases to be fully supported.
+We also keep an eye on upcoming Ruby versions. Expect upcoming
+3.x releases to be fully supported.
 
 Sinatra should work on any operating system supported by the chosen Ruby
 implementation.
 
-If you run MacRuby, you should `gem install control_tower`.
-
-Sinatra currently doesn't run on Cardinal, SmallRuby, BlueRuby or any
-Ruby version prior to 2.2.
+Running Sinatra on a not officially supported Ruby flavor means that if things only break there we assume it's not our issue but theirs.
 
 ## The Bleeding Edge