1 *rails.txt* Plugin for working with Ruby on Rails applications
3 Author: Tim Pope <http://tpo.pe/>
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
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
28 This plugin is only available if 'compatible' is not set.
30 {Vi does not have any of this}
32 INTRODUCTION *rails-introduction* *rails*
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.
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|.
43 GENERAL COMMANDS *rails-commands*
45 All commands are buffer local, unless otherwise stated. This means you must
46 actually edit a file from a Rails application.
49 :Rails new {directory} The only global command. Creates a new Rails
50 application in {directory}, and loads the README.
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.
57 :Rcd [{directory}] |:cd| to /path/to/railsapp/{directory}.
60 :Rlcd [{directory}] |:lcd| to /path/to/railsapp/{directory}.
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|).
69 :Rdoc! Make the appropriate |:helptags| call and invoke
73 :Redit {file} Deprecated in favor of |:R|.
76 :Rfind [{file}] Deprecated in favor of |:R| or |:find|.
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.
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: >
106 :Rpreview! [{path}] As with :Rpreview, except :OpenURL is never used.
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|.
115 :Rrefresh Refreshes certain cached settings. Most noticeably,
116 this clears the cached list of classes that are syntax
117 highlighted as railsUserClass.
120 :Rrefresh! As above, and also reloads rails.vim.
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
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).
140 NAVIGATION *rails-navigation*
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.
145 The 'path' has been modified to include all the best places to be.
147 :find application_controller.rb
149 File Under Cursor - 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.
155 Example uses of |gf|, and where they might lead.
156 (* indicates cursor position)
159 < app/models/post.rb ~
162 < app/models/comment.rb ~
164 link_to 'Home', :controller => 'bl*og'
165 < app/controllers/blog_controller.rb ~
167 <%= render 'sh*ared/sidebar' %>
168 < app/views/shared/_sidebar.html.erb ~
170 <%= stylesheet_link_tag 'scaf*fold' %>
171 < public/stylesheets/scaffold.css ~
173 class BlogController < Applica*tionController
174 < app/controllers/application_controller.rb ~
176 class ApplicationController < ActionCont*roller::Base
177 < .../action_controller/base.rb ~
180 < test/fixtures/posts.yml ~
183 < app/views/layouts/print.html.erb ~
185 <%= link_to "New", new_comme*nt_path %>
186 < app/controllers/comments_controller.rb (jumps to def new) ~
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.
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.
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
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.
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.
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:
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
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
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
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
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|
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|
281 :Rcontroller [{name}] Edit the specified or current controller.
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.
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
296 *rails-:Rfunctionaltest*
297 :Rfunctionaltest [{name}]
298 Edit the functional test or controller spec for the
299 specified or current controller.
302 :Rhelper [{name}] Edit the helper for the specified name or current
305 *rails-:Rinitializer*
306 :Rinitializer [{name}] Edit the config/initializers file specified. With no
307 argument, defaults to editing config/routes.rb.
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.
316 :Rjavascript [{name}] Edit the JavaScript for the specified name or current
317 controller. Also supports CoffeeScript in
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.
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
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
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.
345 :Rmetal [{name}] Edit the app/metal file specified. With no argument,
346 defaults to editing config/boot.rb.
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
357 :Rmodel [{name}] Edit the specified or current model.
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.
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.
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.
382 :Rstylesheet [{name}] Edit the stylesheet for the specified name or current
383 controller. Also supports Sass and SCSS.
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.
393 :Runittest [{name}] Edit the unit test or model spec for the specified
394 name or current model.
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.
404 Custom Navigation Commands ~
405 *rails-custom-navigation*
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.
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.
427 :Rcommand Obsolete alias for |:Rnavcommand|.
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
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.
442 Rake integration happens through the :Rake command.
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
454 :[range]Rake! {targets} Called with a bang, :Rake will forgo opening the
457 *rails-rake-defaults*
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:
466 unit test test:units TEST=...
467 functional test test:functionals TEST=...
468 integration test test:integration TEST=...
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
480 Additionally, when :Rake is given a line number (e.g., :.Rake), the following
481 additional tasks can be invoked:
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)
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.
499 SCRIPT WRAPPERS *rails-scripts*
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.
506 :Rscript {script} {options}
507 Call ruby script/{script} {options}. Defaults to
508 calling script/console.
511 :Rconsole {options} Obsolete. Call |:Rscript| instead.
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
523 :[range]Rp {code} Like :Rrunner, but call the Ruby p method on the
524 result. Literally "p begin {code} end".
526 *rails-:Rpp* *rails-:Ry*
527 :[range]Rpp {code} Like :Rp, but with pp (pretty print) or y (YAML
528 :[range]Ry {code} output).
531 :Rgenerate {options} Calls script/generate {options}, and then edits the
532 first file generated.
535 :Rdestroy {options} Calls script/destroy {options}.
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.
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.
547 REFACTORING HELPERS *rails-refactoring*
549 A few features are dedicated to helping you refactor your code.
554 The :Rextract command can be used to extract a partial to a new file.
557 :[range]Rextract [{controller}/]{name}
558 Create a {name} partial from [range] lines (default:
562 :[range]Rpartial [{controller}/]{name}
563 Obsolete alias for :Rextract.
565 If this is your file, in app/views/blog/show.html.erb: >
568 2 <h2><%= @post.title %></h2>
569 3 <p><%= @post.body %></p>
572 And you issue this command: >
576 Your file will change to this: >
579 2 <%= render :partial => 'post' %>
582 And app/views/blog/_post.html.erb will now contain: >
584 1 <h2><%= post.title %></h2>
585 2 <p><%= post.body %></p>
587 As a special case, if the file had looked like this: >
589 1 <% for object in @posts -%>
590 2 <h2><%= object.title %></h2>
591 3 <p><%= object.body %></p>
594 The end result would have been this: >
596 1 <%= render :partial => 'post', :collection => @posts %>
598 The easiest way to choose what to extract is to use |linewise-visual| mode.
600 :'<,'>Rextract blog/post
601 will suffice. (Note the use of a controller name in this example.)
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.
611 INTEGRATION *rails-integration*
613 Having one foot in Rails and one in Vim, rails.vim has two worlds with which
616 Integration with the Vim Universe ~
617 *rails-vim-integration*
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.
624 :Rtree [{arg}] If |NERDTree| is installed, open a tree for the
625 application root or the given subdirectory.
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
637 :Select * from posts order by id desc
638 :Update comments set author_id = 1
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.
652 <C-E> <% ^ -%>\n<% end -%>
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.
661 One can also use the <C-E> surrounding in a plain Ruby file to append a bare
662 "end" on the following line.
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.
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.
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: >
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.
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.
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.
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:
711 Rnavcommand spechelper spec/helpers -glob=**/*
712 \ -suffix=_helper_spec.rb -default=controller()
713 Rnavcommand specview spec/views -glob=**/* -suffix=_spec.rb
715 ABBREVIATIONS *rails-abbreviations* *rails-snippets*
717 Abbreviations are "snippets lite". They may later be extracted into a
718 separate plugin, or removed entirely.
721 :Rabbrev List all Rails abbreviations.
723 :Rabbrev {abbr} {expn} [{extra}]
724 Define a new Rails abbreviation. {extra} is permitted
725 if and only if {expn} ends with "(".
728 :Rabbrev! {abbr} Remove an abbreviation.
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).
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 =>
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.
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
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
762 SYNTAX HIGHLIGHTING *rails-syntax*
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.
768 The following is a summary of the changes made by rails.vim to the standard
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.
777 If you feel a method has been wrongfully omitted, submit it to the
778 |rails-plugin-author|.
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.
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.
790 The list of classes is refreshed automatically after certain commands like
791 |:Rgenerate|. Use |:Rrefresh| to trigger the process manually.
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
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")
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>>
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).
813 MANAGED VIM OPTIONS *rails-options*
815 The following options are set local to buffers where the plugin is active.
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.
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
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
834 *rails-'includeexpr'* *rails-'inex'*
835 The 'includeexpr' option is set to enable the magic described in |rails-gf|.
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).
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|.
847 CONFIGURATION *rails-configuration*
849 Very little configuration is actually required; this plugin automatically
850 detects your Rails application and adjusts Vim sensibly.
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.
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.
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.
883 :Rset {option}[={value}]
884 Query or set a local option. This command may be
885 called directly, from an autocommand, or from
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.
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)
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.)
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
911 :Rset root_url=http://localhost:12345
912 :Rset related=app/views/blog/edit.html.erb
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: >
922 # rset alternate=app/models/comment.rb
923 These two forms differ only in case.
925 Modelines are deprecated.
927 GLOBAL SETTINGS *rails-global-settings*
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
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.
940 Set this include guard to prevent the plugin from being loaded.
942 *g:rails_abbreviations*
943 Enable Rails abbreviations. See |rails-abbreviations|. Enabled by default.
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.
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.
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.
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.
965 let g:rails_mappings=1
966 Enables a few mappings (mostly for |rails-navigation|). Enabled by default.
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): >
975 # rset preview=blog/show/1
976 Modelines are deprecated and disabled by default.
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.
985 let g:rails_url='http://localhost:3000/'
986 Used for the |:Rpreview| command. Default is as shown above. Overridden by
991 When enabled, this tweaks the syntax highlighting to be more Rails friendly.
992 Enabled by default. See |rails-syntax|.
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
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.
1004 ABOUT *rails-about* *rails-plugin-author*
1006 This plugin was written by Tim Pope. Email all comments, complaints, and compliments to him at vim at tpope. org.
1008 The latest stable version can be found at
1009 http://www.vim.org/scripts/script.php?script_id=1567
1011 Bugs can be reported and the very latest development version can be retrieved
1013 https://github.com/tpope/vim-rails
1014 git clone git://github.com/tpope/vim-rails.git
1017 Copyright (c) Tim Pope. Distributed under the same terms as Vim itself.
1020 vim:tw=78:ts=8:ft=help:norl:
git.r.bdr.sh / rbdr / dotfiles / blob