railties 3.0.0.beta → 3.0.0.beta2

data/guides/source/migrations.textile

@@ -105,7 +105,7 @@ h4. Creating a Model
 The model and scaffold generators will create migrations appropriate for adding a new model. This migration will already contain instructions for creating the relevant table. If you tell Rails what columns you want then statements for adding those will also be created. For example, running
 
 <shell>
-ruby script/generate model Product name:string description:text
+rails generate model Product name:string description:text
 </shell>
 
 will create a migration that looks like this
@@ -135,7 +135,7 @@ h4. Creating a Standalone Migration
 If you are creating migrations for other purposes (for example to add a column to an existing table) then you can use the migration generator:
 
 <shell>
-ruby script/generate migration AddPartNumberToProducts
+rails generate migration AddPartNumberToProducts
 </shell>
 
 This will create an empty but appropriately named migration:
@@ -153,7 +153,7 @@ end
 If the migration name is of the form "AddXXXToYYY" or "RemoveXXXFromYYY" and is followed by a list of column names and types then a migration containing the appropriate +add_column+ and +remove_column+ statements will be created.
 
 <shell>
-ruby script/generate migration AddPartNumberToProducts part_number:string
+rails generate migration AddPartNumberToProducts part_number:string
 </shell>
 
 will generate
@@ -173,7 +173,7 @@ end
 Similarly,
 
 <shell>
-ruby script/generate migration RemovePartNumberFromProducts part_number:string
+rails generate migration RemovePartNumberFromProducts part_number:string
 </shell>
 
 generates
@@ -193,7 +193,7 @@ end
 You are not limited to one magically generated column, for example
 
 <shell>
-ruby script/generate migration AddDetailsToProducts part_number:string price:decimal
+rails generate migration AddDetailsToProducts part_number:string price:decimal
 </shell>
 
 generates

data/guides/source/performance_testing.textile

@@ -37,7 +37,7 @@ h4. Generating Performance Tests
 Rails provides a generator called +performance_test+ for creating new performance tests:
 
 <shell>
-script/generate performance_test homepage
+rails generate performance_test homepage
 </shell>
 
 This generates +homepage_test.rb+ in the +test/performance+ directory:
@@ -381,19 +381,19 @@ h4. +benchmarker+
 Usage:
 
 <shell>
-$ script/performance/benchmarker [times] 'Person.expensive_way' 'Person.another_expensive_way' ...
+$ rails benchmarker [times] 'Person.expensive_way' 'Person.another_expensive_way' ...
 </shell>
 
 Examples:
 
 <shell>
-$ script/performance/benchmarker 10 'Item.all' 'CouchItem.all'
+$ rails benchmarker 10 'Item.all' 'CouchItem.all'
 </shell>
 
 If the +[times]+ argument is omitted, supplied methods are run just once:
 
 <shell>
-$ script/performance/benchmarker 'Item.first' 'Item.last'
+$ rails benchmarker 'Item.first' 'Item.last'
 </shell>
 
 h4. +profiler+
@@ -403,19 +403,19 @@ h4. +profiler+
 Usage:
 
 <shell>
-$ script/performance/profiler 'Person.expensive_method(10)' [times] [flat|graph|graph_html]
+$ rails profiler 'Person.expensive_method(10)' [times] [flat|graph|graph_html]
 </shell>
 
 Examples:
 
 <shell>
-$ script/performance/profiler 'Item.all'
+$ rails profiler 'Item.all'
 </shell>
 
 This will profile +Item.all+ in +RubyProf::WALL_TIME+ measure mode. By default, it prints flat output to the shell.
 
 <shell>
-$ script/performance/profiler 'Item.all' 10 graph
+$ rails profiler 'Item.all' 10 graph
 </shell>
 
 This will profile +10.times { Item.all }+ with +RubyProf::WALL_TIME+ measure mode and print graph output to the shell.
@@ -423,7 +423,7 @@ This will profile +10.times { Item.all }+ with +RubyProf::WALL_TIME+ measure mod
 If you want to store the output in a file:
 
 <shell>
-$ script/performance/profiler 'Item.all' 10 graph 2> graph.txt
+$ rails profiler 'Item.all' 10 graph 2> graph.txt
 </shell>
 
 h3. Helper Methods

data/guides/source/plugins.textile

@@ -39,9 +39,9 @@ The examples in this guide require that you have a working rails application.  T
 gem install rails
 rails yaffle_guide
 cd yaffle_guide
-script/generate scaffold bird name:string
+rails generate scaffold bird name:string
 rake db:migrate
-script/server
+rails server
 </pre>
 
 Then navigate to http://localhost:3000/birds.  Make sure you have a functioning rails app before continuing.
@@ -57,16 +57,16 @@ This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as
 
 Examples:
 <pre>
-./script/generate plugin yaffle
-./script/generate plugin yaffle --with-generator
+rails generate plugin yaffle
+rails generate plugin yaffle --with-generator
 </pre>
 
-To get more detailed help on the plugin generator, type +./script/generate plugin+.
+To get more detailed help on the plugin generator, type +rails generate plugin+.
 
 Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the +--with-generator+ option now:
 
 <pre>
-./script/generate plugin yaffle --with-generator
+rails generate plugin yaffle --with-generator
 </pre>
 
 You should see the following output:
