diff options
| author | Ben Beltran <ben@freshout.us> | 2013-06-05 10:50:57 -0500 |
|---|---|---|
| committer | Ben Beltran <ben@freshout.us> | 2013-06-05 10:50:57 -0500 |
| commit | fe337504f2fb3ded76326b1e3d4d02787a27d853 (patch) | |
| tree | b84891d78de37ae078ea9850a541799b5bca8085 /vim/doc/rails.txt | |
| parent | e23d7a9f7363bdc69e95a1df31e093db15459fcf (diff) | |
Aand that's all the plugins.
Diffstat (limited to 'vim/doc/rails.txt')
| -rw-r--r-- | vim/doc/rails.txt | 1020 |
1 files changed, 0 insertions, 1020 deletions
diff --git a/vim/doc/rails.txt b/vim/doc/rails.txt deleted file mode 100644 index 6dbbb1e..0000000 --- a/vim/doc/rails.txt +++ /dev/null @@ -1,1020 +0,0 @@ -*rails.txt* Plugin for working with Ruby on Rails applications - -Author: Tim Pope <http://tpo.pe/> - -|rails-introduction| Introduction and Feature Summary -|rails-commands| General Commands -|rails-navigation| Navigation -|rails-gf| File Under Cursor - gf -|rails-alternate-related| Alternate and Related Files -|rails-type-navigation| File Type Commands -|rails-custom-navigation| Custom Navigation Commands -|rails-rake| Rake -|rails-scripts| Script Wrappers -|rails-refactoring| Refactoring Helpers -|rails-partials| Partial Extraction -|rails-migrations| Migration Inversion -|rails-integration| Integration -|rails-vim-integration| Integration with the Vim Universe -|rails-rails-integration| Integration with the Rails Universe -|rails-abbreviations| Abbreviations -|rails-syntax| Syntax Highlighting -|rails-options| Managed Vim Options -|rails-configuration| Configuration -|rails-global-settings| Global Settings -|rails-about| About rails.vim -|rails-license| License - -This plugin is only available if 'compatible' is not set. - -{Vi does not have any of this} - -INTRODUCTION *rails-introduction* *rails* - -Whenever you edit a file in a Rails application, this plugin will be -automatically activated. This sets various options and defines a few -buffer-specific commands. - -If you are in a hurry to get started, with a minimal amount of reading, you -are encouraged to at least skim through the headings and command names in this -file, to get a better idea of what is offered. If you only read one thing, -make sure it is the navigation section: |rails-navigation|. - -GENERAL COMMANDS *rails-commands* - -All commands are buffer local, unless otherwise stated. This means you must -actually edit a file from a Rails application. - - *rails-:Rails* -:Rails new {directory} The only global command. Creates a new Rails - application in {directory}, and loads the README. - -:Rails! Show the version of rails.vim installed. If rails.vim - is active for the current buffer, also show the type - of Rails file detected. - - *rails-:Rcd* -:Rcd [{directory}] |:cd| to /path/to/railsapp/{directory}. - - *rails-:Rlcd* -:Rlcd [{directory}] |:lcd| to /path/to/railsapp/{directory}. - - *rails-:Rdoc* -:Rdoc Browse to the Rails API, either in doc/api in the - current Rails application, gem_server if it is - running, or http://api.rubyonrails.org/ . Requires - :OpenURL to be defined (see |rails-:OpenURL|). - - *rails-:Rdoc!* -:Rdoc! Make the appropriate |:helptags| call and invoke - |:help| rails. - - *rails-:Redit* -:Redit {file} Deprecated in favor of |:R|. - - *rails-:Rfind* -:Rfind [{file}] Deprecated in favor of |:R| or |:find|. - - *rails-:Rlog* -:Rlog [{logfile}] Split window and open {logfile} ($RAILS_ENV or - development by default). The control characters used - for highlighting are removed. If you have a :Tail - command (provided by |tailminusf|.vim), that is used; - otherwise, the file does NOT reload upon change. - Use |:checktime| to tell Vim to check for changes. - |G| has been mapped to do just that prior to jumping - to the end of the file, and q is mapped to close the - window. If the delay in loading is too long, you - might like :Rake log:clear. - - *rails-:Rpreview* -:Rpreview [{path}] Creates a URL from http://localhost:3000/ and the - {path} given. The not too useful default is to then - edit this URL using Vim itself, allowing |netrw| to - download it. More useful is to define a :OpenURL - command, which will be used instead (see - |rails-:OpenURL|). If {path} is omitted, a sensible - default is used (considers the current - controller/template, but does not take routing into - account). The default is overridden by comments like - the following that are either before the current - method call or at the top of the file: > - # GET /users - # PUT /users/1 -< - *rails-:Rpreview!* -:Rpreview! [{path}] As with :Rpreview, except :OpenURL is never used. - - *rails-:Rtags* -:Rtags Calls ctags -R on the current application root and - writes the result to tmp/tags. Exuberant ctags must - be installed. Additional arguments can be passed to - ctags with |g:rails_ctags_arguments|. - - *rails-:Rrefresh* -:Rrefresh Refreshes certain cached settings. Most noticeably, - this clears the cached list of classes that are syntax - highlighted as railsUserClass. - - *rails-:Rrefresh!* -:Rrefresh! As above, and also reloads rails.vim. - - *rails-:OpenURL* -:OpenURL {url} This is not a command provided by the plugin, but - rather provided by user and utilized by other plugin - features. This command should be defined to open the - provided {url} in a web browser. An example command - on a Mac might be: > - :command -bar -nargs=1 OpenURL :!open <args> -< The following appears to work on Windows: > - :command -bar -nargs=1 OpenURL :!start cmd /cstart /b <args> -< On Debian compatible distributions, the following is - the preferred method: > - :command -bar -nargs=1 OpenURL :!sensible-browser <args> -< If exists("$SECURITYSESSIONID"), has("gui_win32"), or - executable("sensible-browser") is true, the - corresponding command above will be automatically - defined. Otherwise, you must provide your own (which - is recommended, regardless). - -NAVIGATION *rails-navigation* - -Navigation is where the real power of this plugin lies. Efficient use of the -following features will greatly ease navigating the Rails file structure. - -The 'path' has been modified to include all the best places to be. -> - :find application_controller.rb -< -File Under Cursor - gf ~ - *rails-gf* -The |gf| command, which normally edits the current file under the cursor, has -been remapped to take context into account. |CTRL-W_f| (open in new window) -and |CTRL-W_gf| (open in new tab) are also remapped. - -Example uses of |gf|, and where they might lead. -(* indicates cursor position) -> - Pos*t.first -< app/models/post.rb ~ -> - has_many :c*omments -< app/models/comment.rb ~ -> - link_to 'Home', :controller => 'bl*og' -< app/controllers/blog_controller.rb ~ -> - <%= render 'sh*ared/sidebar' %> -< app/views/shared/_sidebar.html.erb ~ -> - <%= stylesheet_link_tag 'scaf*fold' %> -< public/stylesheets/scaffold.css ~ -> - class BlogController < Applica*tionController -< app/controllers/application_controller.rb ~ -> - class ApplicationController < ActionCont*roller::Base -< .../action_controller/base.rb ~ -> - fixtures :pos*ts -< test/fixtures/posts.yml ~ -> - layout :pri*nt -< app/views/layouts/print.html.erb ~ -> - <%= link_to "New", new_comme*nt_path %> -< app/controllers/comments_controller.rb (jumps to def new) ~ - -In the last example, the controller and action for the named route are -determined by evaluating routes.rb as Ruby and doing some introspection. This -means code from the application is executed. Keep this in mind when -navigating unfamiliar applications. - -Alternate and Related Files ~ - *rails-alternate-related* -Two commands, :A and :R, are used quickly jump to an "alternate" and a -"related" file, defined below. - - *rails-:A* *rails-:AE* *rails-:AS* *rails-:AV* *rails-:AT* *rails-:AD* -:A These commands were picked to mimic Michael Sharpe's -:AE a.vim. Briefly, they edit the "alternate" file, in -:AS either the same window (:A and :AE), a new split -:AV window (:AS), a new vertically split window (:AV), a -:AT new tab (:AT), or read it into the current buffer -:AD (:AD). - - *rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT* *rails-:RD* -:R These are similar |rails-:A| and friends above, only -:RE they jump to the "related" file rather than the -:RS "alternate." With a file name argument, they edit -:RV a file relative to the application root (:R Rakefile), -:RT and with a count and a file name argument, they find a -:RD file in 'path' (e.g., :1R PostsController.) You can - also append a line number (post.rb:42) or a method - (PostsController#32) to both forms. - - *rails-alternate* *rails-related* -The alternate file is most frequently the test file, though there are -exceptions. The related file varies, and is sometimes dependent on current -location in the file. For example, when editing a controller, the related -file is template for the method currently being edited. - -The easiest way to learn these commands is to experiment. A few examples of -alternate and related files for a Test::Unit application follow: - -Current file Alternate file Related file ~ -model unit test schema definition -controller (in method) functional test template (view) -template (view) functional test controller (jump to method) -migration previous migration next migration -config/database.yml config/routes.rb config/environments/*.rb - -Suggestions for further contexts to consider for the alternate file, related -file, and file under the cursor are welcome. They are subtly tweaked from -release to release. - -File Type Navigation Commands ~ - *rails-type-navigation* -For the less common cases, a more deliberate set of commands are provided. -Each of the upcoming commands takes an optional argument (with tab completion) -but defaults to a reasonable guess. Commands that default to the current -model or controller generally behave like you'd expect in other file types. -For example, in app/helpers/posts_helper.rb, the current controller is -"posts", and in test/fixtures/comments.yml, the current model is "comment". -In model related files, the current controller is the pluralized model name, -and in controller related files, the current model is the singularized -controller name. - -Each of the following commands has variants for splitting, vertical splitting, -opening in a new tab, and reading the file into the current buffer. For -:Rmodel, those variants would be :RSmodel, :RVmodel, :RTmodel, and :RDmodel. -There is also :REmodel which is a synonym for :Rmodel (future versions might -allow customization of the behavior of :Rmodel). They also allow for jumping -to methods or line numbers using the same syntax as |:R|, and file creation -can be forced by adding a ! after the filename (not after the command -itself!). - -:Rcontroller |rails-:Rcontroller| -:Renvironment |rails-:Renvironment| -:Rfixtures |rails-:Rfixtures| -:Rfunctionaltest |rails-:Rfunctionaltest| -:Rhelper |rails-:Rhelper| -:Rinitializer |rails-:Rinitializer| -:Rintegrationtest |rails-:Rintegrationtest| -:Rjavascript |rails-:Rjavascript| -:Rlayout |rails-:Rlayout| -:Rlib |rails-:Rlib| -:Rlocale |rails-:Rlocale| -:Rmailer |rails-:Rmailer| -:Rmetal |rails-:Rmetal| -:Rmigration |rails-:Rmigration| -:Rmodel |rails-:Rmodel| -:Robserver |rails-:Robserver| -:Rplugin |rails-:Rplugin| -:Rspec |rails-:Rspec| -:Rstylesheet |rails-:Rstylesheet| -:Rtask |rails-:Rtask| -:Runittest |rails-:Runittest| -:Rview |rails-:Rview| - - *rails-:Rcontroller* -:Rcontroller [{name}] Edit the specified or current controller. - - *rails-:Renvironment* -:Renvironment [{name}] Edit the config/environments file specified. With no - argument, defaults to editing config/application.rb - or config/environment.rb. - - *rails-:Rfixtures* -:Rfixtures [{name}] Edit the fixtures for the given or current model. If - an argument is given, it must be pluralized, like the - final filename (this may change in the future). If - omitted, the current model is pluralized. An optional - extension can be given, to distinguish between YAML - and CSV fixtures. - - *rails-:Rfunctionaltest* -:Rfunctionaltest [{name}] - Edit the functional test or controller spec for the - specified or current controller. - - *rails-:Rhelper* -:Rhelper [{name}] Edit the helper for the specified name or current - controller. - - *rails-:Rinitializer* -:Rinitializer [{name}] Edit the config/initializers file specified. With no - argument, defaults to editing config/routes.rb. - - *rails-:Rintegrationtest* -:Rintegrationtest [{name}] - Edit the integration test, integration spec, or - cucumber feature specified. With no argument, - defaults to editing test/test_helper.rb. - - *rails-:Rjavascript* -:Rjavascript [{name}] Edit the JavaScript for the specified name or current - controller. Also supports CoffeeScript in - app/scripts/. - - *rails-:Rlayout* -:Rlayout [{name}] Edit the specified layout. Defaults to the layout for - the current controller, or the application layout if - that cannot be found. A new layout will be created if - an extension is given. - - *rails-:Rlib* -:Rlib [{name}] Edit the library from the lib directory for the - specified name. If the current file is part of a - plugin, the libraries from that plugin can be - specified as well. With no argument, defaults to - editing db/seeds.rb. - - *rails-:Rlocale* -:Rlocale [{name}] Edit the config/locale file specified, optionally - adding a yml or rb extension if none is given. With - no argument, checks config/environment.rb for the - default locale. - - *rails-:Rmailer* -:Rmailer [{name}] Edit the mailer specified. This looks in both - app/mailers for Rails 3 and app/models for older - versions of Rails but only tab completes the former. - - *rails-:Rmetal* -:Rmetal [{name}] Edit the app/metal file specified. With no argument, - defaults to editing config/boot.rb. - - *rails-:Rmigration* -:Rmigration [{pattern}] If {pattern} is a number, find the migration for that - particular set of digits, zero-padding if necessary. - Otherwise, find the newest migration containing the - given pattern. Omitting the pattern selects the - latest migration. Give a numeric argument of 0 to edit - db/schema.rb. - - *rails-:Rmodel* -:Rmodel [{name}] Edit the specified or current model. - - *rails-:Robserver* -:Robserver [{name}] Find the observer with a name like - {model}_observer.rb. When in an observer, most - commands (like :Rmodel) will seek based on the - observed model ({model}) and not the actual observer - ({model}_observer). However, for the command - :Runittest, a file of the form - {model}_observer_test.rb will be found. - - *rails-:Rplugin* -:Rplugin [{plugin}[/{path}]] - Edits a file within a plugin. If the path to the file - is omitted, it defaults to init.rb. If no argument is - given, it defaults to editing the application Gemfile. - - *rails-:Rspec* -:Rspec [{name}] Edit the given spec. With no argument, defaults to - editing spec/spec_helper.rb (If you want to jump to - the spec for the given file, use |:A| instead). This - command is only defined if there is a spec folder in - the root of the application. - - *rails-:Rstylesheet* -:Rstylesheet [{name}] Edit the stylesheet for the specified name or current - controller. Also supports Sass and SCSS. - - *rails-:Rtask* -:Rtask [{name}] Edit the .rake file from lib/tasks for the specified - name. If the current file is part of a plugin, the - tasks for that plugin can be specified as well. If no - argument is given, either the current plugin's - Rakefile or the application Rakefile will be edited. - - *rails-:Runittest* -:Runittest [{name}] Edit the unit test or model spec for the specified - name or current model. - - *rails-:Rview* -:Rview [[{controller}/]{view}] - Edit the specified view. The controller will default - sensibly, and the view name can be omitted when - editing a method of a controller. If a view name is - given with an extension, a new file will be created. - This is a quick way to create a new view. - -Custom Navigation Commands ~ - *rails-custom-navigation* - -It is also possible to create custom navigation commands. This is best done -in an initialization routine of some sort (e.g., an autocommand); see -|rails-configuration| for details. - - *rails-:Rnavcommand* -:Rnavcommand [options] {name} [{path} ...] - Create a navigation command with the supplied - name, looking in the supplied paths, using the - supplied options. The -suffix option specifies what - suffix to filter on, and strip from the filename, and - defaults to -suffix=.rb . The -glob option specifies - a file glob to use to find files, _excluding_ the - suffix. Useful values include -glob=* and -glob=**/*. - The -default option specifies a default argument (not - a full path). If it is specified as -default=model(), - -default=controller(), or -default=both(), the current - model, controller, or both (as with :Rintegrationtest) - is used as a default. - - *rails-:Rcommand* -:Rcommand Obsolete alias for |:Rnavcommand|. - -Examples: > - Rnavcommand api app/apis -glob=**/* -suffix=_api.rb - Rnavcommand config config -glob=*.* -suffix= -default=routes.rb - Rnavcommand concern app/concerns -glob=**/* - Rnavcommand exemplar test/exemplars spec/exemplars -glob=**/* - \ -default=model() -suffix=_exemplar.rb - -Finally, one Vim feature that proves helpful in conjunction with all of the -above is |CTRL-^|. This keystroke edits the previous file, and is helpful to -back out of any of the above commands. - -RAKE *rails-rake* - -Rake integration happens through the :Rake command. - - *rails-:Rake* -:[range]Rake {targets} Calls |:make!| {targets} (with 'makeprg' being rake, - or `bundle exec rake` if bundler.vim is active) and - opens the quickfix window if there were any errors. - An argument of "-" reruns the last task. If {targets} - are omitted, :Rake defaults to something sensible as - described below. Giving a line number argument may - affect that default. - - *rails-:Rake!* -:[range]Rake! {targets} Called with a bang, :Rake will forgo opening the - quickfix window. - - *rails-rake-defaults* - -Generally, the default task is one that runs the test you'd expect. For -example, if you're in a view in an RSpec application, the view spec is run, -but if it's a Test::Unit application, the functional test for the -corresponding controller is run. The following table lists the most -interesting mappings: - -File Task ~ -unit test test:units TEST=... -functional test test:functionals TEST=... -integration test test:integration TEST=... -spec spec SPEC=... -feature cucumber FEATURE=... -model test:units TEST=... spec SPEC=... -controller test:functionals TEST=... spec SPEC=... -helper test:functionals TEST=... spec SPEC=... -view test:functionals TEST=... spec SPEC=... -fixtures db:fixtures:load FIXTURES=... -migration db:migrate VERSION=... -config/routes.rb routes -db/seeds.rb db:seed - -Additionally, when :Rake is given a line number (e.g., :.Rake), the following -additional tasks can be invoked: - -File Task ~ -unit test test:units TEST=... TESTOPTS=-n... -functional test test:functionals TEST=... TESTOPTS=-n... -integration test test:integration TEST=... TESTOPTS=-n... -spec spec SPEC=...:... -feature cucumber FEATURE=...:... -controller routes CONTROLLER=... -fixtures db:fixtures:identify LABEL=... -migration in self.up db:migrate:up VERSION=... -migration in self.down db:migrate:down VERSION=... -migration elsewhere db:migrate:redo VERSION=... -task ... (try to guess currently edited declaration) - -Finally, you can override the default task with a comment like "# rake ..." -before the method pointed to by [range] or at the top of the file. - -SCRIPT WRAPPERS *rails-scripts* - -The following commands are wrappers around the scripts in the script directory -of the Rails application. Most have extra features beyond calling the script. -A limited amount of completion with <Tab> is supported. - - *rails-:Rscript* -:Rscript {script} {options} - Call ruby script/{script} {options}. Defaults to - calling script/console. - - *rails-:Rconsole* -:Rconsole {options} Obsolete. Call |:Rscript| instead. - - *rails-:Rrunner* -:[range]Rrunner {code} Executes {code} with script/runner. Differs from - :Rscript runner {code} in that the code is passed as - one argument. Also, |system()| is used instead of - |:!|. This is to help eliminate annoying "Press - ENTER" prompts. If a line number is given in the - range slot, the output is pasted into the buffer after - that line. - - *rails-:Rp* -:[range]Rp {code} Like :Rrunner, but call the Ruby p method on the - result. Literally "p begin {code} end". - - *rails-:Rpp* *rails-:Ry* -:[range]Rpp {code} Like :Rp, but with pp (pretty print) or y (YAML -:[range]Ry {code} output). - - *rails-:Rgenerate* -:Rgenerate {options} Calls script/generate {options}, and then edits the - first file generated. - - *rails-:Rdestroy* -:Rdestroy {options} Calls script/destroy {options}. - - *rails-:Rserver* -:Rserver {options} Launches script/server {options} in the background. - On win32, this means |!start|. On other systems, this - uses the --daemon option. - - *rails-:Rserver!* -:Rserver! {options} Same as |:Rserver|, only first attempts to kill any - other server using the same port. On non-Windows - systems, lsof must be installed for this to work. - -REFACTORING HELPERS *rails-refactoring* - -A few features are dedicated to helping you refactor your code. - -Partial Extraction ~ - *rails-partials* - -The :Rextract command can be used to extract a partial to a new file. - - *rails-:Rextract* -:[range]Rextract [{controller}/]{name} - Create a {name} partial from [range] lines (default: - current line). - - *rails-:Rpartial* -:[range]Rpartial [{controller}/]{name} - Obsolete alias for :Rextract. - -If this is your file, in app/views/blog/show.html.erb: > - - 1 <div> - 2 <h2><%= @post.title %></h2> - 3 <p><%= @post.body %></p> - 4 </div> - -And you issue this command: > - - :2,3Rextract post - -Your file will change to this: > - - 1 <div> - 2 <%= render :partial => 'post' %> - 3 </div> - -And app/views/blog/_post.html.erb will now contain: > - - 1 <h2><%= post.title %></h2> - 2 <p><%= post.body %></p> - -As a special case, if the file had looked like this: > - - 1 <% for object in @posts -%> - 2 <h2><%= object.title %></h2> - 3 <p><%= object.body %></p> - 4 <% end -%> -< -The end result would have been this: > - - 1 <%= render :partial => 'post', :collection => @posts %> -< -The easiest way to choose what to extract is to use |linewise-visual| mode. -Then, a simple > - :'<,'>Rextract blog/post -will suffice. (Note the use of a controller name in this example.) - -Migration Inversion ~ - *rails-migrations* *rails-:Rinvert* -:Rinvert In a migration, rewrite the self.up method into a - self.down method. If self.up is empty, the process is - reversed. This chokes on more complicated - instructions, but works reasonably well for simple - calls to create_table, add_column, and the like. - -INTEGRATION *rails-integration* - -Having one foot in Rails and one in Vim, rails.vim has two worlds with which -to interact. - -Integration with the Vim Universe ~ - *rails-vim-integration* - -A handful of Vim plugins are enhanced by rails.vim. All plugins mentioned can -be found at http://www.vim.org/. Cream and GUI menus (for lack of a better -place) are also covered in this section. - - *rails-:Rtree* -:Rtree [{arg}] If |NERDTree| is installed, open a tree for the - application root or the given subdirectory. - - *rails-:Rdbext* *rails-dbext* -:Rdbext [{environment}] This command is only provided when the |dbext| plugin - is installed. Loads the {environment} configuration - (defaults to $RAILS_ENV or development) from - config/database.yml and uses it to configure dbext. - The configuration is cached on a per application - basis. With dbext version 8.00 and newer, this - command is called automatically when needed. When - dbext is configured, you can execute SQL directly from - Vim: > - :Select * from posts order by id desc - :Update comments set author_id = 1 -< - *rails-surround* -The |surround| plugin available from vim.org enables adding and removing -"surroundings" like parentheses, quotes, and HTML tags. Even by itself, it is -quite useful for Rails development, particularly eRuby editing. When coupled -with this plugin, a few additional replacement surroundings are available in -eRuby files. See the |surround| documentation for details on how to use them. -The table below uses ^ to represent the position of the surrounded text. - -Key Surrounding ~ -= <%= ^ %> -- <% ^ -%> -# <%# ^ %> -<C-E> <% ^ -%>\n<% end -%> - -The last surrounding is particularly useful in insert mode with the following -map in one's vimrc. Use Alt+o to open a new line below the current one. This -works nicely even in a terminal (where most alt/meta maps will fail) because -most terminals send <M-o> as <Esc>o anyways. -> - imap <M-o> <Esc>o -< -One can also use the <C-E> surrounding in a plain Ruby file to append a bare -"end" on the following line. - - *rails-abolish* -Among the many features of |abolish| on vim.org is the ability to change the -inflection of the word under the cursor. For example, one can hit crs to -change from MixedCase to snake_case. This plugin adds two additional -inflections: crl for alternating between the singular and plural, and crt for -altering between tableize and classify. The latter is useful in changing -constructs like BlogPost.all to current_user.blog_posts.all and vice versa. - - *rails-cream* -This plugin provides a few additional key bindings if it is running under -Cream, the user friendly editor which uses Vim as a back-end. Ctrl+Enter -finds the file under the cursor (as in |rails-gf|), and Alt+[ and Alt+] find -the alternate (|rails-alternate|) and related (|rails-related|) files. - - *rails-menu* -If the GUI is running, a menu for several commonly used features is provided. -Also on this menu is a list of recently accessed projects. This list of -projects can persist across restarts if a 'viminfo' flag is set to enable -retaining certain global variables. If this interests you, add something like -the following to your vimrc: > - set viminfo^=! -< -Integration with the Rails Universe ~ - *rails-rails-integration* -The general policy of rails.vim is to focus exclusively on the Ruby on Rails -core. Supporting plugins and other add-ons to Rails has the potential to -rapidly get out of hand. However, a few pragmatic exceptions have been made. - - *rails-template-types* -Commands like :Rview use a hardwired list of extensions (erb, rjs, etc.) -when searching for files. In order to facilitate working with non-standard -template types, several popular extensions are featured in this list, -including haml, liquid, and mab (markaby). These extensions will disappear -once a related configuration option is added to rails.vim. - - *rails-rspec* -The presence of a spec directory causes several additional behaviors to -activate. :A knows about specs and will jump to them (but Test::Unit files -still get priority). The associated controller or model of a spec is -detected, so all navigation commands should work as expected inside a spec -file. :Rake in a spec runs just that spec, and in a model, controller, or -helper, runs the associated spec. - -|:Runittest| and |:Rfunctionaltest| lead double lives, handling model and -controller specs respectively. For helper and view specs, you can use -|:Rspec| or define your own navigation commands: -> - Rnavcommand spechelper spec/helpers -glob=**/* - \ -suffix=_helper_spec.rb -default=controller() - Rnavcommand specview spec/views -glob=**/* -suffix=_spec.rb -< -ABBREVIATIONS *rails-abbreviations* *rails-snippets* - -Abbreviations are "snippets lite". They may later be extracted into a -separate plugin, or removed entirely. - - *rails-:Rabbrev* -:Rabbrev List all Rails abbreviations. - -:Rabbrev {abbr} {expn} [{extra}] - Define a new Rails abbreviation. {extra} is permitted - if and only if {expn} ends with "(". - - *rails-:Rabbrev!* -:Rabbrev! {abbr} Remove an abbreviation. - -Rails abbreviations differ from regular abbreviations in that they only expand -after a <C-]> (see |i_CTRL-]|) or a <Tab> (if <Tab> does not work, it is -likely mapped by another plugin). If the abbreviation ends in certain -punctuation marks, additional expansions are possible. A few examples will -hopefully clear this up (all of the following are enabled by default in -appropriate file types). - -Command Sequence typed Resulting text ~ -Rabbrev rp( render :partial\ => rp( render(:partial => -Rabbrev rp( render :partial\ => rp<Tab> render :partial => -Rabbrev vs( validates_size_of vs( validates_size_of( -Rabbrev pa[ params pa[:id] params[:id] -Rabbrev pa[ params pa<C-]> params -Rabbrev pa[ params pa.inspect params.inspect -Rabbrev AR:: ActionRecord AR::Base ActiveRecord::Base -Rabbrev :a :action\ =>\ render :a<Tab> render :action => - -In short, ( expands on (, :: expands on . and :, and [ expands on . and [. -These trailing punctuation marks are NOT part of the final abbreviation, and -you cannot have two mappings that differ only by punctuation. - -You must escape spaces in your expansion, either as "\ " or as "<Space>". For -an abbreviation ending with "(", you may define where to insert the -parenthesis by splitting the expansion into two parts (divided by an unescaped -space). - -Many abbreviations are provided by default: use :Rabbrev to list them. They -vary depending on the type of file (models have different abbreviations than -controllers). There is one "smart" abbreviation, :c, which expands to -":controller => ", ":collection => ", or ":conditions => " depending on -context. - -SYNTAX HIGHLIGHTING *rails-syntax* - -Syntax highlighting is by and large a transparent process. For the full -effect, however, you need a colorscheme which accentuates rails.vim -extensions. One such colorscheme is vividchalk, available from vim.org. - -The following is a summary of the changes made by rails.vim to the standard -syntax highlighting. - - *rails-syntax-keywords* -Rails specific keywords are highlighted in a filetype specific manner. For -example, in a model, has_many is highlighted, whereas in a controller, -before_filter is highlighted. A wide variety of syntax groups are used but -they all link by default to railsMethod. - -If you feel a method has been wrongfully omitted, submit it to the -|rails-plugin-author|. - - *rails-syntax-classes* -Models, helpers, and controllers are given special highlighting. Depending on -the version of Vim installed, you may need a rails.vim aware colorscheme in -order to see this. Said colorscheme needs to provide highlighting for the -railsUserClass syntax group. - -The class names are determined by camelizing filenames from certain -directories of your application. If app/models/line_item.rb exists, the class -"LineItem" will be highlighted. - -The list of classes is refreshed automatically after certain commands like -|:Rgenerate|. Use |:Rrefresh| to trigger the process manually. - - *rails-syntax-assertions* -If you define custom assertions in test_helper.rb, these will be highlighted -in your tests. These are found by scanning test_helper.rb for lines of the -form " def assert_..." and extracting the method name. The railsUserMethod -syntax group is used. The list of assertions can be refreshed with -|:Rrefresh|. - - *rails-syntax-strings* -In the following line of code, the "?" in the conditions clause and the "ASC" -in the order clause will be highlighted: > - Post.find(:all, :conditions => ["body like ?","%e%"], :order => "title ASC") -< -A string literal using %Q<> or %<> delimiters will have its contents -highlighted as HTML. This is sometimes useful when writing helpers. > - link = %<<a href="http://www.vim.org">Vim</a>> -< - *rails-syntax-yaml* -YAML syntax highlighting has been extended to highlight eRuby, which can be -used in most Rails YAML files (including database.yml and fixtures). - -MANAGED VIM OPTIONS *rails-options* - -The following options are set local to buffers where the plugin is active. - - *rails-'shiftwidth'* *rails-'sw'* - *rails-'softtabstop'* *rails-'sts'* - *rails-'expandtab'* *rails-'et'* -A value of 2 is used for 'shiftwidth' (and 'softtabstop'), and 'expandtab' is -enabled. This is a strong convention in Rails, so the conventional wisdom -that this is a user preference has been ignored. - - *rails-'path'* *rails-'pa'* -All the relevant directories from your application are added to your 'path'. -This makes it easy to access a buried file: > - :find blog_controller.rb -< - *rails-'suffixesadd'* *rails-'sua'* -This is filetype dependent, but typically includes .rb, .rake, and several -others. This allows shortening the above example: > - :find blog_controller -< - *rails-'includeexpr'* *rails-'inex'* -The 'includeexpr' option is set to enable the magic described in |rails-gf|. - - *rails-'filetype'* *rails-'ft'* -The 'filetype' is sometimes adjusted for Rails files. Most notably, *.rxml -and *.rjs are treated as Ruby files, and files that have been falsely -identified as Mason sources are changed back to eRuby files (but only when -they are part of a Rails application). - - *rails-'completefunc'* *rails-'cfu'* -A 'completefunc' is provided (if not already set). It is very simple, as it -uses syntax highlighting to make its guess. See |i_CTRL-X_CTRL-U|. - -CONFIGURATION *rails-configuration* - -Very little configuration is actually required; this plugin automatically -detects your Rails application and adjusts Vim sensibly. - - *rails-:autocmd* *rails-autocommands* -If you would like to set your own custom Vim settings whenever a Rails file is -loaded, you can use an autocommand like the following in your vimrc: > - autocmd User Rails silent! Rlcd - autocmd User Rails map <buffer> <F9> :Rake<CR> -You can also have autocommands that only apply to certain types of files. -These are based off the information shown when running the |:Rails!| -command, with hyphens changed to periods. A few examples: > - autocmd User Rails.controller* iabbr <buffer> wsn wsdl_service_name - autocmd User Rails.model.arb* iabbr <buffer> vfo validates_format_of - autocmd User Rails.view.erb* imap <buffer> <C-Z> <%= %><C-O>3h -End all such Rails autocommands with asterisks, even if you have an exact -specification, to allow for more specific subtypes to be added in the future. -There is also a filename matching syntax: > - autocmd User Rails/config/environment.rb Rabbrev c config - autocmd User Rails/**/foo_bar.rb Rabbrev FB:: FooBar -Use the filetype based syntax whenever possible, reserving the filename based -syntax for more advanced cases. - - *macros/rails.vim* -If you have several commands to run on initialization for all file types, they -can be placed in a "macros/rails.vim" file in the 'runtimepath' (for example, -"~/.vim/macros/rails.vim"). This file is sourced by rails.vim each time a -Rails file is loaded. - - *config/rails.vim* -If you have settings particular to a specific project, they can be put in a -config/rails.vim file in the root directory of the application. The file is -sourced in the |sandbox| for security reasons. - - *rails-:Rset* -:Rset {option}[={value}] - Query or set a local option. This command may be - called directly, from an autocommand, or from - config/rails.vim. - -Options may be set in one of four scopes, which may be indicated by an -optional prefix. These scopes determine how broadly an option will apply. -Generally, the default scope is sufficient. - -Scope Description ~ -a: All files in one Rails application -b: Buffer (file) specific -g: Global to all applications -l: Local to method (same as b: in non-Ruby files) - -Options are shown below with their default scope, which should be omitted. -While you may override the scope with a prefix, this is rarely necessary and -oftentimes useless. (For example, setting g:task is useless because the -default rake task will apply before considering this option.) - -Option Meaning ~ -b:alternate Custom alternate file for :A, relative to the Rails root -b:controller Default controller for certain commands (e.g., :Rhelper) -b:model Default model for certain commands (e.g., :Rfixtures) -l:related Custom related file for :R, relative to the Rails root -a:root_url Root URL for commands like :Rpreview - -Examples: > - :Rset root_url=http://localhost:12345 - :Rset related=app/views/blog/edit.html.erb -< - *rails-modelines* -If |g:rails_modelines| is enabled, these options can also be set from -modelines near the beginning or end of the file. These modelines will always -set buffer-local options; scope should never be specified. Examples: > - # Rset task=db:schema:load - <%# Rset alternate=app/views/layouts/application.html.erb %> -Modelines can also be local to a method. Example: > - def test_comment - # rset alternate=app/models/comment.rb -These two forms differ only in case. - -Modelines are deprecated. - -GLOBAL SETTINGS *rails-global-settings* - -A few global variables control the behavior of this plugin. In general, they -can be enabled by setting them to 1 in your vimrc, and disabled by setting -them to 0. > - let g:rails_some_option=1 - let g:rails_some_option=0 -Most of these seldom need to be used. So seldom, in fact, that you should -notify the |rails-plugin-author| if you find any of them useful, as nearly all -are being considered for removal. - - *g:loaded_rails* > - let g:loaded_rails=1 -Set this include guard to prevent the plugin from being loaded. - - *g:rails_abbreviations* -Enable Rails abbreviations. See |rails-abbreviations|. Enabled by default. - - *g:rails_ctags_arguments* > - let g:rails_ctags_arguments='--languages=-javascript' -Additional arguments to pass to ctags from |:Rtags|. Defaults to ignoring -JavaScript files, since ctags has a tendency to choke on those. - - *g:rails_default_file* > - let g:rails_default_file='config/database.yml' -File to load when a new Rails application is created. Defaults to the README. - - *rails-screen* *g:rails_gnu_screen* > - let g:rails_gnu_screen=1 -Use GNU Screen or Tmux (if it is running) to launch |:Rscript| console and -|:Rserver| in the background. Enabled by default. - - *g:rails_history_size* > - let g:rails_history_size=5 -Number of projects to remember. Set to 0 to disable. See |rails-menu| for -information on retaining these projects across a restart. - - *g:rails_mappings* > - let g:rails_mappings=1 -Enables a few mappings (mostly for |rails-navigation|). Enabled by default. - - *g:rails_modelines* > - let g:rails_modelines=1 -Enable modelines like the following: > - # Rset task=db:schema:load -Modelines set buffer-local options using the :Rset command. -Also enables method specific modelines (note the case difference): > - def show - # rset preview=blog/show/1 -Modelines are deprecated and disabled by default. - - *g:rails_menu* > - let g:rails_menu=1 -When 2, a Rails menu is created. When 1, this menu is a submenu under the -Plugin menu. The default is 0, as the menu is slated for removal from future -versions of rails.vim. - - *g:rails_url* > - let g:rails_url='http://localhost:3000/' -Used for the |:Rpreview| command. Default is as shown above. Overridden by -b:rails_url. - - *g:rails_syntax* > - let g:rails_syntax=1 -When enabled, this tweaks the syntax highlighting to be more Rails friendly. -Enabled by default. See |rails-syntax|. - - *rails-tabs* *g:rails_tabstop* > - let g:rails_tabstop=4 -This option now requires the plugin railstab.vim from vim.org: - http://www.vim.org/scripts/script.php?script_id=2253 - -If your goal is simply just override this plugin's settings and use your own -custom 'shiftwidth', adjust things manually in an autocommand: > - autocmd User Rails set sw=4 sts=4 noet -This is highly discouraged: don't fight Rails. - -ABOUT *rails-about* *rails-plugin-author* - -This plugin was written by Tim Pope. Email all comments, complaints, and compliments to him at vim at tpope. org. - -The latest stable version can be found at - http://www.vim.org/scripts/script.php?script_id=1567 - -Bugs can be reported and the very latest development version can be retrieved -from GitHub: - https://github.com/tpope/vim-rails - git clone git://github.com/tpope/vim-rails.git - - *rails-license* -Copyright (c) Tim Pope. Distributed under the same terms as Vim itself. -See |license|. - - vim:tw=78:ts=8:ft=help:norl: |