sinatra 1.1.4 → 1.2.0

data/README.ru.rdoc

@@ -39,6 +39,10 @@ Sinatra — это предметно-ориентированный язык (D
     .. что-то удалить ..
   end
 
+  options '/' do
+    .. что-то ответить ..
+  end
+
 Маршруты сверяются с запросом по очередности определения. Первый же совпавший с запросом маршрут и будет вызван.
 
 Шаблоны маршрутов могут включать в себя параметры доступные в
@@ -168,9 +172,9 @@ Sinatra — это предметно-ориентированный язык (D
 
 === Haml шаблоны
 
-Haml gem/библиотека необходима для рендеринга HAML шаблонов:
+<tt>haml</tt> gem/библиотека необходима для рендеринга HAML шаблонов:
 
-  ## Вам нужно будет подключить haml gem в приложении
+  # Вам нужно будет подключить haml gem в приложении
   require 'haml'
 
   get '/' do
@@ -193,33 +197,44 @@ Haml gem/библиотека необходима для рендеринга H
 
 === Erb шаблоны
 
-  ## Вам нужно будет подключить erb в приложении
+  # Вам нужно будет подключить erb в приложении
   require 'erb'
 
   get '/' do
     erb :index
   end
 
-Отрисует <tt>./views/index.erb</tt>
+Отрисует <tt>./views/index.erb</tt>.
 
 === Erubis шаблоны
 
-Erubis gem/библиотека необходима для рендеринга erubis шаблонов:
+<tt>erubis</tt> gem/библиотека необходима для рендеринга Erubis шаблонов:
 
-  ## Вам нужно будет подключить erubis в приложении
+  # Вам нужно будет подключить Erubis в приложении
   require 'erubis'
 
   get '/' do
     erubis :index
   end
 
-Отрисует <tt>./views/index.erubis</tt>
+Отрисует <tt>./views/index.erubis</tt>.
+
+Также возможно заменить Erb на Erubis:
+
+  require 'erubis'
+  Tilt.register :erb, Tilt[:erubis]
+
+  get '/' do
+    erb :index
+  end
+
+Отрисует <tt>./views/index.erb</tt> с помощью Erubis.
 
 === Builder шаблоны
 
-Builder gem/библиотека необходима для рендеринга builder шаблонов:
+<tt>builder</tt> gem/библиотека необходима для рендеринга builder шаблонов:
 
-  ## Вам нужно будет подключить builder в приложении
+  # Вам нужно будет подключить builder в приложении
   require 'builder'
 
   get '/' do
@@ -230,9 +245,9 @@ Builder gem/библиотека необходима для рендеринг
 
 === Nokogiri шаблоны
 
-Nokogiri gem/библиотека необходима для рендеринга nokogiri шаблонов:
+<tt>nokogiri</tt> gem/библиотека необходима для рендеринга nokogiri шаблонов:
 
-  ## Вам нужно будет подключить nokogiri в приложении
+  # Вам нужно будет подключить nokogiri в приложении
   require 'nokogiri'
 
   get '/' do
@@ -243,9 +258,9 @@ Nokogiri gem/библиотека необходима для рендеринг
 
 === Sass шаблоны
 
-Haml gem/библиотека необходима для рендеринга Sass шаблонов:
+<tt>haml</tt> gem/библиотека необходима для рендеринга Sass шаблонов:
 
-  ## Вам нужно будет подключить haml или sass в приложении
+  # Вам нужно будет подключить haml или sass в приложении
   require 'sass'
 
   get '/stylesheet.css' do
@@ -267,9 +282,9 @@ Haml gem/библиотека необходима для рендеринга S
 
 === Scss шаблоны
 
-Haml gem/библиотека необходима для рендеринга Scss шаблонов:
+<tt>haml</tt> gem/библиотека необходима для рендеринга Scss шаблонов:
 
-  ## Вам нужно будет подключить haml или sass в приложении
+  # Вам нужно будет подключить haml или sass в приложении
   require 'sass'
 
   get '/stylesheet.css' do
@@ -291,9 +306,9 @@ Haml gem/библиотека необходима для рендеринга S
 
 === Less шаблоны
 
-less gem/библиотека необходима для рендеринга Less шаблонов:
+<tt>less</tt> gem/библиотека необходима для рендеринга Less шаблонов:
 
-  ## Вам нужно будет подключить less в приложении
+  # Вам нужно будет подключить less в приложении
   require 'less'
 
   get '/stylesheet.css' do
@@ -304,9 +319,9 @@ less gem/библиотека необходима для рендеринга L
 
 === Liquid шаблоны
 
-liquid gem/библиотека необходима для рендеринга liquid шаблонов:
+<tt>liquid</tt> gem/библиотека необходима для рендеринга liquid шаблонов:
 
-  ## Вам нужно будет подключить liquid в приложении
+  # Вам нужно будет подключить liquid в приложении
   require 'liquid'
 
   get '/' do
@@ -322,9 +337,9 @@ liquid gem/библиотека необходима для рендеринга
 
 === Markdown шаблоны
 
-rdiscount gem/библиотека необходима для рендеринга Markdown шаблонов:
+<tt>rdiscount</tt> gem/библиотека необходима для рендеринга Markdown шаблонов:
 
-  ## Вам нужно будет подключить rdiscount в приложении
+  # Вам нужно будет подключить rdiscount в приложении
   require "rdiscount"
   
   get '/' do
@@ -335,7 +350,7 @@ rdiscount gem/библиотека необходима для рендерин
 расширениями).
 
 В Markdown невозможно вызывать методы или передавать локальные переменные.
-Следовательно, вам скорее всего придется использовать этот шаблон совместно с другим
+Следовательно, вам, скорее всего, придется использовать этот шаблон совместно с другим
 движком рендеринга:
 
   erb :overview, :locals => { :text => markdown(:introduction) }
@@ -345,6 +360,28 @@ rdiscount gem/библиотека необходима для рендерин
   %h1 Hello From Haml!
   %p= markdown(:greetings)
 
+Вы не можете вызывать Ruby из Markdown, соответственно, вы не можете использовать
+лэйаут-шаблоны (layouts) на Markdown. Тем не менее, есть возможность использовать один
+движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`:
+
+  get '/' do
+    markdown :index, :layout_engine => :erb
+  end
+
+Отрисует <tt>./views/index.md</tt> с <tt>./views/layout.erb</tt> в качестве
+лэйаута.
+
+Также вы можете задать такие опции рендеринга глобально:
+
+  set :markdown, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    markdown :index
+  end
+
+Отрисует <tt>./views/index.md</tt> (и любой другой шаблон на Markdown) с
+<tt>./views/post.haml</tt> в качестве лэйаута.
+
 Также возможно обрабатывать Markdown с помощью BlueCloth, а не RDiscount:
 
   require 'bluecloth'
@@ -361,9 +398,9 @@ rdiscount gem/библиотека необходима для рендерин
 
 === Textile шаблоны
 
-RedCloth gem/библиотека необходима для рендеринга Textile шаблонов:
+<tt>RedCloth</tt> gem/библиотека необходима для рендеринга Textile шаблонов:
 
-  ## Вам нужно будет подключить redcloth в приложении
+  # Вам нужно будет подключить redcloth в приложении
   require "redcloth"
 
   get '/' do
@@ -372,22 +409,44 @@ RedCloth gem/библиотека необходима для рендеринг
 
 Отрисует <tt>./views/index.textile</tt>.
 
-В textile невозможно вызывать методы или передавать локальные переменные. Следовательно, вам скорее всего придется 
-использовать этот шаблон совместно с другим движком рендеринга:
+В Textile невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего,
+придется использовать этот шаблон совместно с другим движком рендеринга:
 
   erb :overview, :locals => { :text => textile(:introduction) }
 
-Заметьте, что вы можете вызывать метод textile из других шаблонов:
+Заметьте, что вы можете вызывать метод +textile+ из других шаблонов:
 
   %h1 Hello From Haml!
   %p= textile(:greetings)
 
+Вы не можете вызывать Ruby из Textile, соответственно, вы не можете использовать
+лэйаут-шаблоны на Textile. Тем не менее, есть возможность использовать один
+движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`:
+
+  get '/' do
+    textile :index, :layout_engine => :erb
+  end
+
+Отрисует <tt>./views/index.textile</tt> с <tt>./views/layout.erb</tt> в качестве
+лэйаута.
+
+Также вы можете задать такие опции рендеринга глобально:
+
+  set :textile, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    textile :index
+  end
+
+Отрисует <tt>./views/index.textile</tt> (и любой другой шаблон на Textile) с
+<tt>./views/post.haml</tt> в качестве лэйаута.
+
 === RDoc шаблоны
 
-RDoc gem/библиотека необходима для рендеринга RDoc шаблонов:
+<tt>rdoc</tt> gem/библиотека необходима для рендеринга RDoc шаблонов:
 
-  ## Вам нужно будет подключить rdoc в приложении
-  require "rdoc"
+  # Вам нужно будет подключить rdoc/markup/to_html в приложении
+  require "rdoc/markup/to_html"
 
   get '/' do
     rdoc :index
@@ -395,21 +454,43 @@ RDoc gem/библиотека необходима для рендеринга R
 
 Отрисует <tt>./views/index.rdoc</tt>.
 
-В rdoc невозможно вызывать методы или передавать локальные переменные. Следовательно, вам скорее всего придется 
-использовать этот шаблон совместно с другим движком рендеринга:
+В RDoc невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего,
+придется использовать этот шаблон совместно с другим движком рендеринга:
 
   erb :overview, :locals => { :text => rdoc(:introduction) }
 
-Заметьте, что вы можете вызывать метод rdoc из других шаблонов:
+Заметьте, что вы можете вызывать метод +rdoc+ из других шаблонов:
 
   %h1 Hello From Haml!
   %p= rdoc(:greetings)
 
+Вы не можете вызывать Ruby из RDoc, соответственно, вы не можете использовать
+лэйаут-шаблоны на RDoc. Тем не менее, есть возможность использовать один
+движок рендеринга для шаблона, а другой для лэйаута с помощью опции `:layout_engine`:
+
+  get '/' do
+    rdoc :index, :layout_engine => :erb
+  end
+
+Отрисует <tt>./views/index.rdoc</tt> с <tt>./views/layout.erb</tt> в качестве
+лэйаута.
+
+Также вы можете задать такие опции рендеринга глобально:
+
+  set :rdoc, :layout_engine => :haml, :layout => :post
+
+  get '/' do
+    rdoc :index
+  end
+
+Отрисует <tt>./views/index.rdoc</tt> (и любой другой шаблон на RDoc) с
+<tt>./views/post.haml</tt> в качестве лэйаута.
+
 === Radius шаблоны
 
-radius gem/библиотека необходима для рендеринга Radius шаблонов:
+<tt>radius</tt> gem/библиотека необходима для рендеринга Radius шаблонов:
 
-  ## Вам нужно будет подключить radius в приложении
+  # Вам нужно будет подключить radius в приложении
   require 'radius'
 
   get '/' do
@@ -425,9 +506,9 @@ radius gem/библиотека необходима для рендеринга
 
 === Markaby шаблоны
 
-markaby gem/библиотека необходима для рендеринга Markaby шаблонов:
+<tt>markaby</tt> gem/библиотека необходима для рендеринга Markaby шаблонов:
 
-  ## Вам нужно будет подключить markaby в приложении
+  # Вам нужно будет подключить markaby в приложении
   require 'markaby'
 
   get '/' do
@@ -436,11 +517,39 @@ markaby gem/библиотека необходима для рендеринг
 
 Отрисует <tt>./views/index.mab</tt>.
 
+Вы также можете использовать внутристроковые Markaby шаблоны:
+
+  get '/' do
+    markaby { h1 "Welcome!" }
+  end
+
+=== Slim шаблоны
+
+<tt>slim</tt> gem/библиотека необходима для рендеринга slim шаблонов:
+
+  # Вам нужно будет подключить slim в приложении
+  require 'slim'
+
+  get '/' do
+    slim :index
+  end
+
+Отрисует <tt>./views/index.slim</tt>.
+
 === CoffeeScript шаблоны
 
-coffee-script gem/библиотека и `coffee` бинарный файл необходимы для рендеринга CoffeeScript шаблонов:
+Вам понадобится <tt>coffee-script</tt> gem/библиотека и что-то <b>одно</b> из следующего списка,
+чтобы запускать JavaScript:
+
+* +node+ (из Node.js)
+* вы можете использовать OSX (есть встроенные средства для выполнения JavaScript)
+* +therubyracer+ gem/библиотека
 
-  ## Вам нужно будет подключить coffee-script в приложении
+Подробнее смотрите на {странице проекта}[http://github.com/josh/ruby-coffee-script].
+
+Таким образом вы можете использовать CoffeeScript шаблоны.
+
+  # Вам нужно будет подключить coffee-script в приложении
   require 'coffee-script'
 
   get '/application.js' do
@@ -459,8 +568,8 @@ coffee-script gem/библиотека и `coffee` бинарный файл н
 
 === Доступ к переменным в шаблонах
 
-Шаблоны интерпретируются в том же контексте, что и обработчики маршрутов. Переменные экзмепляра, 
-установленные в процесе обработки маршрутов, будут доступны напрямую в шаблонах:
+Шаблоны интерпретируются в том же контексте, что и обработчики маршрутов. Переменные экземпляра,
+установленные в процессе обработки маршрутов, будут доступны напрямую в шаблонах:
 
   get '/:id' do
     @foo = Foo.find(params[:id])
@@ -474,7 +583,7 @@ coffee-script gem/библиотека и `coffee` бинарный файл н
     haml '%h1= foo.name', :locals => { :foo => foo }
   end
 
-Это обычно используется когда шаблоны рендерятся как частные (partials) из других шаблонов.
+Это обычный подход, когда шаблоны рендерятся как частные (partials) из других шаблонов.
 
 === Вложенные шаблоны
 
@@ -495,7 +604,7 @@ coffee-script gem/библиотека и `coffee` бинарный файл н
   @@ index
   %div.title Hello world!!!!!
 
-Заметьте: Вложенные шаблоны, определенные в файле-исходнике, который подключил sinatra, будут
+Заметьте: Вложенные шаблоны, определенные в файле-исходнике, который подключил Sinatra, будут
 автоматически загружены. Вызовите <tt>enable :inline_templates</tt> напрямую, если у вас вложенные
 шаблоны в других файлах.
 
@@ -516,17 +625,42 @@ coffee-script gem/библиотека и `coffee` бинарный файл н
   end
 
 Если шаблон с именем "layout" существует, то он будет использован каждый раз,
-когда шаблоны будут отрисовываться. Вы можете отключать layout-шаблон в каждом конкретном случае с помощью
+когда шаблоны будут отрисовываться. Вы можете отключать лэйаут в каждом конкретном случае с помощью
 <tt>:layout => false</tt> или отключить его для всего приложения, например, так: <tt>set :haml, :layout => false</tt>.
 
   get '/' do
     haml :index, :layout => !request.xhr?
   end
 
-== Методы помощники
+=== Привязка файловых расширений
+
+Чтобы связать расширение файла и движок рендеринга, используйте
+<tt>Tilt.register</tt>. Например, если вы хотите использовать расширение +tt+
+для шаблонов Textile:
+
+  Tilt.register :tt, Tilt[:textile]
+
+=== Добавление собственного движка рендеринга
+
+Сначала зарегистрируйте свой движок в Tilt, затем создайте метод, отвечающий за отрисовку:
+
+  Tilt.register :myat, MyAwesomeTemplateEngine
+
+  helpers do
+    def myat(*args) render(:myat, *args) end
+  end
+
+  get '/' do
+    myat :index
+  end
 
-Используйте <tt>helpers</tt> метод для определения методов помощников для дальнейшего 
-использования в обработчиках маршрутов и шаблонах:
+Отрисует <tt>./views/index.myat</tt>. Чтобы узнать больше о Tilt,
+смотрите https://github.com/rtomayko/tilt
+
+== Методы-помощники
+
+Используйте метод <tt>helpers</tt>, чтобы определить методы-помощники, которые
+в дальнейшем можно будет использовать в обработчиках маршрутов и шаблонах:
 
   helpers do
     def bar(name)
@@ -570,6 +704,16 @@ After-фильтры выполняются после каждого запро
     session[:last_slug] = slug
   end
 
+Как и маршруты, фильтры могут использовать условия:
+
+  before :agent => /Songbird/ do
+    # ...
+  end
+
+  after '/blog/*', :host_name => 'example.com' do
+    # ...
+  end
+
 == Прерывание
 
 Чтобы незамедлительно прервать обработку запроса внутри фильтра или маршрута, используйте:
@@ -623,23 +767,23 @@ After-фильтры выполняются после каждого запро
     request.request_method    # "GET"
     request.query_string      # ""
     request.content_length    # длина тела запроса
-    request.media_type        # медиа тип тела запроса
+    request.media_type        # медиатип тела запроса
     request.host              # "example.com"
-    request.get?              # true (для других участвующих HTTP глаголов есть похожие методы)
+    request.get?              # true (есть аналоги для других методов HTTP)
     request.form_data?        # false
-    request["SOME_HEADER"]    # значение SOME_HEADER заголовка
+    request["SOME_HEADER"]    # значение заголовка SOME_HEADER
     request.referer           # источник запроса клиента либо '/'
     request.user_agent        # user agent (используется для :agent условия)
-    request.cookies           # хеш куки браузера
+    request.cookies           # хеш с куками браузера
     request.xhr?              # является ли запрос ajax запросом?
     request.url               # "http://example.com/example/foo"
     request.path              # "/example/foo"
-    request.ip                # IP адрес клиента
+    request.ip                # IP-адрес клиента
     request.secure?           # false
-    request.env               # env хеш как получено Rack
+    request.env               # "сырой" env хеш, полученный Rack
   end
 
-Некоторые опции, такие как <tt>script_name</tt> или <tt>path_info</tt> могут быть переписаны:
+Некоторые опции, такие как <tt>script_name</tt> или <tt>path_info</tt> доступны для записи:
 
   before { request.path_info = "/" }
   
@@ -681,7 +825,7 @@ After-фильтры выполняются после каждого запро
 Обработчики ошибок исполняются в том же контексте, что и маршруты, before-фильтры, а это означает, что всякие
 прелести вроде <tt>haml</tt>, <tt>erb</tt>, <tt>halt</tt> и т.д. доступны и им.
 
-===  NotFound
+=== NotFound
 
 Когда возбуждено исключение <tt>Sinatra::NotFound</tt>, или кодом ответа является 404,
 то будет вызван <tt>not_found</tt> обработчик:
@@ -734,9 +878,9 @@ After-фильтры выполняются после каждого запро
 Sinatra устанавливает специальные <tt>not_found</tt> и <tt>error</tt> обработчики, когда запущена в режиме
 разработки (окружение <tt>:development</tt>).
 
-== Mime типы
+== Mime-типы
 
-Когда вы используете <tt>send_file</tt> или статические файлы, у вас могут быть mime типы, которые Sinatra
+Когда вы используете <tt>send_file</tt> или статические файлы, у вас могут быть mime-типы, которые Sinatra
 не понимает по умолчанию. Используйте +mime_type+ для их регистрации по расширению файла:
 
   mime_type :foo, 'text/foo'
@@ -811,8 +955,8 @@ Rack распространяется с различными стандартн
     end
   end
 
-Заметьте: Встроенные модули Sinatra::Test и Sinatra::TestHarness являются
-устаревшими, начиная с 0.9.2 релиза.
+Обратите внимание: Встроенные модуль Sinatra::Test и класс Sinatra::TestHarness являются
+устаревшими, начиная с релиза 0.9.2.
 
 == Sinatra::Base — "прослойки", библиотеки и модульные приложения
 
@@ -1005,7 +1149,7 @@ Sinatra::Application, иначе это будет сабкласс, котор
 
 У вас будет область видимости запроса внутри:
 
-* get/head/post/put/delete блоков
+* get/head/post/put/delete/options блоков
 * before/after фильтрах
 * методах помощниках 
 * шаблонах/видах
@@ -1046,31 +1190,69 @@ Sinatra приложения могут быть запущены напряму
 
 == На острие
 
-Если вы хотите использовать новейший код Sinatra, то создайте локальный
-клон и запускайте свое приложение с <tt>sinatra/lib</tt> директорией
-в <tt>LOAD_PATH</tt>:
+Если вы хотите использовать самый последний код Sinatra, не бойтесь запускать
+свое приложение вместе с master бранчем Sinatra, он весьма стабилен.
+
+Мы также время от времени выпускаем предварительные версии, так что вы можете делать так:
+
+  gem install sinatra --pre
+
+Чтобы воспользоваться некоторыми самыми последними возможностям.
+
+=== С помощью Bundler
+
+Если вы хотите запускать свое приложение с последней версией Sinatra, то
+рекомендуем использовать {Bundler}[http://gembundler.com/].
+
+Сначала установите Bundler, если у вас его еще нет:
+
+  gem install bundler
+
+Затем создайте файл +Gemfile+ в директории вашего проекта:
+
+  source :rubygems
+  gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+
+  # другие зависимости
+  gem 'haml'                    # например, если используете haml
+  gem 'activerecord', '~> 3.0'  # может быть, вам нужен и ActiveRecord 3.x
+
+Обратите внимание, вам нужно будет указывать все зависимости вашего приложения
+в этом файле. Однако, непосредственные зависимости Sinatra (Rack и Tilt) Bundler
+автоматически скачает и добавит.
+
+Теперь вы можете запускать свое приложение примерно так:
+
+  bundle exec ruby myapp.rb
+
+=== Вручную
+
+Создайте локальный клон репозитория и запускайте свое приложение с <tt>sinatra/lib</tt>
+директорией в <tt>LOAD_PATH</tt>:
 
   cd myapp
   git clone git://github.com/sinatra/sinatra.git
   ruby -Isinatra/lib myapp.rb
 
-Также вы можете добавить <tt>sinatra/lib</tt> директорию в
-<tt>LOAD_PATH</tt> приложения:
+Чтобы обновить исходники Sinatra:
 
-  $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
-  require 'rubygems'
-  require 'sinatra'
+  cd myapp/sinatra
+  git pull
 
-  get '/about' do
-    "I'm running version " + Sinatra::VERSION
-  end
+=== Установка глобально
 
-Чтобы обновить исходники Sinatra:
+Вы можете самостоятельно собрать gem:
 
-  cd myproject/sinatra
-  git pull
+  git clone git://github.com/sinatra/sinatra.git
+  cd sinatra
+  rake sinatra.gemspec
+  rake install
+
+Если вы устанавливаете пакеты (gem) от пользователя root, то вашим последним шагом должна быть команда
+
+  sudo rake install
 
-== Больше информации
+== Дальнейшее чтение
 
 * {Вебсайт проекта}[http://www.sinatrarb.com/] - Дополнительная документация,
   новости и ссылки на другие ресурсы.