diff options
Diffstat (limited to 'files/.vim/doc/rails.txt')
| -rw-r--r-- | files/.vim/doc/rails.txt | 1131 |
1 files changed, 0 insertions, 1131 deletions
diff --git a/files/.vim/doc/rails.txt b/files/.vim/doc/rails.txt deleted file mode 100644 index 2390100..0000000 --- a/files/.vim/doc/rails.txt +++ /dev/null @@ -1,1131 +0,0 @@ -*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: |