]> git.r.bdr.sh - rbdr/dotfiles/blame - vim/doc/rails.txt
Add gitignore
[rbdr/dotfiles] / vim / doc / rails.txt
CommitLineData
0d23b6e5
BB
1*rails.txt* Plugin for working with Ruby on Rails applications
2
3Author: 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
28This plugin is only available if 'compatible' is not set.
29
30{Vi does not have any of this}
31
32INTRODUCTION *rails-introduction* *rails*
33
34Whenever you edit a file in a Rails application, this plugin will be
35automatically activated. This sets various options and defines a few
36buffer-specific commands.
37
38If you are in a hurry to get started, with a minimal amount of reading, you
39are encouraged to at least skim through the headings and command names in this
40file, to get a better idea of what is offered. If you only read one thing,
41make sure it is the navigation section: |rails-navigation|.
42
43GENERAL COMMANDS *rails-commands*
44
45All commands are buffer local, unless otherwise stated. This means you must
46actually 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
140NAVIGATION *rails-navigation*
141
142Navigation is where the real power of this plugin lies. Efficient use of the
143following features will greatly ease navigating the Rails file structure.
144
145The 'path' has been modified to include all the best places to be.
146>
147 :find application_controller.rb
148<
149File Under Cursor - gf ~
150 *rails-gf*
151The |gf| command, which normally edits the current file under the cursor, has
152been remapped to take context into account. |CTRL-W_f| (open in new window)
153and |CTRL-W_gf| (open in new tab) are also remapped.
154
155Example 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
188In the last example, the controller and action for the named route are
189determined by evaluating routes.rb as Ruby and doing some introspection. This
190means code from the application is executed. Keep this in mind when
191navigating unfamiliar applications.
192
193Alternate and Related Files ~
194 *rails-alternate-related*
195Two 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*
217The alternate file is most frequently the test file, though there are
218exceptions. The related file varies, and is sometimes dependent on current
219location in the file. For example, when editing a controller, the related
220file is template for the method currently being edited.
221
222The easiest way to learn these commands is to experiment. A few examples of
223alternate and related files for a Test::Unit application follow:
224
225Current file Alternate file Related file ~
226model unit test schema definition
227controller (in method) functional test template (view)
228template (view) functional test controller (jump to method)
229migration previous migration next migration
230config/database.yml config/routes.rb config/environments/*.rb
231
232Suggestions for further contexts to consider for the alternate file, related
233file, and file under the cursor are welcome. They are subtly tweaked from
234release to release.
235
236File Type Navigation Commands ~
237 *rails-type-navigation*
238For the less common cases, a more deliberate set of commands are provided.
239Each of the upcoming commands takes an optional argument (with tab completion)
240but defaults to a reasonable guess. Commands that default to the current
241model or controller generally behave like you'd expect in other file types.
242For example, in app/helpers/posts_helper.rb, the current controller is
243"posts", and in test/fixtures/comments.yml, the current model is "comment".
244In model related files, the current controller is the pluralized model name,
245and in controller related files, the current model is the singularized
246controller name.
247
248Each of the following commands has variants for splitting, vertical splitting,
249opening in a new tab, and reading the file into the current buffer. For
250:Rmodel, those variants would be :RSmodel, :RVmodel, :RTmodel, and :RDmodel.
251There is also :REmodel which is a synonym for :Rmodel (future versions might
252allow customization of the behavior of :Rmodel). They also allow for jumping
253to methods or line numbers using the same syntax as |:R|, and file creation
254can be forced by adding a ! after the filename (not after the command
255itself!).
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
404Custom Navigation Commands ~
405 *rails-custom-navigation*
406
407It is also possible to create custom navigation commands. This is best done
408in 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
429Examples: >
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
436Finally, one Vim feature that proves helpful in conjunction with all of the
437above is |CTRL-^|. This keystroke edits the previous file, and is helpful to
438back out of any of the above commands.
439
440RAKE *rails-rake*
441
442Rake 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
459Generally, the default task is one that runs the test you'd expect. For
460example, if you're in a view in an RSpec application, the view spec is run,
461but if it's a Test::Unit application, the functional test for the
462corresponding controller is run. The following table lists the most
463interesting mappings:
464
465File Task ~
466unit test test:units TEST=...
467functional test test:functionals TEST=...
468integration test test:integration TEST=...
469spec spec SPEC=...
470feature cucumber FEATURE=...
471model test:units TEST=... spec SPEC=...
472controller test:functionals TEST=... spec SPEC=...
473helper test:functionals TEST=... spec SPEC=...
474view test:functionals TEST=... spec SPEC=...
475fixtures db:fixtures:load FIXTURES=...
476migration db:migrate VERSION=...
477config/routes.rb routes
478db/seeds.rb db:seed
479
480Additionally, when :Rake is given a line number (e.g., :.Rake), the following
481additional tasks can be invoked:
482
483File Task ~
484unit test test:units TEST=... TESTOPTS=-n...
485functional test test:functionals TEST=... TESTOPTS=-n...
486integration test test:integration TEST=... TESTOPTS=-n...
487spec spec SPEC=...:...
488feature cucumber FEATURE=...:...
489controller routes CONTROLLER=...
490fixtures db:fixtures:identify LABEL=...
491migration in self.up db:migrate:up VERSION=...
492migration in self.down db:migrate:down VERSION=...
493migration elsewhere db:migrate:redo VERSION=...
494task ... (try to guess currently edited declaration)
495
496Finally, you can override the default task with a comment like "# rake ..."
497before the method pointed to by [range] or at the top of the file.
498
499SCRIPT WRAPPERS *rails-scripts*
500
501The following commands are wrappers around the scripts in the script directory
502of the Rails application. Most have extra features beyond calling the script.
503A 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
547REFACTORING HELPERS *rails-refactoring*
548
549A few features are dedicated to helping you refactor your code.
550
551Partial Extraction ~
552 *rails-partials*
553
554The :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
565If 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
572And you issue this command: >
573
574 :2,3Rextract post
575
576Your file will change to this: >
577
578 1 <div>
579 2 <%= render :partial => 'post' %>
580 3 </div>
581
582And app/views/blog/_post.html.erb will now contain: >
583
584 1 <h2><%= post.title %></h2>
585 2 <p><%= post.body %></p>
586
587As 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<
594The end result would have been this: >
595
596 1 <%= render :partial => 'post', :collection => @posts %>
597<
598The easiest way to choose what to extract is to use |linewise-visual| mode.
599Then, a simple >
600 :'<,'>Rextract blog/post
601will suffice. (Note the use of a controller name in this example.)
602
603Migration 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
611INTEGRATION *rails-integration*
612
613Having one foot in Rails and one in Vim, rails.vim has two worlds with which
614to interact.
615
616Integration with the Vim Universe ~
617 *rails-vim-integration*
618
619A handful of Vim plugins are enhanced by rails.vim. All plugins mentioned can
620be found at http://www.vim.org/. Cream and GUI menus (for lack of a better
621place) 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*
641The |surround| plugin available from vim.org enables adding and removing
642"surroundings" like parentheses, quotes, and HTML tags. Even by itself, it is
643quite useful for Rails development, particularly eRuby editing. When coupled
644with this plugin, a few additional replacement surroundings are available in
645eRuby files. See the |surround| documentation for details on how to use them.
646The table below uses ^ to represent the position of the surrounded text.
647
648Key Surrounding ~
649= <%= ^ %>
650- <% ^ -%>
651# <%# ^ %>
652<C-E> <% ^ -%>\n<% end -%>
653
654The last surrounding is particularly useful in insert mode with the following
655map in one's vimrc. Use Alt+o to open a new line below the current one. This
656works nicely even in a terminal (where most alt/meta maps will fail) because
657most terminals send <M-o> as <Esc>o anyways.
658>
659 imap <M-o> <Esc>o
660<
661One 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*
665Among the many features of |abolish| on vim.org is the ability to change the
666inflection of the word under the cursor. For example, one can hit crs to
667change from MixedCase to snake_case. This plugin adds two additional
668inflections: crl for alternating between the singular and plural, and crt for
669altering between tableize and classify. The latter is useful in changing
670constructs like BlogPost.all to current_user.blog_posts.all and vice versa.
671
672 *rails-cream*
673This plugin provides a few additional key bindings if it is running under
674Cream, the user friendly editor which uses Vim as a back-end. Ctrl+Enter
675finds the file under the cursor (as in |rails-gf|), and Alt+[ and Alt+] find
676the alternate (|rails-alternate|) and related (|rails-related|) files.
677
678 *rails-menu*
679If the GUI is running, a menu for several commonly used features is provided.
680Also on this menu is a list of recently accessed projects. This list of
681projects can persist across restarts if a 'viminfo' flag is set to enable
682retaining certain global variables. If this interests you, add something like
683the following to your vimrc: >
684 set viminfo^=!
685<
686Integration with the Rails Universe ~
687 *rails-rails-integration*
688The general policy of rails.vim is to focus exclusively on the Ruby on Rails
689core. Supporting plugins and other add-ons to Rails has the potential to
690rapidly get out of hand. However, a few pragmatic exceptions have been made.
691
692 *rails-template-types*
693Commands like :Rview use a hardwired list of extensions (erb, rjs, etc.)
694when searching for files. In order to facilitate working with non-standard
695template types, several popular extensions are featured in this list,
696including haml, liquid, and mab (markaby). These extensions will disappear
697once a related configuration option is added to rails.vim.
698
699 *rails-rspec*
700The presence of a spec directory causes several additional behaviors to
701activate. :A knows about specs and will jump to them (but Test::Unit files
702still get priority). The associated controller or model of a spec is
703detected, so all navigation commands should work as expected inside a spec
704file. :Rake in a spec runs just that spec, and in a model, controller, or
705helper, runs the associated spec.
706
707|:Runittest| and |:Rfunctionaltest| lead double lives, handling model and
708controller 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<
715ABBREVIATIONS *rails-abbreviations* *rails-snippets*
716
717Abbreviations are "snippets lite". They may later be extracted into a
718separate 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
730Rails abbreviations differ from regular abbreviations in that they only expand
731after a <C-]> (see |i_CTRL-]|) or a <Tab> (if <Tab> does not work, it is
732likely mapped by another plugin). If the abbreviation ends in certain
733punctuation marks, additional expansions are possible. A few examples will
734hopefully clear this up (all of the following are enabled by default in
735appropriate file types).
736
737Command Sequence typed Resulting text ~
738Rabbrev rp( render :partial\ => rp( render(:partial =>
739Rabbrev rp( render :partial\ => rp<Tab> render :partial =>
740Rabbrev vs( validates_size_of vs( validates_size_of(
741Rabbrev pa[ params pa[:id] params[:id]
742Rabbrev pa[ params pa<C-]> params
743Rabbrev pa[ params pa.inspect params.inspect
744Rabbrev AR:: ActionRecord AR::Base ActiveRecord::Base
745Rabbrev :a :action\ =>\ render :a<Tab> render :action =>
746
747In short, ( expands on (, :: expands on . and :, and [ expands on . and [.
748These trailing punctuation marks are NOT part of the final abbreviation, and
749you cannot have two mappings that differ only by punctuation.
750
751You must escape spaces in your expansion, either as "\ " or as "<Space>". For
752an abbreviation ending with "(", you may define where to insert the
753parenthesis by splitting the expansion into two parts (divided by an unescaped
754space).
755
756Many abbreviations are provided by default: use :Rabbrev to list them. They
757vary depending on the type of file (models have different abbreviations than
758controllers). There is one "smart" abbreviation, :c, which expands to
759":controller => ", ":collection => ", or ":conditions => " depending on
760context.
761
762SYNTAX HIGHLIGHTING *rails-syntax*
763
764Syntax highlighting is by and large a transparent process. For the full
765effect, however, you need a colorscheme which accentuates rails.vim
766extensions. One such colorscheme is vividchalk, available from vim.org.
767
768The following is a summary of the changes made by rails.vim to the standard
769syntax highlighting.
770
771 *rails-syntax-keywords*
772Rails specific keywords are highlighted in a filetype specific manner. For
773example, in a model, has_many is highlighted, whereas in a controller,
774before_filter is highlighted. A wide variety of syntax groups are used but
775they all link by default to railsMethod.
776
777If you feel a method has been wrongfully omitted, submit it to the
778|rails-plugin-author|.
779
780 *rails-syntax-classes*
781Models, helpers, and controllers are given special highlighting. Depending on
782the version of Vim installed, you may need a rails.vim aware colorscheme in
783order to see this. Said colorscheme needs to provide highlighting for the
784railsUserClass syntax group.
785
786The class names are determined by camelizing filenames from certain
787directories of your application. If app/models/line_item.rb exists, the class
788"LineItem" will be highlighted.
789
790The list of classes is refreshed automatically after certain commands like
791|:Rgenerate|. Use |:Rrefresh| to trigger the process manually.
792
793 *rails-syntax-assertions*
794If you define custom assertions in test_helper.rb, these will be highlighted
795in your tests. These are found by scanning test_helper.rb for lines of the
796form " def assert_..." and extracting the method name. The railsUserMethod
797syntax group is used. The list of assertions can be refreshed with
798|:Rrefresh|.
799
800 *rails-syntax-strings*
801In the following line of code, the "?" in the conditions clause and the "ASC"
802in the order clause will be highlighted: >
803 Post.find(:all, :conditions => ["body like ?","%e%"], :order => "title ASC")
804<
805A string literal using %Q<> or %<> delimiters will have its contents
806highlighted as HTML. This is sometimes useful when writing helpers. >
807 link = %<<a href="http://www.vim.org">Vim</a>>
808<
809 *rails-syntax-yaml*
810YAML syntax highlighting has been extended to highlight eRuby, which can be
811used in most Rails YAML files (including database.yml and fixtures).
812
813MANAGED VIM OPTIONS *rails-options*
814
815The 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'*
820A value of 2 is used for 'shiftwidth' (and 'softtabstop'), and 'expandtab' is
821enabled. This is a strong convention in Rails, so the conventional wisdom
822that this is a user preference has been ignored.
823
824 *rails-'path'* *rails-'pa'*
825All the relevant directories from your application are added to your 'path'.
826This makes it easy to access a buried file: >
827 :find blog_controller.rb
828<
829 *rails-'suffixesadd'* *rails-'sua'*
830This is filetype dependent, but typically includes .rb, .rake, and several
831others. This allows shortening the above example: >
832 :find blog_controller
833<
834 *rails-'includeexpr'* *rails-'inex'*
835The 'includeexpr' option is set to enable the magic described in |rails-gf|.
836
837 *rails-'filetype'* *rails-'ft'*
838The 'filetype' is sometimes adjusted for Rails files. Most notably, *.rxml
839and *.rjs are treated as Ruby files, and files that have been falsely
840identified as Mason sources are changed back to eRuby files (but only when
841they are part of a Rails application).
842
843 *rails-'completefunc'* *rails-'cfu'*
844A 'completefunc' is provided (if not already set). It is very simple, as it
845uses syntax highlighting to make its guess. See |i_CTRL-X_CTRL-U|.
846
847CONFIGURATION *rails-configuration*
848
849Very little configuration is actually required; this plugin automatically
850detects your Rails application and adjusts Vim sensibly.
851
852 *rails-:autocmd* *rails-autocommands*
853If you would like to set your own custom Vim settings whenever a Rails file is
854loaded, 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>
857You can also have autocommands that only apply to certain types of files.
858These are based off the information shown when running the |:Rails!|
859command, 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
863End all such Rails autocommands with asterisks, even if you have an exact
864specification, to allow for more specific subtypes to be added in the future.
865There 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
868Use the filetype based syntax whenever possible, reserving the filename based
869syntax for more advanced cases.
870
871 *macros/rails.vim*
872If you have several commands to run on initialization for all file types, they
873can 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
875Rails file is loaded.
876
877 *config/rails.vim*
878If you have settings particular to a specific project, they can be put in a
879config/rails.vim file in the root directory of the application. The file is
880sourced 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
888Options may be set in one of four scopes, which may be indicated by an
889optional prefix. These scopes determine how broadly an option will apply.
890Generally, the default scope is sufficient.
891
892Scope Description ~
893a: All files in one Rails application
894b: Buffer (file) specific
895g: Global to all applications
896l: Local to method (same as b: in non-Ruby files)
897
898Options are shown below with their default scope, which should be omitted.
899While you may override the scope with a prefix, this is rarely necessary and
900oftentimes useless. (For example, setting g:task is useless because the
901default rake task will apply before considering this option.)
902
903Option Meaning ~
904b:alternate Custom alternate file for :A, relative to the Rails root
905b:controller Default controller for certain commands (e.g., :Rhelper)
906b:model Default model for certain commands (e.g., :Rfixtures)
907l:related Custom related file for :R, relative to the Rails root
908a:root_url Root URL for commands like :Rpreview
909
910Examples: >
911 :Rset root_url=http://localhost:12345
912 :Rset related=app/views/blog/edit.html.erb
913<
914 *rails-modelines*
915If |g:rails_modelines| is enabled, these options can also be set from
916modelines near the beginning or end of the file. These modelines will always
917set buffer-local options; scope should never be specified. Examples: >
918 # Rset task=db:schema:load
919 <%# Rset alternate=app/views/layouts/application.html.erb %>
920Modelines can also be local to a method. Example: >
921 def test_comment
922 # rset alternate=app/models/comment.rb
923These two forms differ only in case.
924
925Modelines are deprecated.
926
927GLOBAL SETTINGS *rails-global-settings*
928
929A few global variables control the behavior of this plugin. In general, they
930can be enabled by setting them to 1 in your vimrc, and disabled by setting
931them to 0. >
932 let g:rails_some_option=1
933 let g:rails_some_option=0
934Most of these seldom need to be used. So seldom, in fact, that you should
935notify the |rails-plugin-author| if you find any of them useful, as nearly all
936are being considered for removal.
937
938 *g:loaded_rails* >
939 let g:loaded_rails=1
940Set this include guard to prevent the plugin from being loaded.
941
942 *g:rails_abbreviations*
943Enable Rails abbreviations. See |rails-abbreviations|. Enabled by default.
944
945 *g:rails_ctags_arguments* >
946 let g:rails_ctags_arguments='--languages=-javascript'
947Additional arguments to pass to ctags from |:Rtags|. Defaults to ignoring
948JavaScript 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'
952File 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
956Use 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
961Number of projects to remember. Set to 0 to disable. See |rails-menu| for
962information on retaining these projects across a restart.
963
964 *g:rails_mappings* >
965 let g:rails_mappings=1
966Enables a few mappings (mostly for |rails-navigation|). Enabled by default.
967
968 *g:rails_modelines* >
969 let g:rails_modelines=1
970Enable modelines like the following: >
971 # Rset task=db:schema:load
972Modelines set buffer-local options using the :Rset command.
973Also enables method specific modelines (note the case difference): >
974 def show
975 # rset preview=blog/show/1
976Modelines are deprecated and disabled by default.
977
978 *g:rails_menu* >
979 let g:rails_menu=1
980When 2, a Rails menu is created. When 1, this menu is a submenu under the
981Plugin menu. The default is 0, as the menu is slated for removal from future
982versions of rails.vim.
983
984 *g:rails_url* >
985 let g:rails_url='http://localhost:3000/'
986Used for the |:Rpreview| command. Default is as shown above. Overridden by
987b:rails_url.
988
989 *g:rails_syntax* >
990 let g:rails_syntax=1
991When enabled, this tweaks the syntax highlighting to be more Rails friendly.
992Enabled by default. See |rails-syntax|.
993
994 *rails-tabs* *g:rails_tabstop* >
995 let g:rails_tabstop=4
996This option now requires the plugin railstab.vim from vim.org:
997 http://www.vim.org/scripts/script.php?script_id=2253
998
999If your goal is simply just override this plugin's settings and use your own
1000custom 'shiftwidth', adjust things manually in an autocommand: >
1001 autocmd User Rails set sw=4 sts=4 noet
1002This is highly discouraged: don't fight Rails.
1003
1004ABOUT *rails-about* *rails-plugin-author*
1005
1006This plugin was written by Tim Pope. Email all comments, complaints, and compliments to him at vim at tpope. org.
1007
1008The latest stable version can be found at
1009 http://www.vim.org/scripts/script.php?script_id=1567
1010
1011Bugs can be reported and the very latest development version can be retrieved
1012from GitHub:
1013 https://github.com/tpope/vim-rails
1014 git clone git://github.com/tpope/vim-rails.git
1015
1016 *rails-license*
1017Copyright (c) Tim Pope. Distributed under the same terms as Vim itself.
1018See |license|.
1019
1020 vim:tw=78:ts=8:ft=help:norl: