From 73e137dfbab84d1ed0cd62a65bc04ffd3f4bfae2 Mon Sep 17 00:00:00 2001 From: Konstantin Haase Date: Mon, 21 Feb 2011 14:03:30 +0100 Subject: [PATCH] improve language in readme all credit goes to wordy.com - they did this for free! --- README.rdoc | 77 ++++++++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/README.rdoc b/README.rdoc index cbaf86f2..797e93f2 100644 --- a/README.rdoc +++ b/README.rdoc @@ -22,7 +22,7 @@ pick up if available. == Routes -In Sinatra, a route is an HTTP method paired with an URL matching pattern. +In Sinatra, a route is an HTTP method paired with a URL-matching pattern. Each route is associated with a block: get '/' do @@ -130,7 +130,7 @@ You can easily define your own conditions: The return value of a route block determines at least the response body passed on to the HTTP client, or at least the next middleware in the Rack stack. -Most commonly this is a string, as in the above examples. But other values are +Most commonly, this is a string, as in the above examples. But other values are also accepted. You can return any object that would either be a valid Rack response, Rack @@ -141,7 +141,7 @@ body object or HTTP status code: * An object that responds to #each and passes nothing but strings to the given block * A Fixnum representing the status code -That way we can for instance easily implement a streaming example: +That way we can, for instance, easily implement a streaming example: class Stream def each @@ -212,8 +212,8 @@ directory. To use a different views directory: One important thing to remember is that you always have to reference templates with symbols, even if they're in a subdirectory (in this -case use :'subdir/template'). You must use a symbol because -otherwise rendering methods will render any strings passed to them +case, use :'subdir/template'). You must use a symbol because +otherwise rendering methods will render any strings passed to them directly. === Haml Templates @@ -315,7 +315,7 @@ The haml or sass gem/library is required to render Sass templa Renders ./views/stylesheet.sass. -{Sass' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options] +{Sass's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options] can be set globally through Sinatra's configurations, see {Options and Configurations}[http://www.sinatrarb.com/configuration.html], and overridden on an individual basis. @@ -339,7 +339,7 @@ The haml or sass gem/library is required to render Scss templa Renders ./views/stylesheet.scss. -{Scss' options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options] +{Scss's options}[http://sass-lang.com/docs/yardoc/file.SASS_REFERENCE.html#options] can be set globally through Sinatra's configurations, see {Options and Configurations}[http://www.sinatrarb.com/configuration.html], and overridden on an individual basis. @@ -706,9 +706,9 @@ learn more about Tilt. == Filters -+before+ filters are evaluated before each request within the same -context as the routes. They can modify the request and the response. Instance -variables set in these filters are accessible by routes and templates: +Before filters are evaluated before each request within the same +context as the routes will be and can modify the request and response. Instance +variables set in filters are accessible by routes and templates: before do @note = 'Hi!' @@ -720,20 +720,20 @@ variables set in these filters are accessible by routes and templates: params[:splat] #=> 'bar/baz' end -+after+ filters are evaluated after each request within the same context -and can also modify the request and the response. Instance variables set in -+before+ filters and routes are accessible by +after+ filters: +After filters are evaluated after each request within the same context and can +also modify the request and response. Instance variables set in before filters +and routes are accessible by after filters: after do - puts response.status + put response.status end Note: Unless you use the +body+ method rather than just returning a String from the routes, the body will not yet be available in the after filter, since it is generated later on. -Filters optionally taking a pattern will cause them to be evaluated only if -the request path matches the pattern: +Filters optionally take a pattern, causing them to be evaluated only if the +request path matches that pattern: before '/protected/*' do authenticate! @@ -743,7 +743,7 @@ the request path matches the pattern: session[:last_slug] = slug end -Like routes, filters may also take conditions: +Like routes, filters also take conditions: before :agent => /Songbird/ do # ... @@ -823,7 +823,7 @@ With headers: === Passing -A route can punt processing to the next matching route using pass: +A route can put processing to the next matching route using pass: get '/guess/:who' do pass unless params[:who] == 'Frank' @@ -852,7 +852,7 @@ of calling another route. Simply use +call+ to achieve this: end Note that in the example above, you would ease testing and increase performance -by simply moving "bar" into a helper method used by both /foo +by simply moving "bar" into a helper used by both /foo and /bar. If you want the request to be sent to the same application instance rather than @@ -876,10 +876,10 @@ access the body: puts body end -It is also possible to pass a block to +body+, that will be executed by the Rack +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 +body+, you can also set the status code and headers: +Similar to the body, you can also set the status code and headers: get '/foo' do status 418 @@ -915,8 +915,7 @@ Haml: It takes reverse proxies and Rack routers into account, if present. -This method is also aliased to +to+ (see below) for an -example). +This method is also aliased to +to+ (see below for an example). === Browser Redirect @@ -1016,7 +1015,7 @@ It also takes a couple of options: The options are: [filename] - file name in response, defaults to the real file name. + file name, in response, defaults to the real file name. [last_modified] value for Last-Modified header, defaults to the file's mtime. @@ -1067,7 +1066,7 @@ error handlers) through the request method: request.env # raw env hash handed in by Rack end -Some options, like script_name or path_info can also be +Some options, like script_name or path_info, can also be written: before { request.path_info = "/" } @@ -1121,7 +1120,7 @@ able to use more than one view directory: end end -Another example would be to use different directories for different engines: +Another example would be using different directories for different engines: set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views' @@ -1274,7 +1273,7 @@ You can access those options via settings: == Error Handling -Error handlers run within the same context as routes and +before+ filters, which +Error handlers run within the same context as routes and before filters, which means you get all the goodies it has to offer, like haml, erb, halt, etc. @@ -1364,7 +1363,7 @@ accepts multiple/variable args as well as blocks: Rack is distributed with a variety of standard middleware for logging, debugging, URL routing, authentication, and session handling. Sinatra uses -many of of these components automatically based on configuration so you +many of these components automatically based on configuration so you typically don't have to +use+ them explicitly. == Testing @@ -1428,7 +1427,7 @@ The methods available to Sinatra::Base subclasses are exactly as those available via the top-level DSL. Most top-level apps can be converted to Sinatra::Base components with two modifications: -* Your file should require +sinatra/base+ instead of +sinatra+; +* Your file should require +sinatra/base+ instead of +sinatra+; otherwise, all of Sinatra's DSL methods are imported into the main namespace. * Put your app's routes, error handlers, filters, and options in a subclass @@ -1440,15 +1439,15 @@ for details on available options and their behavior. === Modular vs. Classic Style -Contrary to common believes, there is nothing wrong with classic style. If it +Contrary to common belief, there is nothing wrong with classic style. If it suits your application, you do not have to switch to a modular application. -There are only two downsides compared to modular style: +There are only two downsides compared with modular style: -* You may only have one Sinatra application per Ruby process - if you plan to +* You may only have one Sinatra application per Ruby process. If you plan to use more, switch to modular style. -* Classic style pollutes Object with delegator methods - if you plan to ship +* Classic style pollutes Object with delegator methods. If you plan to ship your application in a library/gem, switch to modular style. There is no reason you cannot mix modular and classic style. @@ -1476,7 +1475,7 @@ There are two common options for starting a modular app, actively starting with class MyApp < Sinatra::Base # ... app code here ... - # start the server if ruby file is executed directly + # start the server if ruby file executed directly run! if app_file == $0 end @@ -1567,7 +1566,7 @@ 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 +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 single application class @@ -1630,8 +1629,8 @@ You have the request scope binding inside: === Delegation Scope The delegation scope just forwards methods to the class scope. However, it -does not behave 100% like the class scope, as you do not have the class' -binding: Only methods explicitly marked for delegation are available and you +does not behave 100% like the class scope, as you do not have the class +binding. Only methods explicitly marked for delegation are available and you do not share variables/state with the class scope (read: you have a different +self+). You can explicitly add method delegations by calling Sinatra::Delegator.delegate :method_name. @@ -1725,7 +1724,7 @@ To get some of the latest features. If you want to run your application with the latest Sinatra, using {Bundler}[http://gembundler.com/] is the recommended way. -First, install bundler, if you haven't yet: +First, install bundler, if you haven't: gem install bundler @@ -1739,7 +1738,7 @@ Then, in your project directory, create a +Gemfile+: gem 'activerecord', '~> 3.0' # maybe you also need ActiveRecord 3.x Note that you will have to list all your applications dependencies in there. -Sinatra's direct dependencies (Rack and Tilt) will however be automatically +Sinatra's direct dependencies (Rack and Tilt) will, however, be automatically fetched and added by Bundler. Now you can run your app like this: