From e69485ee21c4bb733498c290080c97e19a0e3965 Mon Sep 17 00:00:00 2001 From: burningTyger Date: Fri, 30 Dec 2011 23:20:01 +0100 Subject: [PATCH] small changes to Environment section and minor markup fixes --- README.rdoc | 116 +++++++++++++++++++++++++++------------------------- 1 file changed, 61 insertions(+), 55 deletions(-) diff --git a/README.rdoc b/README.rdoc index c36a99fdbe..90ba76f83d 100644 --- a/README.rdoc +++ b/README.rdoc @@ -5,7 +5,7 @@ effort: # myapp.rb require 'sinatra' - + get '/' do 'Hello world!' end @@ -128,7 +128,7 @@ Other available conditions are +host_name+ and +provides+: get '/', :provides => 'html' do haml :index end - + get '/', :provides => ['rss', 'atom', 'xml'] do builder :feed end @@ -136,21 +136,21 @@ Other available conditions are +host_name+ and +provides+: You can easily define your own conditions: set(:probability) { |value| condition { rand <= value } } - + get '/win_a_car', :probability => 0.1 do "You won!" end - + get '/win_a_car' do "Sorry, you lost." end - + For a condition that takes multiple values use a splat: set(:auth) do |*roles| # <- notice the splat here condition do unless logged_in? && roles.any? {|role| current_user.in_role? role } - redirect "/login/", 303 + redirect "/login/", 303 end end end @@ -158,11 +158,11 @@ For a condition that takes multiple values use a splat: get "/my/account/", :auth => [:user, :admin] do "Your Account Details" end - + get "/only/admin/", :auth => :admin do "Only admins are allowed here!" end - + === Return Values The return value of a route block determines at least the response body passed @@ -177,7 +177,7 @@ body object or HTTP status code: body (responds to #each)] * An Array with two elements: [status (Fixnum), response body (responds to #each)] -* An object that responds to #each and passes nothing but strings to +* An object that responds to #each and passes nothing but strings to the given block * A Fixnum representing the status code @@ -559,7 +559,7 @@ Templates may be defined at the end of the source file: = yield @@ index - %div.title Hello world!!!!! + %div.title Hello world. NOTE: Inline templates defined in the source file that requires sinatra are automatically loaded. Call enable :inline_templates explicitly if you @@ -582,8 +582,8 @@ Templates may also be defined using the top-level template method: end If a template named "layout" exists, it will be used each time a template -is rendered. You can individually disable layouts by passing -:layout => false or disable them by default via +is rendered. You can individually disable layouts by passing +:layout => false or disable them by default via set :haml, :layout => false: get '/' do @@ -659,7 +659,7 @@ Like routes, filters also take conditions: before :agent => /Songbird/ do # ... end - + after '/blog/*', :host_name => 'example.com' do # ... end @@ -798,12 +798,12 @@ access the body: get '/foo' do body "bar" end - + after do puts body end -It is also possible to pass a block to +body+, which will be executed by the +It is also possible to pass a block to +body+, which will be executed by the Rack handler (this can be used to implement streaming, see "Return Values"). Similar to the body, you can also set the status code and headers: @@ -954,12 +954,12 @@ To pass arguments with a redirect, either add them to the query: Or use a session: enable :sessions - + get '/foo' do session[:secret] = 'foo' redirect to('/bar') end - + get '/bar' do session[:secret] end @@ -1006,14 +1006,14 @@ It is also possible to use a etag @article.sha1, :weak These helpers will not do any caching for you, but rather feed the necessary -information to your cache. If you are looking for a quick reverse-proxy caching solution, -try {rack-cache}[http://rtomayko.github.com/rack-cache/]: +information to your cache. If you are looking for a quick reverse-proxy caching +solution, try {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 @@ -1114,7 +1114,7 @@ Some options, like script_name or path_info, can also be written: before { request.path_info = "/" } - + get "/" do "all requests end up here" end @@ -1223,16 +1223,16 @@ Run once, at startup, in any environment: configure do # setting one option set :option, 'value' - + # setting multiple options set :a => 1, :b => 2 - + # same as `set :option, true` enable :option - + # same as `set :option, false` disable :option - + # you can also have dynamic settings with blocks set(:css_dir) { File.join(views, 'css') } end @@ -1300,8 +1300,8 @@ You can also hand in an array in order to disable a list of protections: settings.add_charsets << "application/foobar" -[app_file] Path to the main application file, used to detect project root, - views and public folder and inline templates. +[app_file] Path to the main application file, used to detect project + root, views and public folder and inline templates. [bind] IP address to bind to (default: 0.0.0.0). Only used for built-in server. @@ -1347,8 +1347,8 @@ You can also hand in an array in order to disable a list of protections: setting if not set. [raise_errors] raise exceptions (will stop application). Enabled - by default when environment is set to "test", - disabled otherwise. + by default when environment is set to + "test", disabled otherwise. [run] if enabled, Sinatra will handle starting the web server, do not enable if using rackup or other means. @@ -1388,15 +1388,20 @@ You can also hand in an array in order to disable a list of protections: == Environments -There are three predefined +environments+: development, production and test. Environment can be set by RACK_ENV environment variable, and default value is development. +There are three predefined +environments+: "development", +"production" and "test". Environments can be set +through the +RACK_ENV+ environment variable. The default value is +"development". In this mode, all templates are reloaded between +requests. Special not_found and error handlers are installed +for this environment so you will see a stack trace in your browser. +In "production" and "test" templates are cached by default. -You can also run different environemnt using -e option: +To run different environments use the -e option: ruby my_app.rb -e [ENVIRONMENT] -You can use predefinied methods: +development?+, +test?+ and +production?+, to check which enviroment is set. - -+Developemnt+ is default setting. In this mode, all templates are being reloaded between requests. Special not_found and error handlers are installed for this enviroment, so you will see nice error page. In +production+ and +test+ templates are being cached. +You can use predefined methods: +development?+, +test?+ and +production?+ to +check which enviroment is currently set. == Error Handling @@ -1501,8 +1506,8 @@ with {CodeRack}[http://coderack.org/] or in the == Testing -Sinatra tests can be written using any Rack-based testing library -or framework. {Rack::Test}[http://rdoc.info/github/brynary/rack-test/master/frames] +Sinatra tests can be written using any Rack-based testing library or framework. +{Rack::Test}[http://rdoc.info/github/brynary/rack-test/master/frames] is recommended: require 'my_sinatra_app' @@ -1564,7 +1569,8 @@ available via the top-level DSL. Most top-level apps can be converted to of Sinatra::Base. Sinatra::Base is a blank slate. Most options are disabled by default, -including the built-in server. See {Options and Configuration}[http://sinatra.github.com/configuration.html] +including the built-in server. See +{Options and Configuration}[http://sinatra.github.com/configuration.html] for details on available options and their behavior. === Modular vs. Classic Style @@ -1597,10 +1603,10 @@ There are two common options for starting a modular app, actively starting with # my_app.rb require 'sinatra/base' - + class MyApp < Sinatra::Base # ... app code here ... - + # start the server if ruby file executed directly run! if app_file == $0 end @@ -1625,7 +1631,7 @@ Write your app file: # app.rb require 'sinatra' - + get '/' do 'Hello world!' end @@ -1656,12 +1662,12 @@ endpoint could be another Sinatra application, or any other Rack-based application (Rails/Ramaze/Camping/...): require 'sinatra/base' - + class LoginScreen < Sinatra::Base enable :sessions - + get('/login') { haml :login } - + post('/login') do if params[:name] == 'admin' && params[:password] == 'admin' session['user_name'] = params[:name] @@ -1670,17 +1676,17 @@ application (Rails/Ramaze/Camping/...): end end end - + class MyApp < Sinatra::Base # middleware will run before filters use LoginScreen - + before do unless session['user_name'] halt "Access denied, please login." end end - + get('/') { "Hello #{session['user_name']}." } end @@ -1732,10 +1738,10 @@ available. === Application/Class Scope Every Sinatra application corresponds to a subclass of Sinatra::Base. -If you are using the top-level DSL (require 'sinatra'), then this -class is Sinatra::Application, otherwise it is the subclass you +If you are using the top-level DSL (require 'sinatra'), then this +class is Sinatra::Application, otherwise it is the subclass you created explicitly. At class level you have methods like +get+ or +before+, but -you cannot access the +request+ object or the +session+, as there only is a +you cannot access the +request+ object or the +session+, as there only is a single application class for all requests. Options created via +set+ are methods at class level: @@ -1744,7 +1750,7 @@ Options created via +set+ are methods at class level: # Hey, I'm in the application scope! set :foo, 42 foo # => 42 - + get '/foo' do # Hey, I'm no longer in the application scope! end @@ -1776,12 +1782,12 @@ scope via the +settings+ helper: get '/define_route/:name' do # Request scope for '/define_route/:name' @value = 42 - + settings.get("/#{params[:name]}") do # Request scope for "/#{params[:name]}" @value # => nil (not the same request) end - + "Route defined!" end end @@ -1910,7 +1916,7 @@ Then, in your project directory, create a +Gemfile+: source :rubygems gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git" - + # other dependencies gem 'haml' # for instance, if you use haml gem 'activerecord', '~> 3.0' # maybe you also need ActiveRecord 3.x @@ -1966,7 +1972,7 @@ SemVerTag. * {Mailing List}[http://groups.google.com/group/sinatrarb/topics] * {IRC: #sinatra}[irc://chat.freenode.net/#sinatra] on http://freenode.net * {Sinatra Book}[http://sinatra-book.gittr.com] Cookbook Tutorial -* {Sinatra Recipes}[http://recipes.sinatrarb.com/] Community +* {Sinatra Recipes}[http://recipes.sinatrarb.com/] Community contributed recipes * API documentation for the {latest release}[http://rubydoc.info/gems/sinatra] or the {current HEAD}[http://rubydoc.info/github/sinatra/sinatra] on