@@ -104,7 +104,7 @@ To make it easy to organize your files and to make the plugin more compatible wi
     `-- init.rb
 </pre>
 
-*vendor/plugins/yaffle/rails/init.rb*
+*vendor/plugins/yaffle/init.rb*
 
 <ruby>
 require 'yaffle'
@@ -334,20 +334,22 @@ end
 To test that your method does what it says it does, run the unit tests with +rake+ from your plugin directory.  To see this in action, fire up a console and start squawking:
 
 <shell>
-$ ./script/console
+$ rails console
 >> "Hello World".to_squawk
 => "squawk! Hello World"
 </shell>
 
 h4. Working with +init.rb+
 
-When rails loads plugins it looks for the file named 'init.rb' or 'rails/init.rb'.  However, when the plugin is initialized, 'init.rb' is invoked via +eval+ (not +require+) so it has slightly different behavior.
+When Rails loads plugins it looks for a file named +init.rb+.  However, when the plugin is initialized, +init.rb+ is invoked via +eval+ (not +require+) so it has slightly different behavior.
 
-Under certain circumstances if you reopen classes or modules in 'init.rb' you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from +init.rb+, as shown above.
+NOTE: The plugins loader also looks for +rails/init.rb+, but that one is deprecated in favor of the top-level +init.rb+ aforementioned.
+
+Under certain circumstances if you reopen classes or modules in +init.rb+ you may inadvertently create a new class, rather than reopening an existing class.  A better alternative is to reopen the class in a different file, and require that file from +init.rb+, as shown above.
 
 If you must reopen a class in +init.rb+ you can use +module_eval+ or +class_eval+ to avoid any issues:
 
-* *vendor/plugins/yaffle/rails/init.rb*
+* *vendor/plugins/yaffle/init.rb*
 
 <ruby>
 Hash.class_eval do
@@ -359,7 +361,7 @@ end
 
 Another way is to explicitly define the top-level module space for all modules and classes, like +::Hash+:
 
-* *vendor/plugins/yaffle/rails/init.rb*
+* *vendor/plugins/yaffle/init.rb*
 
 <ruby>
 class ::Hash
@@ -871,7 +873,7 @@ If you plan to distribute your plugin, developers will expect at least a minimum
 Rails ships with several built-in generators.  You can see all of the generators available to you by typing the following at the command line:
 
 <shell>
-./script/generate
+rails generate
 </shell>
 
 You should see something like this:
@@ -882,7 +884,7 @@ Installed Generators
   Builtin: controller, integration_test, mailer, migration, model, observer, plugin, resource, scaffold, session_migration
 </shell>
 
-When you run +script/generate yaffle_definition -h+ you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle_definition/USAGE'.
+When you run +rails generate yaffle_definition -h+ you should see the contents of your 'vendor/plugins/yaffle/generators/yaffle_definition/USAGE'.
 
 For this plugin, update the USAGE file could look like this:
 
@@ -1111,11 +1113,11 @@ end
 To see this work, type:
 
 <shell>
-./script/generate yaffle_route
-./script/destroy yaffle_route
+rails generate yaffle_route
+rails destroy yaffle_route
 </shell>
 
-NOTE: If you haven't set up the custom route from above, 'script/destroy' will fail and you'll have to remove it manually.
+NOTE: If you haven't set up the custom route from above, 'rails destroy' will fail and you'll have to remove it manually.
 
 h3. Migrations
 
@@ -1195,7 +1197,7 @@ h4. Generate Migrations
 
 Generating migrations has several advantages over other methods.  Namely, you can allow other developers to more easily customize the migration.  The flow looks like this:
 
- * call your script/generate script and pass in whatever options they need
+ * call your rails generate script and pass in whatever options they need
  * examine the generated migration, adding/removing columns or other options as necessary
 
 This example will demonstrate how to use one of the built-in generator methods named 'migration_template' to create a migration file.  Extending the rails migration generator requires a somewhat intimate knowledge of the migration generator internals, so it's best to write a test first:
@@ -1289,7 +1291,7 @@ It's courteous to check to see if table names are being pluralized whenever you
 To run the generator, type the following at the command line:
 
 <shell>
-./script/generate yaffle_migration bird
+rails generate yaffle_migration bird
 </shell>
 
 and you will see a new file:
@@ -1333,15 +1335,15 @@ yaffle:squawk             # Prints out the word 'Yaffle'
 
 You can add as many files as you want in the tasks directory, and if they end in .rake Rails will pick them up.
 
-Note that tasks from 'vendor/plugins/yaffle/Rakefile' are not available to the main app.
+Note that tasks from +vendor/plugins/yaffle/Rakefile+ are not available to the main app.
 
-h3. PluginGems
+h3. Plugins as Gems
 
 Turning your rails plugin into a gem is a simple and straightforward task.  This section will cover how to turn your plugin into a gem.  It will not cover how to distribute that gem.
 
-Historically rails plugins loaded the plugin's 'init.rb' file.  In fact some plugins contain all of their code in that one file.  To be compatible with plugins, 'init.rb' was moved to 'rails/init.rb'.
+The initialization file has to be called +rails/init.rb+, the root +init.rb+ file, if any, is ignored by Rails. Also, the name of the plugin now is relevant since +config.gem+ tries to load it. Either name the main file after your gem, or document that users should use the +:lib+ option.
 
-It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in 'Rakefile'.  A rake task that packages the gem might look like this:
+It's common practice to put any developer-centric rake tasks (such as tests, rdoc and gem package tasks) in +Rakefile+.  A rake task that packages the gem might look like this:
 
 * *vendor/plugins/yaffle/Rakefile:*
 
@@ -1383,7 +1385,7 @@ rake gem
 sudo gem install pkg/yaffle-0.0.1.gem
 </shell>
 
-To test this, create a new rails app, add 'config.gem "yaffle"' to environment.rb and all of your plugin's functionality will be available to you.
+To test this, create a new rails app, add +config.gem "yaffle"+ to +config/environment.rb+ and all of your plugin's functionality will be available to you.
 
 h3. RDoc Documentation
 

data/guides/source/rails_on_rack.textile

@@ -30,11 +30,11 @@ h4. Rails Application's Rack Object
 
 <tt>ActionController::Dispatcher.new</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using +ActionController::Dispatcher.new+ object to serve a Rails application.</p>
 
-h4. +script/server+
+h4. +rails server+
 
-<tt>script/server</tt> does the basic job of creating a +Rack::Builder+ object and starting the webserver. This is Rails' equivalent of Rack's +rackup+ script.
+<tt>rails server</tt> does the basic job of creating a +Rack::Builder+ object and starting the webserver. This is Rails' equivalent of Rack's +rackup+ script.
 
-Here's how +script/server+ creates an instance of +Rack::Builder+
+Here's how +rails server+ creates an instance of +Rack::Builder+
 
 <ruby>
 app = Rack::Builder.new {
@@ -54,7 +54,7 @@ Middlewares used in the code above are primarily useful only in the development
 
 h4. +rackup+
 
-To use +rackup+ instead of Rails' +script/server+, you can put the following inside +config.ru+ of your Rails application's root directory:
+To use +rackup+ instead of Rails' +rails server+, you can put the following inside +config.ru+ of your Rails application's root directory:
 
 <ruby>
 # RAILS_ROOT/config.ru
@@ -233,7 +233,7 @@ h4. Generating a Metal Application
 Rails provides a generator called +metal+ for creating a new Metal application:
 
 <shell>
-$ script/generate metal poller
+$ rails generate metal poller
 </shell>
 
 This generates +poller.rb+ in the +app/metal+ directory:

data/guides/source/routing.textile

@@ -4,7 +4,7 @@ This guide covers the user-facing features of Rails routing. By referring to thi
 
 * Understand the purpose of routing
 * Decipher the code in +routes.rb+
-* Construct your own routes, using either the classic hash style or the now-preferred RESTful style
+* Construct your own routes, using either the @match@ method or the preferred RESTful style
 * Identify how a route will map to a controller and action
 
 endprologue.
@@ -37,7 +37,7 @@ Routing also works in reverse. If your application contains this code:
 
 Then the routing engine is the piece that translates that to a link to a URL such as +http://example.com/patients/17+. By using routing in this way, you can reduce the brittleness of your application as compared to one with hard-coded URLs, and make your code easier to read and understand.
 
-NOTE: Patient needs to be declared as a resource for this style of translation via a named route to be available.
+NOTE: Patient needs to be declared as a Restful resource for this style of translation to be available.
 
 h3. Quick Tour of +routes.rb+
 
@@ -45,7 +45,7 @@ There are two components to routing in Rails: the routing engine itself, which i
 
 h4. Processing the File
 
-In format, +routes.rb+ is nothing more than one big block sent to +ActionController::Routing::Routes.draw+. Within this block, you can have comments, but it's likely that most of your content will be individual lines of code - each line being a route in your application. You'll find five main types of content in this file:
+In format, +routes.rb+ is nothing more than one big block sent to +ApplicationName::Application.routes.draw+. Within this block, you can have comments, but it's likely that most of your content will be individual lines of code - each line being a route in your application. You'll find five main types of content in this file:
 
 * RESTful Routes
 * Named Routes
@@ -55,31 +55,39 @@ In format, +routes.rb+ is nothing more than one big block sent to +ActionControl
 
 Each of these types of route is covered in more detail later in this guide.
 
-The +routes.rb+ file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route. If there is no matching route, then Rails returns HTTP status 404 to the caller.
+The +routes.rb+ file is processed from top to bottom when a request comes in. The request will be dispatched to the first matching route, and then proceeds to the next. If there is no matching route, then Rails returns HTTP status 404 to the caller.
 
 h4. RESTful Routes
 
-RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information in a single declaration. A RESTful route looks like this:
+RESTful routes take advantage of the built-in REST orientation of Rails to wrap up a lot of routing information with a single declaration. A RESTful route looks like this:
 
 <ruby>
-map.resources :books
+resources :books
 </ruby>
 
 h4. Named Routes
 
 Named routes give you very readable links in your code, as well as handling incoming requests. Here's a typical named route:
 
+<ruby>
+match 'login' => 'sessions#new', :as => 'login'
+</ruby>
+
+If you're coming from Rails 2, this route will be equivalent to:
+
 <ruby>
 map.login '/login', :controller => 'sessions', :action => 'new'
 </ruby>
 
+You will also notice that +sessions#new+ is a shorthand for +:controller => 'sessions', :action => 'new'+. By declaring a named route such as this, you can use +login_path+ or +login_url+ in your controllers and views to generate the URLs for this route.
+
 h4. Nested Routes
 
 Nested routes let you declare that one resource is contained within another resource. You'll see later on how this translates to URLs and paths in your code. For example, if your application includes parts, each of which belongs to an assembly, you might have this nested route declaration:
 
 <ruby>
-map.resources :assemblies do |assemblies|
-  assemblies.resources :parts
+resources :assemblies do
+  resources :parts
 end
 </ruby>
 
@@ -88,19 +96,18 @@ h4. Regular Routes
 In many applications, you'll also see non-RESTful routing, which explicitly connects the parts of a URL to a particular action. For example,
 
 <ruby>
-map.connect 'parts/:number', :controller => 'inventory', :action => 'show'
+match 'parts/:number' => 'inventory#show'
 </ruby>
 
 h4. Default Routes
 
-The default routes are a safety net that catch otherwise-unrouted requests. Many Rails applications will contain this pair of default routes:
+The default route is a safety net that catches otherwise-unrouted requests. Many Rails applications will contain this default route:
 
 <ruby>
-map.connect ':controller/:action/:id'
-map.connect ':controller/:action/:id.:format'
+match ':controller(/:action(/:id(.:format)))'
 </ruby>
 
-These default routes are automatically generated when you create a new Rails application. If you're using RESTful routing for everything in your application, you will probably want to remove them. But be sure you're not using the default routes before you remove them!
+In Rails 3, this route is commented out advising to use RESTful routes as much as possible. So if you're using RESTful routing for everything in your application, you will probably want to leave it like that.
 
 h3. RESTful Routing: the Rails Default
 
@@ -126,7 +133,7 @@ h4. CRUD, Verbs, and Actions
 In Rails, a RESTful route provides a mapping between HTTP verbs, controller actions, and (implicitly) CRUD operations in a database. A single entry in the routing file, such as
 
 <ruby>
-map.resources :photos
+resources :photos
 </ruby>
 
 creates seven different routes in your application:
@@ -142,11 +149,9 @@ creates seven different routes in your application:
 
 For the specific routes (those that reference just a single resource), the identifier for the resource will be available within the corresponding controller action as +params[:id]+.
 
-TIP: If you consistently use RESTful routes in your application, you should disable the default routes in +routes.rb+ so that Rails will enforce the mapping between HTTP verbs and routes.
-
 h4. URLs and Paths
 
-Creating a RESTful route will also make available a pile of helpers within your application:
+Creating a RESTful route will also make available a pile of helpers within your application, something that requires explicit mention otherwise:
 
 * +photos_url+ and +photos_path+ map to the path for the index and create actions
 * +new_photo_url+ and +new_photo_path+ map to the path for the new action
@@ -164,26 +169,26 @@ photos_path # => "/photos"
 
 h4. Defining Multiple Resources at the Same Time
 
-If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to +map.resources+:
+If you need to create routes for more than one RESTful resource, you can save a bit of typing by defining them all with a single call to +resources+:
 
 <ruby>
-map.resources :photos, :books, :videos
+resources :photos, :books, :videos
 </ruby>
 
 This has exactly the same effect as
 
 <ruby>
-map.resources :photos
-map.resources :books
-map.resources :videos
+resources :photos
+resources :books
+resources :videos
 </ruby>
 
 h4. Singular Resources
 
-You can also apply RESTful routing to singleton resources within your application. In this case, you use +map.resource+ instead of +map.resources+ and the route generation is slightly different. For example, a routing entry of
+You can also apply RESTful routing to singleton resources within your application. In this case, you use +resource+ instead of +resources+ and the route generation is slightly different. For example, a routing entry of
 
 <ruby>
-map.resource :geocoder
+resource :geocoder
 </ruby>
 
 creates six different routes in your application:
@@ -214,19 +219,17 @@ Although the conventions of RESTful routing are likely to be sufficient for many
 * +:conditions+
 * +:as+
 * +:path_names+
-* +:path_prefix+
-* +:name_prefix+
 * +:only+
 * +:except+
 
-You can also add additional routes via the +:member+ and +:collection+ options, which are discussed later in this guide.
+You can also add additional routes via the +member+ and +collection+ blocks, which are discussed later in this guide.
 
 h5. Using +:controller+
 
 The +:controller+ option lets you use a controller name that is different from the public-facing resource name. For example, this routing entry:
 
 <ruby>
-map.resources :photos, :controller => "images"
+resources :photos, :controller => "images"
 </ruby>
 
 will recognize incoming URLs containing +photo+ but route the requests to the Images controller:
@@ -247,35 +250,37 @@ h4. Controller Namespaces and Routing
 Rails allows you to group your controllers into namespaces by saving them in folders underneath +app/controllers+. The +:controller+ option provides a convenient way to use these routes. For example, you might have a resource whose controller is purely for admin users in the +admin+ folder:
 
 <ruby>
-map.resources :adminphotos, :controller => "admin/photos"
+resources :photos, :controller => "admin/photos"
 </ruby>
 
-If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the +adminphoto_path+ helper, and you follow a link generated with +&lt;%= link_to "show", adminphoto(1) %&gt;+ you will end up on the view generated by +admin/photos/show+, but you will also end up in the same place if you have +&lt;%= link_to "show", {:controller => "photos", :action => "show"} %&gt;+ because Rails will generate the show URL relative to the current URL.
+If you use controller namespaces, you need to be aware of a subtlety in the Rails routing code: it always tries to preserve as much of the namespace from the previous request as possible. For example, if you are on a view generated from the +photo_path+ helper, and you follow a link generated with +&lt;%= link_to "show", photo_path(1) %&gt;+ you will end up on the view generated by +admin/photos/show+, but you will also end up in the same place if you have +&lt;%= link_to "show", {:controller => "photos", :action => "show"} %&gt;+ because Rails will generate the show URL relative to the current URL.
 
 TIP: If you want to guarantee that a link goes to a top-level controller, use a preceding slash to anchor the controller name: +&lt;%= link_to "show", {:controller => "/photos", :action => "show"} %&gt;+
 
 You can also specify a controller namespace with the +:namespace+ option instead of a path:
 
 <ruby>
-map.resources :adminphotos, :namespace => "admin", :controller => "photos"
+resources :adminphotos, :namespace => "admin", :controller => "photos"
 </ruby>
 
-This can be especially useful when combined with +with_options+ to map multiple namespaced routes together:
+This can be especially useful when map multiple namespaced routes together using +namespace+ block by:
 
 <ruby>
-map.with_options(:namespace => "admin") do |admin|
-  admin.resources :photos, :videos
+namespace :admin do
+  resources :photos, :videos
 end
 </ruby>
 
-That would give you routing for +admin/photos+ and +admin/videos+ controllers.
+That would give you routing for +admin/photos+ and +admin/videos+ controllers. 
+
+The difference between generating routes through +namespace+ and the +:controller+ key is that the +namespace+ will add +admin+ to the generated helpers as well, so the above route generates +admin_photos_path+.
 
 h5. Using +:singular+
 
 If for some reason Rails isn't doing what you want in converting the plural resource name to a singular name in member routes, you can override its judgment with the +:singular+ option:
 
 <ruby>
-map.resources :teeth, :singular => "tooth"
+resources :teeth, :singular => "tooth"
 </ruby>
 
 TIP: Depending on the other code in your application, you may prefer to add additional rules to the +Inflector+ class instead.
@@ -285,7 +290,7 @@ h5. Using +:requirements+
 You can use the +:requirements+ option in a RESTful route to impose a format on the implied +:id+ parameter in the singular routes. For example:
 
 <ruby>
-map.resources :photos, :requirements => {:id => /[A-Z][A-Z][0-9]+/}
+resources :photos, :requirements => {:id => /[A-Z][A-Z][0-9]+/}
 </ruby>
 
 This declaration constrains the +:id+ parameter to match the supplied regular expression. So, in this case, +/photos/1+ would no longer be recognized by this route, but +/photos/RR27+ would.
@@ -299,7 +304,7 @@ h5. Using +:as+
 The +:as+ option lets you override the normal naming for the actual generated paths. For example:
 
 <ruby>
-map.resources :photos, :as => "images"
+resources :photos, :as => "images"
 </ruby>
 
 will recognize incoming URLs containing +image+ but route the requests to the Photos controller:
@@ -320,7 +325,7 @@ h5. Using +:path_names+
 The +:path_names+ option lets you override the automatically-generated "new" and "edit" segments in URLs:
 
 <ruby>
-map.resources :photos, :path_names => { :new => 'make', :edit => 'change' }
+resources :photos, :path_names => { :new => 'make', :edit => 'change' }
 </ruby>
 
 This would cause the routing to recognize URLs such as
@@ -343,7 +348,7 @@ h5. Using +:path_prefix+
 The +:path_prefix+ option lets you add additional parameters that will be prefixed to the recognized paths. For example, suppose each photo in your application belongs to a particular photographer. In that case, you might declare this route:
 
 <ruby>
-map.resources :photos, :path_prefix => '/photographers/:photographer_id'
+resources :photos, :path_prefix => '/photographers/:photographer_id'
 </ruby>
 
 Routes recognized by this entry would include:
@@ -362,9 +367,9 @@ h5. Using +:name_prefix+
 You can use the :name_prefix option to avoid collisions between routes. This is most useful when you have two resources with the same name that use +:path_prefix+ to map differently. For example:
 
 <ruby>
-map.resources :photos, :path_prefix => '/photographers/:photographer_id',
+resources :photos, :path_prefix => '/photographers/:photographer_id',
   :name_prefix => 'photographer_'
-map.resources :photos, :path_prefix => '/agencies/:agency_id',
+resources :photos, :path_prefix => '/agencies/:agency_id',
   :name_prefix => 'agency_'
 </ruby>
 
@@ -377,7 +382,7 @@ h5. Using +:only+ and +:except+
 By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the +:only+ and +:except+ options to fine-tune this behavior. The +:only+ option specifies that only certain routes should be generated:
 
 <ruby>
-map.resources :photos, :only => [:index, :show]
+resources :photos, :only => [:index, :show]
 </ruby>
 
 With this declaration, a +GET+ request to +/photos+ would succeed, but a +POST+ request to +/photos+ (which would ordinarily be routed to the create action) will fail.
@@ -385,7 +390,7 @@ With this declaration, a +GET+ request to +/photos+ would succeed, but a +POST+
 The +:except+ option specifies a route or list of routes that should _not_ be generated:
 
 <ruby>
-map.resources :photos, :except => :destroy
+resources :photos, :except => :destroy
 </ruby>
 
 In this case, all of the normal routes except the route for +destroy+ (a +DELETE+ request to +/photos/<em>id</em>+) will be generated.
@@ -411,12 +416,12 @@ end
 Each ad is logically subservient to one magazine. Nested routes allow you to capture this relationship in your routing. In this case, you might include this route declaration:
 
 <ruby>
-map.resources :magazines do |magazine|
-  magazine.resources :ads
+resources :magazines do
+  resources :ads
 end
 </ruby>
 
-TIP: Further below you'll learn about a convenient shortcut for this construct:<br/>+map.resources :magazines, :has_many => :ads+
+TIP: Further below you'll learn about a convenient shortcut for this construct:<br/>+resources :magazines, :has_many => :ads+
 
 In addition to the routes for magazines, this declaration will also create routes for ads, each of which requires the specification of a magazine in the URL:
 
@@ -437,16 +442,16 @@ h5. Using +:name_prefix+
 The +:name_prefix+ option overrides the automatically-generated prefix in nested route helpers. For example,
 
 <ruby>
-map.resources :magazines do |magazine|
-  magazine.resources :ads, :name_prefix => 'periodical'
+resources :magazines do
+  resources :ads, :name_prefix => 'periodical'
 end
 </ruby>
 
 This will create routing helpers such as +periodical_ads_url+ and +periodical_edit_ad_path+. You can even use +:name_prefix+ to suppress the prefix entirely:
 
 <ruby>
-map.resources :magazines do |magazine|
-  magazine.resources :ads, :name_prefix => nil
+resources :magazines do
+  resources :ads, :name_prefix => nil
 end
 </ruby>
 
@@ -462,16 +467,16 @@ h5. Using +:has_one+ and +:has_many+
 The +:has_one+ and +:has_many+ options provide a succinct notation for simple nested routes. Use +:has_one+ to nest a singleton resource, or +:has_many+ to nest a plural resource:
 
 <ruby>
-map.resources :photos, :has_one => :photographer, :has_many => [:publications, :versions]
+resources :photos, :has_one => :photographer, :has_many => [:publications, :versions]
 </ruby>
 
 This has the same effect as this set of declarations:
 
 <ruby>
-map.resources :photos do |photo|
-  photo.resource :photographer
-  photo.resources :publications
-  photo.resources :versions
+resources :photos do
+  resource :photographer
+  resources :publications
+  resources :versions
 end
 </ruby>
 
@@ -480,9 +485,9 @@ h5. Limits to Nesting
 You can nest resources within other nested resources if you like. For example:
 
 <ruby>
-map.resources :publishers do |publisher|
-  publisher.resources :magazines do |magazine|
-    magazine.resources :photos
+resources :publishers do
+  resources :magazines do
+    resources :photos
   end
 end
 </ruby>
@@ -502,9 +507,9 @@ h5. Shallow Nesting
 The +:shallow+ option provides an elegant solution to the difficulties of deeply-nested routes. If you specify this option at any level of routing, then paths for nested resources which reference a specific member (that is, those with an +:id+ parameter) will not use the parent path prefix or name prefix. To see what this means, consider this set of routes:
 
 <ruby>
-map.resources :publishers, :shallow => true do |publisher|
-  publisher.resources :magazines do |magazine|
-    magazine.resources :photos
+resources :publishers, :shallow => true do
+  resources :magazines do
+    resources :photos
   end
 end
 </ruby>
@@ -522,7 +527,7 @@ This will enable recognition of (among others) these routes:
 With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with. If you like, you can combine shallow nesting with the +:has_one+ and +:has_many+ options:
 
 <ruby>
-map.resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
+resources :publishers, :has_many => { :magazines => :photos }, :shallow => true
 </ruby>
 
 h4. Route Generation from Arrays
@@ -530,8 +535,8 @@ h4. Route Generation from Arrays
 In addition to using the generated routing helpers, Rails can also generate RESTful routes from an array of parameters. For example, suppose you have a set of routes generated with these entries in routes.rb:
 
 <ruby>
-map.resources :magazines do |magazine|
-  magazine.resources :ads
+resources :magazines do
+  resources :ads
 end
 </ruby>
 
@@ -554,17 +559,16 @@ h4. Namespaced Resources
 It's possible to do some quite complex things by combining +:path_prefix+ and +:name_prefix+. For example, you can use the combination of these two options to move administrative resources to their own folder in your application:
 
 <ruby>
-map.resources :photos, :path_prefix => 'admin', :controller => 'admin/photos'
-map.resources :tags, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_tags'
-map.resources :ratings, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_ratings'
+resources :photos, :path_prefix => 'admin', :controller => 'admin/photos'
+resources :tags, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_tags'
+resources :ratings, :name_prefix => 'admin_photo_', :path_prefix => 'admin/photos/:photo_id', :controller => 'admin/photo_ratings'
 </ruby>
 
 The good news is that if you find yourself using this level of complexity, you can stop. Rails supports _namespaced resources_ to make placing resources in their own folder a snap. Here's the namespaced version of those same three routes:
 
 <ruby>
-map.namespace(:admin) do |admin|
-	admin.resources :photos,
-	  :has_many => { :tags, :ratings}
+namespace :admin do
+	resources :photos, :has_many => { :tags, :ratings }
 end
 </ruby>
 
@@ -576,18 +580,24 @@ You are not limited to the seven routes that RESTful routing creates by default.
 
 h5. Adding Member Routes
 
-To add a member route, use the +:member+ option:
+To add a member route, just add +member+ block into resource block:
 
 <ruby>
-map.resources :photos, :member => { :preview => :get }
+resources :photos do
+  member do
+    get :preview
+  end
+end
 </ruby>
 
 This will enable Rails to recognize URLs such as +/photos/1/preview+ using the GET HTTP verb, and route them to the preview action of the Photos controller. It will also create the +preview_photo_url+ and +preview_photo_path+ route helpers.
 
-Within the hash of member routes, each route name specifies the HTTP verb that it will recognize. You can use +:get+, +:put+, +:post+, +:delete+, or +:any+ here. You can also specify an array of methods, if you need more than one but you don't want to allow just anything:
+Within the block of member routes, each route name specifies the HTTP verb that it will recognize. You can use +get+, +put+, +post+, +delete+, or +any+ here. If you don't have multiple +member+ route, you can also passing +:on+ to the routing.
 
 <ruby>
-map.resources :photos, :member => { :prepare => [:get, :post] }
+resources :photos do
+  get :preview, :on => :member
+end
 </ruby>
 
 h5. Adding Collection Routes
@@ -595,32 +605,35 @@ h5. Adding Collection Routes
 To add a collection route, use the +:collection+ option:
 
 <ruby>
-map.resources :photos, :collection => { :search => :get }
+resources :photos do
+  collection do
+    get :search
+  end
+end
 </ruby>
 
 This will enable Rails to recognize URLs such as +/photos/search+ using the GET HTTP verb, and route them to the search action of the Photos controller. It will also create the +search_photos_url+ and +search_photos_path+ route helpers.
 
-Just as with member routes, you can specify an array of methods for a collection route:
+Just as with member routes, you can passing +:on+ to the routing.
 
 <ruby>
-map.resources :photos, :collection => { :search => [:get, :post] }
+resources :photos do
+  get :search, :on => :collection
+end
 </ruby>
 
 h5. Adding New Routes
 
-To add a new route (one that creates a new resource), use the +:new+ option:
+As of writing, Rails 3 has deprecated +:new+ option from routing. You will need to explicit define the route using +match+ method
 
 <ruby>
-map.resources :photos, :new => { :upload => :post }
+resources :photos
+match 'photos/new/upload' => 'photos#upload', :as => 'upload_new_photos'
 </ruby>
 
-This will enable Rails to recognize URLs such as +/photos/new/upload+ using the POST HTTP verb, and route them to the upload action of the Photos controller. It will also create the +upload_new_photos_path+ and +upload_new_photos_url+ route helpers.
-
-TIP: If you want to redefine the verbs accepted by one of the standard actions, you can do so by explicitly mapping that action. For example:<br/>+map.resources :photos, :new => { :new => :any }+<br/>This will allow the new action to be invoked by any request to +photos/new+, no matter what HTTP verb you use.
-
 h5. A Note of Caution
 
-If you find yourself adding many extra actions to a RESTful route, it's time to stop and ask yourself whether you're disguising the presence of another resource that would be better split off on its own. When the +:member+ and +:collection+ hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.
+If you find yourself adding many extra actions to a RESTful route, it's time to stop and ask yourself whether you're disguising the presence of another resource that would be better split off on its own. When the +member+ and +collection+ hashes become a dumping-ground, RESTful routes lose the advantage of easy readability that is one of their strongest points.
 
 h3. Regular Routes
 
@@ -633,7 +646,7 @@ h4. Bound Parameters
 When you set up a regular route, you supply a series of symbols that Rails maps to parts of an incoming HTTP request. Two of these symbols are special: +:controller+ maps to the name of a controller in your application, and +:action+ maps to the name of an action within that controller. For example, consider one of the default Rails routes:
 
 <ruby>
-map.connect ':controller/:action/:id'
+match ':controller(/:action(/:id))'
 </ruby>
 
 If an incoming request of +/photos/show/1+ is processed by this route (because it hasn't matched any previous route in the file), then the result will be to invoke the +show+ action of the +Photos+ controller, and to make the final parameter (1) available as +params[:id]+.
@@ -643,7 +656,7 @@ h4. Wildcard Components
 You can set up as many wildcard symbols within a regular route as you like. Anything other than +:controller+ or +:action+ will be available to the matching action as part of the params hash. So, if you set up this route:
 
 <ruby>
-map.connect ':controller/:action/:id/:user_id'
+match ':controller/:action/:id/:user_id'
 </ruby>
 
 An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be set to 2.
@@ -653,7 +666,7 @@ h4. Static Text
 You can specify static text when creating a route. In this case, the static text is used only for matching the incoming requests:
 
 <ruby>
-map.connect ':controller/:action/:id/with_user/:user_id'
+match ':controller/:action/:id/with_user/:user_id'
 </ruby>
 
 This route would respond to URLs such as +/photos/show/1/with_user/2+.
@@ -663,17 +676,17 @@ h4. Querystring Parameters
 Rails routing automatically picks up querystring parameters and makes them available in the +params+ hash. For example, with this route:
 
 <ruby>
-map.connect ':controller/:action/:id'
+match ':controller/:action/:id
 </ruby>
 
 An incoming URL of +/photos/show/1?user_id=2+ will be dispatched to the +show+ action of the +Photos+ controller. +params[:id]+ will be set to 1, and +params[:user_id]+ will be equal to 2.
 
 h4. Defining Defaults
 
-You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply defaults for these two parameters in a hash:
+You do not need to explicitly use the +:controller+ and +:action+ symbols within a route. You can supply defaults for these two parameters by putting it after +=>+:
 
 <ruby>
-map.connect 'photos/:id', :controller => 'photos', :action => 'show'
+match 'photos/:id' => 'photos#show'
 </ruby>
 
 With this route, an incoming URL of +/photos/12+ would be dispatched to the +show+ action within the +Photos+ controller.
@@ -681,8 +694,7 @@ With this route, an incoming URL of +/photos/12+ would be dispatched to the +sho
 You can also define other defaults in a route by supplying a hash for the +:defaults+ option. This even applies to parameters that are not explicitly defined elsewhere in the route. For example:
 
 <ruby>
-map.connect 'photos/:id', :controller => 'photos', :action => 'show',
-  :defaults => { :format => 'jpg' }
+match 'photos/:id' => 'photos#show', :defaults => { :format => 'jpg' }
 </ruby>
 
 With this route, an incoming URL of +photos/12+ would be dispatched to the +show+ action within the +Photos+ controller, and +params[:format]+ will be set to +jpg+.
@@ -692,7 +704,7 @@ h4. Named Routes
 Regular routes need not use the +connect+ method. You can use any other name here to create a _named route_. For example,
 
 <ruby>
-map.logout '/logout', :controller => 'sessions', :action => 'destroy'
+match 'logout' => 'sessions#destroy', :as => :logout
 </ruby>
 
 This will do two things. First, requests to +/logout+ will be sent to the +destroy+ action of the +Sessions+ controller. Second, Rails will maintain the +logout_path+ and +logout_url+ helpers for use within your code.
@@ -702,15 +714,13 @@ h4. Route Requirements
 You can use the +:requirements+ option to enforce a format for any parameter in a route:
 
 <ruby>
-map.connect 'photo/:id', :controller => 'photos', :action => 'show',
- :requirements => { :id => /[A-Z]\d{5}/ }
+match 'photo/:id' => 'photos#show', :requirements => { :id => /[A-Z]\d{5}/ }
 </ruby>
 
 This route would respond to URLs such as +/photo/A12345+. You can more succinctly express the same route this way:
 
 <ruby>
-map.connect 'photo/:id', :controller => 'photos', :action => 'show',
-  :id => /[A-Z]\d{5}/
+match 'photo/:id' => 'photos#show', :id => /[A-Z]\d{5}/
 </ruby>
 
 h4. Route Conditions
@@ -718,8 +728,7 @@ h4. Route Conditions
 Route conditions (introduced with the +:conditions+ option) are designed to implement restrictions on routes. Currently, the only supported restriction is +:method+:
 
 <ruby>
-map.connect 'photo/:id', :controller => 'photos', :action => 'show',
- :conditions => { :method => :get }
+match 'photo/:id' => 'photos#show', :conditions => { :method => :get }
 </ruby>
 
 As with conditions in RESTful routes, you can specify +:get+, +:post+, +:put+, +:delete+, or +:any+ for the acceptable method.
@@ -729,7 +738,7 @@ h4. Route Globbing
 Route globbing is a way to specify that a particular parameter should be matched to all the remaining parts of a route. For example
 
 <ruby>
-map.connect 'photo/*other', :controller => 'photos', :action => 'unknown',
+match 'photo/*other' => 'photos#unknown'
 </ruby>
 
 This route would match +photo/12+ or +/photo/long/path/to/12+ equally well, creating an array of path segments as the value of +params[:other]+.
@@ -755,7 +764,7 @@ There's one more way in which routing can do different things depending on diffe
 For instance, consider the second of the default routes in the boilerplate +routes.rb+ file:
 
 <ruby>
-map.connect ':controller/:action/:id.:format'
+match ':controller(/:action(/:id(.:format)))'
 </ruby>
 
 This route matches requests such as +/photo/edit/1.xml+ or +/photo/show/2.rss+. Within the appropriate action code, you can issue different responses depending on the requested format:
@@ -781,11 +790,10 @@ Mime::Type.register "image/jpg", :jpg
 
 h3. The Default Routes
 
-When you create a new Rails application, +routes.rb+ is initialized with two default routes:
+When you create a new Rails application, +routes.rb+ is initialized with a default route:
 
 <ruby>
-map.connect ':controller/:action/:id'
-map.connect ':controller/:action/:id.:format'
+match ':controller(/:action(/:id(.:format)))'
 </ruby>
 
 These routes provide reasonable defaults for many URLs, if you're not using RESTful routing.
@@ -796,31 +804,24 @@ h3. The Empty Route
 
 Don't confuse the default routes with the empty route. The empty route has one specific purpose: to route requests that come in to the root of the web site. For example, if your site is example.com, then requests to +http://example.com+ or +http://example.com/+ will be handled by the empty route.
 
-h4. Using +map.root+
+h4. Using +root+
 
-The preferred way to set up the empty route is with the +map.root+ command:
+The preferred way to set up the empty route is with the +root+ command:
 
 <ruby>
-map.root :controller => "pages", :action => "main"
+root :to => 'pages#main'
 </ruby>
 
 The use of the +root+ method tells Rails that this route applies to requests for the root of the site.
 
-For better readability, you can specify an already-created route in your call to +map.root+:
-
-<ruby>
-map.index 'index', :controller => "pages", :action => "main"
-map.root :index
-</ruby>
-
-Because of the top-down processing of the file, the named route must be specified _before_ the call to +map.root+.
+Because of the top-down processing of the file, the named route must be specified _before_ the call to +root+.
 
 h4. Connecting the Empty String
 
 You can also specify an empty route by explicitly connecting the empty string:
 
 <ruby>
-map.connect '', :controller => "pages", :action => "main"
+match '' => 'pages#main'
 </ruby>
 
 TIP: If the empty route does not seem to be working in your application, make sure that you have deleted the file +public/index.html+ from your Rails tree.
@@ -898,6 +899,7 @@ h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/3
 
+* Febuary 1, 2010: Modifies the routing documentation to match new routing DSL in Rails 3, by Prem Sichanugrist
 * October 4, 2008: Added additional detail on specifying verbs for resource member/collection routes, by "Mike Gunderloy":credits.html#mgunderloy
 * September 23, 2008: Added section on namespaced controllers and routing, by "Mike Gunderloy":credits.html#mgunderloy
 * September 10, 2008: initial version by "Mike Gunderloy":credits.html#mgunderloy