]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/rails.txt
Merge branch 'master' of github.com:benbeltran/dotfiles
[rbdr/dotfiles] / vim / doc / rails.txt
1 *rails.txt* Plugin for working with Ruby on Rails applications
2
3 Author: Tim Pope <http://tpo.pe/>
4
5 |rails-introduction| Introduction and Feature Summary
6 |rails-commands| General Commands
7 |rails-navigation| Navigation
8 |rails-gf| File Under Cursor - gf
9 |rails-alternate-related| Alternate and Related Files
10 |rails-type-navigation| File Type Commands
11 |rails-custom-navigation| Custom Navigation Commands
12 |rails-rake| Rake
13 |rails-scripts| Script Wrappers
14 |rails-refactoring| Refactoring Helpers
15 |rails-partials| Partial Extraction
16 |rails-migrations| Migration Inversion
17 |rails-integration| Integration
18 |rails-vim-integration| Integration with the Vim Universe
19 |rails-rails-integration| Integration with the Rails Universe
20 |rails-abbreviations| Abbreviations
21 |rails-syntax| Syntax Highlighting
22 |rails-options| Managed Vim Options
23 |rails-configuration| Configuration
24 |rails-global-settings| Global Settings
25 |rails-about| About rails.vim
26 |rails-license| License
27
28 This plugin is only available if 'compatible' is not set.
29
30 {Vi does not have any of this}
31
32 INTRODUCTION *rails-introduction* *rails*
33
34 Whenever you edit a file in a Rails application, this plugin will be
35 automatically activated. This sets various options and defines a few
36 buffer-specific commands.
37
38 If you are in a hurry to get started, with a minimal amount of reading, you
39 are encouraged to at least skim through the headings and command names in this
40 file, to get a better idea of what is offered. If you only read one thing,
41 make sure it is the navigation section: |rails-navigation|.
42
43 GENERAL COMMANDS *rails-commands*
44
45 All commands are buffer local, unless otherwise stated. This means you must
46 actually edit a file from a Rails application.
47
48 *rails-:Rails*
49 :Rails new {directory} The only global command. Creates a new Rails
50 application in {directory}, and loads the README.
51
52 :Rails! Show the version of rails.vim installed. If rails.vim
53 is active for the current buffer, also show the type
54 of Rails file detected.
55
56 *rails-:Rcd*
57 :Rcd [{directory}] |:cd| to /path/to/railsapp/{directory}.
58
59 *rails-:Rlcd*
60 :Rlcd [{directory}] |:lcd| to /path/to/railsapp/{directory}.
61
62 *rails-:Rdoc*
63 :Rdoc Browse to the Rails API, either in doc/api in the
64 current Rails application, gem_server if it is
65 running, or http://api.rubyonrails.org/ . Requires
66 :OpenURL to be defined (see |rails-:OpenURL|).
67
68 *rails-:Rdoc!*
69 :Rdoc! Make the appropriate |:helptags| call and invoke
70 |:help| rails.
71
72 *rails-:Redit*
73 :Redit {file} Deprecated in favor of |:R|.
74
75 *rails-:Rfind*
76 :Rfind [{file}] Deprecated in favor of |:R| or |:find|.
77
78 *rails-:Rlog*
79 :Rlog [{logfile}] Split window and open {logfile} ($RAILS_ENV or
80 development by default). The control characters used
81 for highlighting are removed. If you have a :Tail
82 command (provided by |tailminusf|.vim), that is used;
83 otherwise, the file does NOT reload upon change.
84 Use |:checktime| to tell Vim to check for changes.
85 |G| has been mapped to do just that prior to jumping
86 to the end of the file, and q is mapped to close the
87 window. If the delay in loading is too long, you
88 might like :Rake log:clear.
89
90 *rails-:Rpreview*
91 :Rpreview [{path}] Creates a URL from http://localhost:3000/ and the
92 {path} given. The not too useful default is to then
93 edit this URL using Vim itself, allowing |netrw| to
94 download it. More useful is to define a :OpenURL
95 command, which will be used instead (see
96 |rails-:OpenURL|). If {path} is omitted, a sensible
97 default is used (considers the current
98 controller/template, but does not take routing into
99 account). The default is overridden by comments like
100 the following that are either before the current
101 method call or at the top of the file: >
102 # GET /users
103 # PUT /users/1
104 <
105 *rails-:Rpreview!*
106 :Rpreview! [{path}] As with :Rpreview, except :OpenURL is never used.
107
108 *rails-:Rtags*
109 :Rtags Calls ctags -R on the current application root and
110 writes the result to tmp/tags. Exuberant ctags must
111 be installed. Additional arguments can be passed to
112 ctags with |g:rails_ctags_arguments|.
113
114 *rails-:Rrefresh*
115 :Rrefresh Refreshes certain cached settings. Most noticeably,
116 this clears the cached list of classes that are syntax
117 highlighted as railsUserClass.
118
119 *rails-:Rrefresh!*
120 :Rrefresh! As above, and also reloads rails.vim.
121
122 *rails-:OpenURL*
123 :OpenURL {url} This is not a command provided by the plugin, but
124 rather provided by user and utilized by other plugin
125 features. This command should be defined to open the
126 provided {url} in a web browser. An example command
127 on a Mac might be: >
128 :command -bar -nargs=1 OpenURL :!open <args>
129 < The following appears to work on Windows: >
130 :command -bar -nargs=1 OpenURL :!start cmd /cstart /b <args>
131 < On Debian compatible distributions, the following is
132 the preferred method: >
133 :command -bar -nargs=1 OpenURL :!sensible-browser <args>
134 < If exists("$SECURITYSESSIONID"), has("gui_win32"), or
135 executable("sensible-browser") is true, the
136 corresponding command above will be automatically
137 defined. Otherwise, you must provide your own (which
138 is recommended, regardless).
139
140 NAVIGATION *rails-navigation*
141
142 Navigation is where the real power of this plugin lies. Efficient use of the
143 following features will greatly ease navigating the Rails file structure.
144
145 The 'path' has been modified to include all the best places to be.
146 >
147 :find application_controller.rb
148 <
149 File Under Cursor - gf ~
150 *rails-gf*
151 The |gf| command, which normally edits the current file under the cursor, has
152 been remapped to take context into account. |CTRL-W_f| (open in new window)
153 and |CTRL-W_gf| (open in new tab) are also remapped.
154
155 Example uses of |gf|, and where they might lead.
156 (* indicates cursor position)
157 >
158 Pos*t.first
159 < app/models/post.rb ~
160 >
161 has_many :c*omments
162 < app/models/comment.rb ~
163 >
164 link_to 'Home', :controller => 'bl*og'
165 < app/controllers/blog_controller.rb ~
166 >
167 <%= render 'sh*ared/sidebar' %>
168 < app/views/shared/_sidebar.html.erb ~
169 >
170 <%= stylesheet_link_tag 'scaf*fold' %>
171 < public/stylesheets/scaffold.css ~
172 >
173 class BlogController < Applica*tionController
174 < app/controllers/application_controller.rb ~
175 >
176 class ApplicationController < ActionCont*roller::Base
177 < .../action_controller/base.rb ~
178 >
179 fixtures :pos*ts
180 < test/fixtures/posts.yml ~
181 >
182 layout :pri*nt
183 < app/views/layouts/print.html.erb ~
184 >
185 <%= link_to "New", new_comme*nt_path %>
186 < app/controllers/comments_controller.rb (jumps to def new) ~
187
188 In the last example, the controller and action for the named route are
189 determined by evaluating routes.rb as Ruby and doing some introspection. This
190 means code from the application is executed. Keep this in mind when
191 navigating unfamiliar applications.
192
193 Alternate and Related Files ~
194 *rails-alternate-related*
195 Two commands, :A and :R, are used quickly jump to an "alternate" and a
196 "related" file, defined below.
197
198 *rails-:A* *rails-:AE* *rails-:AS* *rails-:AV* *rails-:AT* *rails-:AD*
199 :A These commands were picked to mimic Michael Sharpe's
200 :AE a.vim. Briefly, they edit the "alternate" file, in
201 :AS either the same window (:A and :AE), a new split
202 :AV window (:AS), a new vertically split window (:AV), a
203 :AT new tab (:AT), or read it into the current buffer
204 :AD (:AD).
205
206 *rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT* *rails-:RD*
207 :R These are similar |rails-:A| and friends above, only
208 :RE they jump to the "related" file rather than the
209 :RS "alternate." With a file name argument, they edit
210 :RV a file relative to the application root (:R Rakefile),
211 :RT and with a count and a file name argument, they find a
212 :RD file in 'path' (e.g., :1R PostsController.) You can
213 also append a line number (post.rb:42) or a method
214 (PostsController#32) to both forms.
215
216 *rails-alternate* *rails-related*
217 The alternate file is most frequently the test file, though there are
218 exceptions. The related file varies, and is sometimes dependent on current
219 location in the file. For example, when editing a controller, the related
220 file is template for the method currently being edited.
221
222 The easiest way to learn these commands is to experiment. A few examples of
223 alternate and related files for a Test::Unit application follow:
224
225 Current file Alternate file Related file ~
226 model unit test schema definition
227 controller (in method) functional test template (view)
228 template (view) functional test controller (jump to method)
229 migration previous migration next migration
230 config/database.yml config/routes.rb config/environments/*.rb
231
232 Suggestions for further contexts to consider for the alternate file, related
233 file, and file under the cursor are welcome. They are subtly tweaked from
234 release to release.
235
236 File Type Navigation Commands ~
237 *rails-type-navigation*
238 For the less common cases, a more deliberate set of commands are provided.
239 Each of the upcoming commands takes an optional argument (with tab completion)
240 but defaults to a reasonable guess. Commands that default to the current
241 model or controller generally behave like you'd expect in other file types.
242 For example, in app/helpers/posts_helper.rb, the current controller is
243 "posts", and in test/fixtures/comments.yml, the current model is "comment".
244 In model related files, the current controller is the pluralized model name,
245 and in controller related files, the current model is the singularized
246 controller name.
247
248 Each of the following commands has variants for splitting, vertical splitting,
249 opening in a new tab, and reading the file into the current buffer. For
250 :Rmodel, those variants would be :RSmodel, :RVmodel, :RTmodel, and :RDmodel.
251 There is also :REmodel which is a synonym for :Rmodel (future versions might
252 allow customization of the behavior of :Rmodel). They also allow for jumping
253 to methods or line numbers using the same syntax as |:R|, and file creation
254 can be forced by adding a ! after the filename (not after the command
255 itself!).
256
257 :Rcontroller |rails-:Rcontroller|
258 :Renvironment |rails-:Renvironment|
259 :Rfixtures |rails-:Rfixtures|
260 :Rfunctionaltest |rails-:Rfunctionaltest|
261 :Rhelper |rails-:Rhelper|
262 :Rinitializer |rails-:Rinitializer|
263 :Rintegrationtest |rails-:Rintegrationtest|
264 :Rjavascript |rails-:Rjavascript|
265 :Rlayout |rails-:Rlayout|
266 :Rlib |rails-:Rlib|
267 :Rlocale |rails-:Rlocale|
268 :Rmailer |rails-:Rmailer|
269 :Rmetal |rails-:Rmetal|
270 :Rmigration |rails-:Rmigration|
271 :Rmodel |rails-:Rmodel|
272 :Robserver |rails-:Robserver|
273 :Rplugin |rails-:Rplugin|
274 :Rspec |rails-:Rspec|
275 :Rstylesheet |rails-:Rstylesheet|
276 :Rtask |rails-:Rtask|
277 :Runittest |rails-:Runittest|
278 :Rview |rails-:Rview|
279
280 *rails-:Rcontroller*
281 :Rcontroller [{name}] Edit the specified or current controller.
282
283 *rails-:Renvironment*
284 :Renvironment [{name}] Edit the config/environments file specified. With no
285 argument, defaults to editing config/application.rb
286 or config/environment.rb.
287
288 *rails-:Rfixtures*
289 :Rfixtures [{name}] Edit the fixtures for the given or current model. If
290 an argument is given, it must be pluralized, like the
291 final filename (this may change in the future). If
292 omitted, the current model is pluralized. An optional
293 extension can be given, to distinguish between YAML
294 and CSV fixtures.
295
296 *rails-:Rfunctionaltest*
297 :Rfunctionaltest [{name}]
298 Edit the functional test or controller spec for the
299 specified or current controller.
300
301 *rails-:Rhelper*
302 :Rhelper [{name}] Edit the helper for the specified name or current
303 controller.
304
305 *rails-:Rinitializer*
306 :Rinitializer [{name}] Edit the config/initializers file specified. With no
307 argument, defaults to editing config/routes.rb.
308
309 *rails-:Rintegrationtest*
310 :Rintegrationtest [{name}]
311 Edit the integration test, integration spec, or
312 cucumber feature specified. With no argument,
313 defaults to editing test/test_helper.rb.
314
315 *rails-:Rjavascript*
316 :Rjavascript [{name}] Edit the JavaScript for the specified name or current
317 controller. Also supports CoffeeScript in
318 app/scripts/.
319
320 *rails-:Rlayout*
321 :Rlayout [{name}] Edit the specified layout. Defaults to the layout for
322 the current controller, or the application layout if
323 that cannot be found. A new layout will be created if
324 an extension is given.
325
326 *rails-:Rlib*
327 :Rlib [{name}] Edit the library from the lib directory for the
328 specified name. If the current file is part of a
329 plugin, the libraries from that plugin can be
330 specified as well. With no argument, defaults to
331 editing db/seeds.rb.
332
333 *rails-:Rlocale*
334 :Rlocale [{name}] Edit the config/locale file specified, optionally
335 adding a yml or rb extension if none is given. With
336 no argument, checks config/environment.rb for the
337 default locale.
338
339 *rails-:Rmailer*
340 :Rmailer [{name}] Edit the mailer specified. This looks in both
341 app/mailers for Rails 3 and app/models for older
342 versions of Rails but only tab completes the former.
343
344 *rails-:Rmetal*
345 :Rmetal [{name}] Edit the app/metal file specified. With no argument,
346 defaults to editing config/boot.rb.
347
348 *rails-:Rmigration*
349 :Rmigration [{pattern}] If {pattern} is a number, find the migration for that
350 particular set of digits, zero-padding if necessary.
351 Otherwise, find the newest migration containing the
352 given pattern. Omitting the pattern selects the
353 latest migration. Give a numeric argument of 0 to edit
354 db/schema.rb.
355
356 *rails-:Rmodel*
357 :Rmodel [{name}] Edit the specified or current model.
358
359 *rails-:Robserver*
360 :Robserver [{name}] Find the observer with a name like
361 {model}_observer.rb. When in an observer, most
362 commands (like :Rmodel) will seek based on the
363 observed model ({model}) and not the actual observer
364 ({model}_observer). However, for the command
365 :Runittest, a file of the form
366 {model}_observer_test.rb will be found.
367
368 *rails-:Rplugin*
369 :Rplugin [{plugin}[/{path}]]
370 Edits a file within a plugin. If the path to the file
371 is omitted, it defaults to init.rb. If no argument is
372 given, it defaults to editing the application Gemfile.
373
374 *rails-:Rspec*
375 :Rspec [{name}] Edit the given spec. With no argument, defaults to
376 editing spec/spec_helper.rb (If you want to jump to
377 the spec for the given file, use |:A| instead). This
378 command is only defined if there is a spec folder in
379 the root of the application.
380
381 *rails-:Rstylesheet*
382 :Rstylesheet [{name}] Edit the stylesheet for the specified name or current
383 controller. Also supports Sass and SCSS.
384
385 *rails-:Rtask*
386 :Rtask [{name}] Edit the .rake file from lib/tasks for the specified
387 name. If the current file is part of a plugin, the
388 tasks for that plugin can be specified as well. If no
389 argument is given, either the current plugin's
390 Rakefile or the application Rakefile will be edited.
391
392 *rails-:Runittest*
393 :Runittest [{name}] Edit the unit test or model spec for the specified
394 name or current model.
395
396 *rails-:Rview*
397 :Rview [[{controller}/]{view}]
398 Edit the specified view. The controller will default
399 sensibly, and the view name can be omitted when
400 editing a method of a controller. If a view name is
401 given with an extension, a new file will be created.
402 This is a quick way to create a new view.
403
404 Custom Navigation Commands ~
405 *rails-custom-navigation*
406
407 It is also possible to create custom navigation commands. This is best done
408 in an initialization routine of some sort (e.g., an autocommand); see
409 |rails-configuration| for details.
410
411 *rails-:Rnavcommand*
412 :Rnavcommand [options] {name} [{path} ...]
413 Create a navigation command with the supplied
414 name, looking in the supplied paths, using the
415 supplied options. The -suffix option specifies what
416 suffix to filter on, and strip from the filename, and
417 defaults to -suffix=.rb . The -glob option specifies
418 a file glob to use to find files, _excluding_ the
419 suffix. Useful values include -glob=* and -glob=**/*.
420 The -default option specifies a default argument (not
421 a full path). If it is specified as -default=model(),
422 -default=controller(), or -default=both(), the current
423 model, controller, or both (as with :Rintegrationtest)
424 is used as a default.
425
426 *rails-:Rcommand*
427 :Rcommand Obsolete alias for |:Rnavcommand|.
428
429 Examples: >
430 Rnavcommand api app/apis -glob=**/* -suffix=_api.rb
431 Rnavcommand config config -glob=*.* -suffix= -default=routes.rb
432 Rnavcommand concern app/concerns -glob=**/*
433 Rnavcommand exemplar test/exemplars spec/exemplars -glob=**/*
434 \ -default=model() -suffix=_exemplar.rb
435
436 Finally, one Vim feature that proves helpful in conjunction with all of the
437 above is |CTRL-^|. This keystroke edits the previous file, and is helpful to
438 back out of any of the above commands.
439
440 RAKE *rails-rake*
441
442 Rake integration happens through the :Rake command.
443
444 *rails-:Rake*
445 :[range]Rake {targets} Calls |:make!| {targets} (with 'makeprg' being rake,
446 or `bundle exec rake` if bundler.vim is active) and
447 opens the quickfix window if there were any errors.
448 An argument of "-" reruns the last task. If {targets}
449 are omitted, :Rake defaults to something sensible as
450 described below. Giving a line number argument may
451 affect that default.
452
453 *rails-:Rake!*
454 :[range]Rake! {targets} Called with a bang, :Rake will forgo opening the
455 quickfix window.
456
457 *rails-rake-defaults*
458
459 Generally, the default task is one that runs the test you'd expect. For
460 example, if you're in a view in an RSpec application, the view spec is run,
461 but if it's a Test::Unit application, the functional test for the
462 corresponding controller is run. The following table lists the most
463 interesting mappings:
464
465 File Task ~
466 unit test test:units TEST=...
467 functional test test:functionals TEST=...
468 integration test test:integration TEST=...
469 spec spec SPEC=...
470 feature cucumber FEATURE=...
471 model test:units TEST=... spec SPEC=...
472 controller test:functionals TEST=... spec SPEC=...
473 helper test:functionals TEST=... spec SPEC=...
474 view test:functionals TEST=... spec SPEC=...
475 fixtures db:fixtures:load FIXTURES=...
476 migration db:migrate VERSION=...
477 config/routes.rb routes
478 db/seeds.rb db:seed
479
480 Additionally, when :Rake is given a line number (e.g., :.Rake), the following
481 additional tasks can be invoked:
482
483 File Task ~
484 unit test test:units TEST=... TESTOPTS=-n...
485 functional test test:functionals TEST=... TESTOPTS=-n...
486 integration test test:integration TEST=... TESTOPTS=-n...
487 spec spec SPEC=...:...
488 feature cucumber FEATURE=...:...
489 controller routes CONTROLLER=...
490 fixtures db:fixtures:identify LABEL=...
491 migration in self.up db:migrate:up VERSION=...
492 migration in self.down db:migrate:down VERSION=...
493 migration elsewhere db:migrate:redo VERSION=...
494 task ... (try to guess currently edited declaration)
495
496 Finally, you can override the default task with a comment like "# rake ..."
497 before the method pointed to by [range] or at the top of the file.
498
499 SCRIPT WRAPPERS *rails-scripts*
500
501 The following commands are wrappers around the scripts in the script directory
502 of the Rails application. Most have extra features beyond calling the script.
503 A limited amount of completion with <Tab> is supported.
504
505 *rails-:Rscript*
506 :Rscript {script} {options}
507 Call ruby script/{script} {options}. Defaults to
508 calling script/console.
509
510 *rails-:Rconsole*
511 :Rconsole {options} Obsolete. Call |:Rscript| instead.
512
513 *rails-:Rrunner*
514 :[range]Rrunner {code} Executes {code} with script/runner. Differs from
515 :Rscript runner {code} in that the code is passed as
516 one argument. Also, |system()| is used instead of
517 |:!|. This is to help eliminate annoying "Press
518 ENTER" prompts. If a line number is given in the
519 range slot, the output is pasted into the buffer after
520 that line.
521
522 *rails-:Rp*
523 :[range]Rp {code} Like :Rrunner, but call the Ruby p method on the
524 result. Literally "p begin {code} end".
525
526 *rails-:Rpp* *rails-:Ry*
527 :[range]Rpp {code} Like :Rp, but with pp (pretty print) or y (YAML
528 :[range]Ry {code} output).
529
530 *rails-:Rgenerate*
531 :Rgenerate {options} Calls script/generate {options}, and then edits the
532 first file generated.
533
534 *rails-:Rdestroy*
535 :Rdestroy {options} Calls script/destroy {options}.
536
537 *rails-:Rserver*
538 :Rserver {options} Launches script/server {options} in the background.
539 On win32, this means |!start|. On other systems, this
540 uses the --daemon option.
541
542 *rails-:Rserver!*
543 :Rserver! {options} Same as |:Rserver|, only first attempts to kill any
544 other server using the same port. On non-Windows
545 systems, lsof must be installed for this to work.
546
547 REFACTORING HELPERS *rails-refactoring*
548
549 A few features are dedicated to helping you refactor your code.
550
551 Partial Extraction ~
552 *rails-partials*
553
554 The :Rextract command can be used to extract a partial to a new file.
555
556 *rails-:Rextract*
557 :[range]Rextract [{controller}/]{name}
558 Create a {name} partial from [range] lines (default:
559 current line).
560
561 *rails-:Rpartial*
562 :[range]Rpartial [{controller}/]{name}
563 Obsolete alias for :Rextract.
564
565 If this is your file, in app/views/blog/show.html.erb: >
566
567 1 <div>
568 2 <h2><%= @post.title %></h2>
569 3 <p><%= @post.body %></p>
570 4 </div>
571
572 And you issue this command: >
573
574 :2,3Rextract post
575
576 Your file will change to this: >
577
578 1 <div>
579 2 <%= render :partial => 'post' %>
580 3 </div>
581
582 And app/views/blog/_post.html.erb will now contain: >
583
584 1 <h2><%= post.title %></h2>
585 2 <p><%= post.body %></p>
586
587 As a special case, if the file had looked like this: >
588
589 1 <% for object in @posts -%>
590 2 <h2><%= object.title %></h2>
591 3 <p><%= object.body %></p>
592 4 <% end -%>
593 <
594 The end result would have been this: >
595
596 1 <%= render :partial => 'post', :collection => @posts %>
597 <
598 The easiest way to choose what to extract is to use |linewise-visual| mode.
599 Then, a simple >
600 :'<,'>Rextract blog/post
601 will suffice. (Note the use of a controller name in this example.)
602
603 Migration Inversion ~
604 *rails-migrations* *rails-:Rinvert*
605 :Rinvert In a migration, rewrite the self.up method into a
606 self.down method. If self.up is empty, the process is
607 reversed. This chokes on more complicated
608 instructions, but works reasonably well for simple
609 calls to create_table, add_column, and the like.
610
611 INTEGRATION *rails-integration*
612
613 Having one foot in Rails and one in Vim, rails.vim has two worlds with which
614 to interact.
615
616 Integration with the Vim Universe ~
617 *rails-vim-integration*
618
619 A handful of Vim plugins are enhanced by rails.vim. All plugins mentioned can
620 be found at http://www.vim.org/. Cream and GUI menus (for lack of a better
621 place) are also covered in this section.
622
623 *rails-:Rtree*
624 :Rtree [{arg}] If |NERDTree| is installed, open a tree for the
625 application root or the given subdirectory.
626
627 *rails-:Rdbext* *rails-dbext*
628 :Rdbext [{environment}] This command is only provided when the |dbext| plugin
629 is installed. Loads the {environment} configuration
630 (defaults to $RAILS_ENV or development) from
631 config/database.yml and uses it to configure dbext.
632 The configuration is cached on a per application
633 basis. With dbext version 8.00 and newer, this
634 command is called automatically when needed. When
635 dbext is configured, you can execute SQL directly from
636 Vim: >
637 :Select * from posts order by id desc
638 :Update comments set author_id = 1
639 <
640 *rails-surround*
641 The |surround| plugin available from vim.org enables adding and removing
642 "surroundings" like parentheses, quotes, and HTML tags. Even by itself, it is
643 quite useful for Rails development, particularly eRuby editing. When coupled
644 with this plugin, a few additional replacement surroundings are available in
645 eRuby files. See the |surround| documentation for details on how to use them.
646 The table below uses ^ to represent the position of the surrounded text.
647
648 Key Surrounding ~
649 = <%= ^ %>
650 - <% ^ -%>
651 # <%# ^ %>
652 <C-E> <% ^ -%>\n<% end -%>
653
654 The last surrounding is particularly useful in insert mode with the following
655 map in one's vimrc. Use Alt+o to open a new line below the current one. This
656 works nicely even in a terminal (where most alt/meta maps will fail) because
657 most terminals send <M-o> as <Esc>o anyways.
658 >
659 imap <M-o> <Esc>o
660 <
661 One can also use the <C-E> surrounding in a plain Ruby file to append a bare
662 "end" on the following line.
663
664 *rails-abolish*
665 Among the many features of |abolish| on vim.org is the ability to change the
666 inflection of the word under the cursor. For example, one can hit crs to
667 change from MixedCase to snake_case. This plugin adds two additional
668 inflections: crl for alternating between the singular and plural, and crt for
669 altering between tableize and classify. The latter is useful in changing
670 constructs like BlogPost.all to current_user.blog_posts.all and vice versa.
671
672 *rails-cream*
673 This plugin provides a few additional key bindings if it is running under
674 Cream, the user friendly editor which uses Vim as a back-end. Ctrl+Enter
675 finds the file under the cursor (as in |rails-gf|), and Alt+[ and Alt+] find
676 the alternate (|rails-alternate|) and related (|rails-related|) files.
677
678 *rails-menu*
679 If the GUI is running, a menu for several commonly used features is provided.
680 Also on this menu is a list of recently accessed projects. This list of
681 projects can persist across restarts if a 'viminfo' flag is set to enable
682 retaining certain global variables. If this interests you, add something like
683 the following to your vimrc: >
684 set viminfo^=!
685 <
686 Integration with the Rails Universe ~
687 *rails-rails-integration*
688 The general policy of rails.vim is to focus exclusively on the Ruby on Rails
689 core. Supporting plugins and other add-ons to Rails has the potential to
690 rapidly get out of hand. However, a few pragmatic exceptions have been made.
691
692 *rails-template-types*
693 Commands like :Rview use a hardwired list of extensions (erb, rjs, etc.)
694 when searching for files. In order to facilitate working with non-standard
695 template types, several popular extensions are featured in this list,
696 including haml, liquid, and mab (markaby). These extensions will disappear
697 once a related configuration option is added to rails.vim.
698
699 *rails-rspec*
700 The presence of a spec directory causes several additional behaviors to
701 activate. :A knows about specs and will jump to them (but Test::Unit files
702 still get priority). The associated controller or model of a spec is
703 detected, so all navigation commands should work as expected inside a spec
704 file. :Rake in a spec runs just that spec, and in a model, controller, or
705 helper, runs the associated spec.
706
707 |:Runittest| and |:Rfunctionaltest| lead double lives, handling model and
708 controller specs respectively. For helper and view specs, you can use
709 |:Rspec| or define your own navigation commands:
710 >
711 Rnavcommand spechelper spec/helpers -glob=**/*
712 \ -suffix=_helper_spec.rb -default=controller()
713 Rnavcommand specview spec/views -glob=**/* -suffix=_spec.rb
714 <
715 ABBREVIATIONS *rails-abbreviations* *rails-snippets*
716
717 Abbreviations are "snippets lite". They may later be extracted into a
718 separate plugin, or removed entirely.
719
720 *rails-:Rabbrev*
721 :Rabbrev List all Rails abbreviations.
722
723 :Rabbrev {abbr} {expn} [{extra}]
724 Define a new Rails abbreviation. {extra} is permitted
725 if and only if {expn} ends with "(".
726
727 *rails-:Rabbrev!*
728 :Rabbrev! {abbr} Remove an abbreviation.
729
730 Rails abbreviations differ from regular abbreviations in that they only expand
731 after a <C-]> (see |i_CTRL-]|) or a <Tab> (if <Tab> does not work, it is
732 likely mapped by another plugin). If the abbreviation ends in certain
733 punctuation marks, additional expansions are possible. A few examples will
734 hopefully clear this up (all of the following are enabled by default in
735 appropriate file types).
736
737 Command Sequence typed Resulting text ~
738 Rabbrev rp( render :partial\ => rp( render(:partial =>
739 Rabbrev rp( render :partial\ => rp<Tab> render :partial =>
740 Rabbrev vs( validates_size_of vs( validates_size_of(
741 Rabbrev pa[ params pa[:id] params[:id]
742 Rabbrev pa[ params pa<C-]> params
743 Rabbrev pa[ params pa.inspect params.inspect
744 Rabbrev AR:: ActionRecord AR::Base ActiveRecord::Base
745 Rabbrev :a :action\ =>\ render :a<Tab> render :action =>
746
747 In short, ( expands on (, :: expands on . and :, and [ expands on . and [.
748 These trailing punctuation marks are NOT part of the final abbreviation, and
749 you cannot have two mappings that differ only by punctuation.
750
751 You must escape spaces in your expansion, either as "\ " or as "<Space>". For
752 an abbreviation ending with "(", you may define where to insert the
753 parenthesis by splitting the expansion into two parts (divided by an unescaped
754 space).
755
756 Many abbreviations are provided by default: use :Rabbrev to list them. They
757 vary depending on the type of file (models have different abbreviations than
758 controllers). There is one "smart" abbreviation, :c, which expands to
759 ":controller => ", ":collection => ", or ":conditions => " depending on
760 context.
761
762 SYNTAX HIGHLIGHTING *rails-syntax*
763
764 Syntax highlighting is by and large a transparent process. For the full
765 effect, however, you need a colorscheme which accentuates rails.vim
766 extensions. One such colorscheme is vividchalk, available from vim.org.
767
768 The following is a summary of the changes made by rails.vim to the standard
769 syntax highlighting.
770
771 *rails-syntax-keywords*
772 Rails specific keywords are highlighted in a filetype specific manner. For
773 example, in a model, has_many is highlighted, whereas in a controller,
774 before_filter is highlighted. A wide variety of syntax groups are used but
775 they all link by default to railsMethod.
776
777 If you feel a method has been wrongfully omitted, submit it to the
778 |rails-plugin-author|.
779
780 *rails-syntax-classes*
781 Models, helpers, and controllers are given special highlighting. Depending on
782 the version of Vim installed, you may need a rails.vim aware colorscheme in
783 order to see this. Said colorscheme needs to provide highlighting for the
784 railsUserClass syntax group.
785
786 The class names are determined by camelizing filenames from certain
787 directories of your application. If app/models/line_item.rb exists, the class
788 "LineItem" will be highlighted.
789
790 The list of classes is refreshed automatically after certain commands like
791 |:Rgenerate|. Use |:Rrefresh| to trigger the process manually.
792
793 *rails-syntax-assertions*
794 If you define custom assertions in test_helper.rb, these will be highlighted
795 in your tests. These are found by scanning test_helper.rb for lines of the
796 form " def assert_..." and extracting the method name. The railsUserMethod
797 syntax group is used. The list of assertions can be refreshed with
798 |:Rrefresh|.
799
800 *rails-syntax-strings*
801 In the following line of code, the "?" in the conditions clause and the "ASC"
802 in the order clause will be highlighted: >
803 Post.find(:all, :conditions => ["body like ?","%e%"], :order => "title ASC")
804 <
805 A string literal using %Q<> or %<> delimiters will have its contents
806 highlighted as HTML. This is sometimes useful when writing helpers. >
807 link = %<<a href="http://www.vim.org">Vim</a>>
808 <
809 *rails-syntax-yaml*
810 YAML syntax highlighting has been extended to highlight eRuby, which can be
811 used in most Rails YAML files (including database.yml and fixtures).
812
813 MANAGED VIM OPTIONS *rails-options*
814
815 The following options are set local to buffers where the plugin is active.
816
817 *rails-'shiftwidth'* *rails-'sw'*
818 *rails-'softtabstop'* *rails-'sts'*
819 *rails-'expandtab'* *rails-'et'*
820 A value of 2 is used for 'shiftwidth' (and 'softtabstop'), and 'expandtab' is
821 enabled. This is a strong convention in Rails, so the conventional wisdom
822 that this is a user preference has been ignored.
823
824 *rails-'path'* *rails-'pa'*
825 All the relevant directories from your application are added to your 'path'.
826 This makes it easy to access a buried file: >
827 :find blog_controller.rb
828 <
829 *rails-'suffixesadd'* *rails-'sua'*
830 This is filetype dependent, but typically includes .rb, .rake, and several
831 others. This allows shortening the above example: >
832 :find blog_controller
833 <
834 *rails-'includeexpr'* *rails-'inex'*
835 The 'includeexpr' option is set to enable the magic described in |rails-gf|.
836
837 *rails-'filetype'* *rails-'ft'*
838 The 'filetype' is sometimes adjusted for Rails files. Most notably, *.rxml
839 and *.rjs are treated as Ruby files, and files that have been falsely
840 identified as Mason sources are changed back to eRuby files (but only when
841 they are part of a Rails application).
842
843 *rails-'completefunc'* *rails-'cfu'*
844 A 'completefunc' is provided (if not already set). It is very simple, as it
845 uses syntax highlighting to make its guess. See |i_CTRL-X_CTRL-U|.
846
847 CONFIGURATION *rails-configuration*
848
849 Very little configuration is actually required; this plugin automatically
850 detects your Rails application and adjusts Vim sensibly.
851
852 *rails-:autocmd* *rails-autocommands*
853 If you would like to set your own custom Vim settings whenever a Rails file is
854 loaded, you can use an autocommand like the following in your vimrc: >
855 autocmd User Rails silent! Rlcd
856 autocmd User Rails map <buffer> <F9> :Rake<CR>
857 You can also have autocommands that only apply to certain types of files.
858 These are based off the information shown when running the |:Rails!|
859 command, with hyphens changed to periods. A few examples: >
860 autocmd User Rails.controller* iabbr <buffer> wsn wsdl_service_name
861 autocmd User Rails.model.arb* iabbr <buffer> vfo validates_format_of
862 autocmd User Rails.view.erb* imap <buffer> <C-Z> <%= %><C-O>3h
863 End all such Rails autocommands with asterisks, even if you have an exact
864 specification, to allow for more specific subtypes to be added in the future.
865 There is also a filename matching syntax: >
866 autocmd User Rails/config/environment.rb Rabbrev c config
867 autocmd User Rails/**/foo_bar.rb Rabbrev FB:: FooBar
868 Use the filetype based syntax whenever possible, reserving the filename based
869 syntax for more advanced cases.
870
871 *macros/rails.vim*
872 If you have several commands to run on initialization for all file types, they
873 can be placed in a "macros/rails.vim" file in the 'runtimepath' (for example,
874 "~/.vim/macros/rails.vim"). This file is sourced by rails.vim each time a
875 Rails file is loaded.
876
877 *config/rails.vim*
878 If you have settings particular to a specific project, they can be put in a
879 config/rails.vim file in the root directory of the application. The file is
880 sourced in the |sandbox| for security reasons.
881
882 *rails-:Rset*
883 :Rset {option}[={value}]
884 Query or set a local option. This command may be
885 called directly, from an autocommand, or from
886 config/rails.vim.
887
888 Options may be set in one of four scopes, which may be indicated by an
889 optional prefix. These scopes determine how broadly an option will apply.
890 Generally, the default scope is sufficient.
891
892 Scope Description ~
893 a: All files in one Rails application
894 b: Buffer (file) specific
895 g: Global to all applications
896 l: Local to method (same as b: in non-Ruby files)
897
898 Options are shown below with their default scope, which should be omitted.
899 While you may override the scope with a prefix, this is rarely necessary and
900 oftentimes useless. (For example, setting g:task is useless because the
901 default rake task will apply before considering this option.)
902
903 Option Meaning ~
904 b:alternate Custom alternate file for :A, relative to the Rails root
905 b:controller Default controller for certain commands (e.g., :Rhelper)
906 b:model Default model for certain commands (e.g., :Rfixtures)
907 l:related Custom related file for :R, relative to the Rails root
908 a:root_url Root URL for commands like :Rpreview
909
910 Examples: >
911 :Rset root_url=http://localhost:12345
912 :Rset related=app/views/blog/edit.html.erb
913 <
914 *rails-modelines*
915 If |g:rails_modelines| is enabled, these options can also be set from
916 modelines near the beginning or end of the file. These modelines will always
917 set buffer-local options; scope should never be specified. Examples: >
918 # Rset task=db:schema:load
919 <%# Rset alternate=app/views/layouts/application.html.erb %>
920 Modelines can also be local to a method. Example: >
921 def test_comment
922 # rset alternate=app/models/comment.rb
923 These two forms differ only in case.
924
925 Modelines are deprecated.
926
927 GLOBAL SETTINGS *rails-global-settings*
928
929 A few global variables control the behavior of this plugin. In general, they
930 can be enabled by setting them to 1 in your vimrc, and disabled by setting
931 them to 0. >
932 let g:rails_some_option=1
933 let g:rails_some_option=0
934 Most of these seldom need to be used. So seldom, in fact, that you should
935 notify the |rails-plugin-author| if you find any of them useful, as nearly all
936 are being considered for removal.
937
938 *g:loaded_rails* >
939 let g:loaded_rails=1
940 Set this include guard to prevent the plugin from being loaded.
941
942 *g:rails_abbreviations*
943 Enable Rails abbreviations. See |rails-abbreviations|. Enabled by default.
944
945 *g:rails_ctags_arguments* >
946 let g:rails_ctags_arguments='--languages=-javascript'
947 Additional arguments to pass to ctags from |:Rtags|. Defaults to ignoring
948 JavaScript files, since ctags has a tendency to choke on those.
949
950 *g:rails_default_file* >
951 let g:rails_default_file='config/database.yml'
952 File to load when a new Rails application is created. Defaults to the README.
953
954 *rails-screen* *g:rails_gnu_screen* >
955 let g:rails_gnu_screen=1
956 Use GNU Screen or Tmux (if it is running) to launch |:Rscript| console and
957 |:Rserver| in the background. Enabled by default.
958
959 *g:rails_history_size* >
960 let g:rails_history_size=5
961 Number of projects to remember. Set to 0 to disable. See |rails-menu| for
962 information on retaining these projects across a restart.
963
964 *g:rails_mappings* >
965 let g:rails_mappings=1
966 Enables a few mappings (mostly for |rails-navigation|). Enabled by default.
967
968 *g:rails_modelines* >
969 let g:rails_modelines=1
970 Enable modelines like the following: >
971 # Rset task=db:schema:load
972 Modelines set buffer-local options using the :Rset command.
973 Also enables method specific modelines (note the case difference): >
974 def show
975 # rset preview=blog/show/1
976 Modelines are deprecated and disabled by default.
977
978 *g:rails_menu* >
979 let g:rails_menu=1
980 When 2, a Rails menu is created. When 1, this menu is a submenu under the
981 Plugin menu. The default is 0, as the menu is slated for removal from future
982 versions of rails.vim.
983
984 *g:rails_url* >
985 let g:rails_url='http://localhost:3000/'
986 Used for the |:Rpreview| command. Default is as shown above. Overridden by
987 b:rails_url.
988
989 *g:rails_syntax* >
990 let g:rails_syntax=1
991 When enabled, this tweaks the syntax highlighting to be more Rails friendly.
992 Enabled by default. See |rails-syntax|.
993
994 *rails-tabs* *g:rails_tabstop* >
995 let g:rails_tabstop=4
996 This option now requires the plugin railstab.vim from vim.org:
997 http://www.vim.org/scripts/script.php?script_id=2253
998
999 If your goal is simply just override this plugin's settings and use your own
1000 custom 'shiftwidth', adjust things manually in an autocommand: >
1001 autocmd User Rails set sw=4 sts=4 noet
1002 This is highly discouraged: don't fight Rails.
1003
1004 ABOUT *rails-about* *rails-plugin-author*
1005
1006 This plugin was written by Tim Pope. Email all comments, complaints, and compliments to him at vim at tpope. org.
1007
1008 The latest stable version can be found at
1009 http://www.vim.org/scripts/script.php?script_id=1567
1010
1011 Bugs can be reported and the very latest development version can be retrieved
1012 from GitHub:
1013 https://github.com/tpope/vim-rails
1014 git clone git://github.com/tpope/vim-rails.git
1015
1016 *rails-license*
1017 Copyright (c) Tim Pope. Distributed under the same terms as Vim itself.
1018 See |license|.
1019
1020 vim:tw=78:ts=8:ft=help:norl: