diff options
Diffstat (limited to 'files/.vim/doc/rails.txt')
| -rwxr-xr-x | files/.vim/doc/rails.txt | 1131 |
1 files changed, 1131 insertions, 0 deletions
diff --git a/files/.vim/doc/rails.txt b/files/.vim/doc/rails.txt new file mode 100755 index 0000000..2390100 --- /dev/null +++ b/files/.vim/doc/rails.txt @@ -0,0 +1,1131 @@ +*rails.txt* Plugin for working with Ruby on Rails applications + +Author: Tim Pope <vimNOSPAM@tpope.info> |rails-plugin-author| + +|rails-introduction| Introduction and Feature Summary +|rails-installation| Installation and Usage +|rails-install-vim| Installing and Configuring Vim +|rails-install-plugin| Installing and Using the Plugin +|rails-commands| General Commands +|rails-navigation| Navigation +|rails-gf| File Under Cursor - gf +|rails-alternate-related| Alternate and Related Files +|rails-model-navigation| Model Navigation Commands +|rails-controller-navigation| Controller Navigation Commands +|rails-misc-navigation| Miscellaneous Navigation Commands +|rails-custom-navigation| Custom Navigation Commands +|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* + +TextMate may be the latest craze for developing Ruby on Rails applications, +but Vim is forever. This plugin offers the following features for Ruby on +Rails application development. + +1. Automatically detects buffers containing files from Rails applications, + and applies settings to those buffers (and only those buffers). You can + use an autocommand to apply your own custom settings as well. + |rails-configuration| + +2. Unintrusive. Only files in a Rails application should be affected; regular + Ruby scripts are left untouched. Even when enabled, the plugin should keep + out of your way if you're not using its features. (If you find a situation + where this is not a case, contact the |rails-plugin-author|.) + +3. Provides reasonable settings for working with Rails applications. Rake is + the 'makeprg' (and it always knows where your Rakefile is), 'shiftwidth' + is 2, and 'path' includes an appropriate collection of directories from + your application. |rails-options| + +4. Easy navigation of the Rails directory structure. |gf| considers context + and knows about partials, fixtures, and much more. There are two commands, + :A (alternate) and :R (related) for easy jumping between files, including + favorites like model to migration, template to helper, and controller to + functional test. For more advanced usage, :Rmodel, :Rview, :Rcontroller, + and several other commands are provided. |rails-navigation| + +5. Enhanced syntax highlighting. From has_and_belongs_to_many to + distance_of_time_in_words, it's here. For Vim 7 users, 'completefunc' is + set to enable syntax based completion on |i_CTRL-X_CTRL-U|, making it easy + to complete such long method names. |rails-syntax| + +6. Interface to script/*. Generally, use ":Rscript about" to call + "script/about". Most commands have wrappers with additional features: + ":Rgenerate controller Blog" generates a blog controller and edits + app/controllers/blog_controller.rb. |rails-scripts| + +7. Partial extraction and migration inversion. |:Rextract| {file} replaces + the desired range (ideally selected in visual line mode) with "render + :partial => '{file}'", which is automatically created with your content. + The @{file} instance variable is replaced with the {file} local variable. + |:Rinvert| takes a self.up migration and writes a self.down. + |rails-refactoring| + +8. Integration with other plugins. |:Rproject| creates a new project.vim + project. |:Rdbext| loads database settings from database.yml for dbext.vim + (and this happens by default under most circumstances). Cream users get + some additional mappings, and all GUI users get a menu. |rails-integration| + +============================================================================== +INSTALLATION AND USAGE *rails-installation* + +If you are familiar Vim and have the latest version installed, you may skip +directly to |rails-install-plugin| below. + +Installing and Configuring Vim ~ + *rails-install-vim* +Because it is common for users to utilize an older version of Vim that came +installed on a system, rails.vim has a design goal of remaining compatible +with versions of Vim 6.2 and newer. However, if you have a choice in the +matter, you are strongly encouraged to install the latest version available. +Older versions of Vim should work, but increasingly, new plugin features will +require Vim 7 or newer. If possible, install a version of Vim with the |Ruby| +interface compiled in, as a few features will make use of it when available. + +If you are new to Vim, you need to create a vimrc. For Windows, this file +goes in ~\_vimrc (try :e ~\_vimrc if you don't know where this is). On other +platforms, use ~/.vimrc. A very minimal example file is shown below. +> + set nocompatible + syntax on + filetype plugin indent on +> +Installing and Using the Plugin ~ + *rails-install-plugin* +If you have the zip file, extract it to vimfiles (Windows) or ~/.vim +(everything else). You should have the following files: > + plugin/rails.vim + doc/rails.txt +See |add-local-help| for instructions on enabling the documentation. In a +nutshell: > + :helptags ~/.vim/doc + +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 {directory} The only global command. Creates a new Rails + application in {directory}, and loads the README. + + *rails-:Rake* +:Rake {targets} Like calling |:make| {targets} (with 'makeprg' being + rake). However, in some contexts, if {targets} are + omitted, :Rake defaults to something sensible (like + db:migrate in a migration, or your current test). + + *rails-:Rake!* +:Rake! {targets} Called with a bang, :Rake will use an alternate + 'errorformat' which attempts to parse the full stack + backtrace. + + *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} Edit {file}, relative to the application root. + + *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. If {path} is omitted, a sensible + default is used (considers the current + controller/template, but does not take routing into + account). 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|). + + *rails-:Rpreview!* +:Rpreview! [{path}] As with :Rpreview, except :OpenURL is never used. + + *rails-:Rtags* +:Rtags Calls ctags -R on the current application root. + Exuberant ctags must be installed. + + *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 has("mac_gui"), has("win32_gui"), 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 blog_controller + :find book_test +< + *rails-:Rfind* +:Rfind [{file}] Find {file}. Very similar to :find, but things like + BlogController are properly handled, and if + genutils.vim is installed (1.x not 2.x), tab complete + works. The default filename is taken from under the + cursor in a manner quite similar to gf, described + below. + +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.find(: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 :partial => 'sh*ared/sidebar' %> +< app/views/shared/_sidebar.rhtml ~ +> + <%= stylesheet_link_tag :scaf*fold %> +< public/stylesheets/scaffold.css ~ +> + class BlogController < Applica*tionController +< app/controllers/application.rb ~ +> + class ApplicationController < ActionCont*roller::Base +< .../action_controller/base.rb ~ +> + fixtures :pos*ts +< test/fixtures/posts.yml ~ +> + layout :pri*nt +< app/views/layouts/print.rhtml ~ +> + <%= 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* +: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), or +:AT a new tab (:AT). A mapping for :A is [f . + + *rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT* +:R These are similar |rails-:A| and friends above, only +:RE they jump to the "related" file rather than the +:RS "alternate." A mapping for :R is ]f . +:RV +:RT + + *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 +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 follow: + +Current file Alternate file Related file ~ +model unit test related migration +controller (in method) functional test template (view) +template (view) helper controller (jump to method) +migration previous migration next migration +config/routes.rb config/database.yml config/environment.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. + +For the less common cases, a more deliberate set of commands are provided. +Each of the following takes an optional argument (with tab completion) but +defaults to a reasonable guess that follows Rails conventions. For example, +when editing app/models/employee.rb, :Rcontroller will default to +app/controllers/employees_controller.rb. The controller and model options, +ideally set from |rails-modelines|, can override the mapping from model +related files to controller related files (Rset controller=hiring) and vice +versa (Rset model=employee). See |rails-:Rset|. + +Each of the following commands has variants for splitting, vertical splitting +and opening in a new tab. For :Rmodel, those variants would be :RSmodel, +:RVmodel, and :RTmodel. There is also :REmodel which is a synonym for :Rmodel +(future versions might allow customization of the behavior of :Rmodel). + + +Model Navigation Commands ~ + *rails-model-navigation* +The default for model navigation commands is the current model, if it can be +determined. For example, test/unit/post_test.rb would have a current model +of post. Otherwise, if a controller name can be determined, said controller +name will be singularized and used. To override this, use a command or +modeline like: > + Rset model=comment + +:Rmodel |rails-:Rmodel| +:Rmigration |rails-:Rmigration| +:Robserver |rails-:Robserver| +:Rfixtures |rails-:Rfixtures| +:Runittest |rails-:Runittest| + + *rails-:Rmodel* +:Rmodel [{name}] Edit the specified model. + + *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. The pattern defaults to the current + model name, pluralized. So when editing the Post + model, :Rmigration with no arguments might find + create_posts.rb, or add_date_to_posts.rb. + + *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-:Rfixtures* +:Rfixtures [{name}] Edit the fixtures for the given 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 automatically. An + optional extension can be given, to distinguish + between YAML and CSV fixtures. + + *rails-:Runittest* +:Runittest [{name}] Edit the unit test for the specified model. + +Controller Navigation Commands ~ + *rails-controller-navigation* +The default for controller navigation commands is the current controller, if +it can be determined. For example, test/functional/blog_test.rb would have a +current controller of blog. Otherwise, if a model name can be determined, +said model name will be pluralized and used. To override this, use a command +or modeline like: > + Rset controller=blog + +:Rcontroller |rails-:Rcontroller| +:Rhelper |rails-:Rhelper| +:Rview |rails-:Rview| +:Rlayout |rails-:Rlayout| +:Rfunctionaltest |rails-:Rfunctionaltest| + + *rails-:Rcontroller* +:Rcontroller [{name}] Edit the specified controller. + + *rails-:Rhelper* +:Rhelper [{name}] Edit the helper for the specified controller. + + *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. + + *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-:Rapi* +:Rapi [{name}] Edit the API for the specified controller. This + command is deprecated; add it yourself with + |:Rcommand| if you still desire it. + + *rails-:Rfunctionaltest* +:Rfunctionaltest [{name}] + Edit the functional test for the specified controller. + +Miscellaneous Navigation Commands ~ + *rails-misc-navigation* + +The following commands are not clearly associated with models or controllers. + +:Rstylesheet |rails-:Rstylesheet| +:Rjavascript |rails-:Rjavascript| +:Rplugin |rails-:Rplugin| +:Rlib |rails-:Rlib| +:Rtask |rails-:Rtask| +:Rintegrationtest |rails-:Rintegrationtest| + + *rails-:Rstylesheet* +:Rstylesheet [{name}] Edit the stylesheet for the specified name, defaulting + to the current controller's name. + + *rails-:Rjavascript* +:Rjavascript [{name}] Edit the javascript for the specified name, defaulting + to the current controller's name. + + *rails-:Rplugin* +:Rplugin {plugin}[/{path}] + Edits a file within a plugin. If the path to the file + is omitted, it defaults to init.rb. + + *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. + + *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-:Rintegrationtest* +:Rintegrationtest [{name}] + Edit the integration test specified. The default + is based on the current controller or model, with no + singularization or pluralization done. + +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-:Rcommand* +:Rcommand [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. + +:Rcommand is still under development and far from fully documented, but the +following examples should illustrate the basics: +> + Rcommand api app/apis -glob=**/* -suffix=_api.rb + Rcommand config config -glob=*.* -suffix= -default=routes.rb + Rcommand environment config/environments -default=../environment + Rcommand concern app/concerns -glob=**/* + +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. + +============================================================================== +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}. + + *rails-:Rconsole* +:Rconsole {options} Start script/console. On Windows it will be launched + in the background with |!start|. In the terminal + version GNU Screen is used if it is running and + |g:rails_gnu_screen| is set. + + *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. Respects |g:rails_subversion|. + + *rails-:Rdestroy* +:Rdestroy {options} Calls script/destroy {options}. Respects + |g:rails_subversion|. + + *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} + Deprecated alias for :Rextract. + +If this is your file, in app/views/blog/show.rhtml: > + + 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.rhtml 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-:Rproject* *rails-project* +:Rproject [{file}] This command is only provided when the |project| + plugin is installed. Invoke :Project (typically + without an argument), and search for the root of the + current Rails application. If it is not found, create + a new project, with appropriate directories (app, + etc., but not vendor). + + *rails-:Rproject!* +:Rproject! [{file}] Same as :Rproject, only delete existing project if it + exists and recreate it. The logic to delete the old + project is convoluted and possibly erroneous; report + any problems to the |rails-plugin-author|. A handy + mapping might look something like: > + autocmd User Rails map <buffer> <F6> :Rproject!|silent w<CR> +< As a bonus, this command organizes views into separate + directories for easier navigation. The downside of + this is that you will have to regenerate your project + each time you add another view directory (which is why + this command recreates your project each time!). + + *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 until a different Rails + application is edited. This command is called for you + automatically when |g:rails_dbext| is set (default on + non-Windows systems). + + *rails-:Rdbext!* +:Rdbext! [{environment}] + Load the database configuration as above, and then + attempt a CREATE DATABASE for it. This is primarily + useful for demonstrations. + + *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-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 (rhtml, 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* +Support for RSpec is currently experimental and incomplete, with only a +handful of features being implemented. :A knows about specs and will jump to +them, but only if no test file is found. The associated controller or model +of a spec is detected, so all navigation commands should work as expected +inside a spec file. :Rfixtures will find spec fixtures, but the extension is +mandatory and tab completion will not work. :Rake will run the currently +edited spec. + +While there are currently no built-in dedicated RSpec navigation commands, you +can approximate your own with |:Rcommand|. +> + Rcommand specmodel spec/models -glob=**/* + \ -suffix=_spec.rb -default=model() + Rcommand spechelper spec/helpers -glob=**/* + \ -suffix=_helper_spec.rb -default=controller() + Rcommand speccontroller spec/controllers -glob=**/* + \ -suffix=_controller_spec.rb -default=controller() + Rcommand specview spec/views -glob=**/* -suffix=_view_spec.rb +< +============================================================================== +ABBREVIATIONS *rails-abbreviations* *rails-snippets* + +Abbreviations are still experimental. 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 [ expands on both . 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 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-@params* *rails-syntax-deprecated* +Certain deprecated syntax (like @params and render_text) is highlighted as an +error. If you trigger this highlighting, generally it means you need to +update your code. + + *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<> delimiters will have its contents highlighted as +HTML. This is sometimes useful when writing helpers. > + link = %Q<<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, .rhtml, 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-'statusline'* *rails-'stl'* +Useful information is added to the 'statusline', when |g:rails_statusline| is +enabled. + + *rails-'makeprg'* *rails-'mp'* + *rails-'errorformat'* *rails-'efm'* +Rake is used as the 'makeprg', so |:make| will work as expected. Also, +'errorformat' is set appropriately to handle your tests. + + *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 in the 'statusline' (see +|rails-'statusline'|), 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.rhtml* imap <buffer> <C-Z> <%= %><C-O>3h +End all such Rails autocommands with asterisks, even if you have an exact +specification. There is also a filename matching syntax: > + autocmd User Rails/db/schema.rb Rset task=db:schema:dump + 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. This only works in Vim 7 or +newer. + + *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 set in one of four scopes, which my 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:preview URL stub for :Rpreview (e.g., blog/show/1) +b:task Default task used with :Rake +l:related Custom related file for :R, relative to the Rails root +a:root_url Root URL for commands like :Rpreview +a:ruby_fork_port Experimental: use ruby_fork on given port to speed things up + +Examples: > + :Rset root_url=http://localhost:12345 + :Rset related=app/views/blog/edit.rhtml preview=blog/edit/1 + :Rset alternate=app/models/ + :Rset l:task=preview " Special pseudo-task for :Rake + +Note the use of a scope prefix in the last example. + + *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.rhtml %> +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. + +============================================================================== +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 should never need to be used. The few that might be interesting +are |g:rails_expensive|, |g:rails_subversion|, and |g:rails_default_database|. + + *g:loaded_rails* > + let g:loaded_rails=1 +Do not load the plugin. For emergency use only. + + *g:rails_abbreviations* +Enable Rails abbreviations. See |rails-abbreviations|. Enabled by default. + + *g:rails_dbext* > + let g:rails_dbext=1 +Enable integration with the dbext plugin, if it is installed. Defaults to the +value of |g:rails_expensive|. When this option is set, dbext settings are +automagically extracted from config/database.yml. Then, you can use features +like table name completion and commands like > + :Create database brablog_development + :Select * from posts where title like '%Denmark%' +Note that dbext is a complicated plugin, and may require additional +configuration. See |dbext| (if installed) and |sql-completion-dynamic| (in +Vim 7). + + *g:rails_default_file* > + let g:rails_default_file='config/database.yml' +File to load when a new Rails application is created, or when loading an +existing project from the menu. Defaults to the README. + + *g:rails_default_database* > + let g:rails_default_database='sqlite3' +Database to use for new applications. Defaults to letting Rails decide. + + *rails-slow* *g:rails_expensive* > + let g:rails_expensive=1 +Enables or disables expensive (slow) features (typically involving calls to +the Ruby interpreter). Recommended for moderately fast computers. This +option used to be disabled by default on Windows, but now it is enabled by +default everywhere. If the Vim Ruby interface is available, this option is +mostly ignored, as spawning a new process is generally the bottleneck for most +expensive operations. Set this option to 0 if you experience painful delays +when first editing a file from a Rails application. + + *rails-screen* *g:rails_gnu_screen* > + let g:rails_gnu_screen=1 +Use GNU Screen (if it is running) to launch |:Rconsole| 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 extremely useful but may cause security concerns when editing +projects from an untrusted source. Enabled 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 1. + + *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_statusline* > + let g:rails_statusline=1 +Give a clue in the statusline when this plugin is enabled. Enabled by +default. + + *g:rails_subversion* > + let g:rails_subversion=1 +Automatically add/remove files to the subversion repository for commands like +|:Rgenerate| and |:Rdestroy| (but not |:Rscript|). Ignored when the +application is not part of a subversion repository. Disabled by default. + + *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 is for people who dislike the default 'shiftwidth' of 2. When +non-zero, all files will have a |:retab|! done with 'tabstop' set to 2 on +load, to convert the initial indent from spaces to tabs. Then, 'tabstop' and +'shiftwidth' will be set to the option's value. The process is reversed on +write. Thus, one can use a custom indent when editing files, yet conform to +Rails conventions when saving them. There is also a local buffer version +of this option, to allow for things like: > + autocmd User Rails if &ft == 'ruby' | let b:rails_tabstop = 4 | endif +This option defaults to 0, which is the recommended value. + +If instead of all this magic, you would prefer to 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 him at <vimNOSPAM@tpope.info>. He +can also be found on Freenode's IRC network, hanging out in #rubyonrails and +#vim as tpope. + +The official homepage is + http://rails.vim.tpope.net +The latest stable version can be found at + http://www.vim.org/scripts/script.php?script_id=1567 +In Vim 7, you can keep up to date with |GetLatestVimScripts|. + +Development versions can be found at the following URLs: + http://tpope.us/rails.vba + http://tpope.us/rails.zip + http://svn.tpope.net/rails/vim/railsvim +The first is a |vimball| for Vim 7. The third is a subversion repository +and contains the very latest features and bugs. + +Feedback is highly desired on this plugin. Please send all comments, +complaints, and compliments to the author. No bug is too small to report. + + *rails-license* +This plugin is distributable under the same terms as Vim itself. See +|license|. No warranties, expressed or implied. + +============================================================================== +vim:tw=78:ts=8:ft=help:norl: |