rails.txt

*rails.txt*	Plugin for working with Ruby on Rails applications

Author:  Tim Pope <http://tpo.pe/>

|rails-introduction|            Introduction and Feature Summary
|rails-commands|                General Commands
|rails-navigation|              Navigation
|rails-gf|                          File Under Cursor - gf
|rails-alternate-related|           Alternate and Related Files
|rails-type-navigation|             File Type Commands
|rails-rake|                    Rake
|rails-scripts|                 Script Wrappers
|rails-refactoring|             Refactoring Helpers
|rails-partials|                    Partial Extraction
|rails-migrations|                  Migration Inversion
|rails-integration|             Integration
|rails-vim-integration|             Integration with the Vim Universe
|rails-rails-integration|           Integration with the Rails Universe
|rails-abbreviations|           Abbreviations
|rails-syntax|                  Syntax Highlighting
|rails-options|                 Managed Vim Options
|rails-projections|             Projections
|rails-configuration|           Configuration
|rails-global-settings|         Global Settings
|rails-about|                   About rails.vim
|rails-license|                     License

This plugin is only available if 'compatible' is not set.

{Vi does not have any of this}

INTRODUCTION					*rails-introduction* *rails*

Whenever you edit a file in a Rails application, this plugin will be
automatically activated.  This sets various options and defines a few
buffer-specific commands.

If you are in a hurry to get started, with a minimal amount of reading, you
are encouraged to at least skim through the headings and command names in this
file, to get a better idea of what is offered.  If you only read one thing,
make sure it is the navigation section: |rails-navigation|.

GENERAL COMMANDS				*rails-commands*

All commands are buffer local, unless otherwise stated.  This means you must
actually edit a file from a Rails application.

						*rails-:Rails-new*
:Rails new {directory}	The only global command.  Invokes "rails new
			{directory}" and loads the generated files into the
			quickfix list.

						*rails-:Rails!*
:Rails!			Show the version of rails.vim installed.  If rails.vim
			is active for the current buffer, also show the type
			of Rails file detected.

						*rails-:Redit*
:Redit {file}		Obsolete alias for |:R| or |:A|.

						*rails-:Rfind*
:Rfind [{file}]		Obsolete alias for |:find|.

						*rails-:Rlog*
:Rlog [{logfile}]	Split window and open {logfile} ($RAILS_ENV or
			development by default).  The control characters used
			for highlighting are removed.  If you have a :Tail
			command (provided by |tailminusf|.vim), that is used;
			otherwise, the file does NOT reload upon change.
			Use |:checktime| to tell Vim to check for changes.
			|G| has been mapped to do just that prior to jumping
			to the end of the file, and q is mapped to close the
			window.  If the delay in loading is too long, you
			might like :Rake log:clear.

						*rails-:Rpreview*
:Rpreview [path]	Open the given [path] for the current app in a
			browser.  The host and port are determined by applying
			some netstat/lsof trickery to the current server pid.
			If no server is running, Pow is consulted, and if all
			else fails, a default of localhost:3000 is used.  If
			[path] is omitted, a sensible default is used
			(considers the current controller/template, but does
			not take routing into account).  The default is
			overridden by comments like the following that are
			either before the current method call or at the top of
			the file: >

		# GET /users
		# PUT /users/1
<
			If it's not using the right browser, define an OpenURL
			command:
>
		:command -bar -nargs=1 OpenURL :!open <args>
<
						*rails-:Rpreview!*
:Rpreview! [{path}]	Like :Rpreview, but open the path inside Vim using
			|netrw| instead.

						*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-:Cd* *rails-:Rcd*
:Cd [{directory}]	|:cd| to /path/to/railsapp/{directory}.

						*rails-:Lcd* *rails-:Rlcd*
:Lcd [{directory}]	|:lcd| to /path/to/railsapp/{directory}.

						*rails-:Ctags* *rails-:Rtags*
:Ctags			Calls ctags -R on the current application root.
			Exuberant ctags must be installed.  Additional
			arguments can be passed to ctags with
			|g:rails_ctags_arguments|.

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 standard Rails load path is prepended to 'path', enabling |:find| to work:
>
	:find application_controller.rb
<
File Under Cursor - gf ~
						*rails-gf*
The |gf| command, which normally edits the current file under the cursor, has
been remapped to take context into account. |CTRL-W_f| (open in new window)
and |CTRL-W_gf| (open in new tab) are also remapped.

Example uses of |gf|, and where they might lead.
(* indicates cursor position)
>
	Pos*t.first
<	app/models/post.rb ~
>
	has_many :c*omments
<	app/models/comment.rb ~
>
	link_to 'Home', :controller => 'bl*og'
<	app/controllers/blog_controller.rb ~
>
	<%= render 'sh*ared/sidebar' %>
<	app/views/shared/_sidebar.html.erb ~
>
	<%= stylesheet_link_tag 'scaf*fold' %>
<	public/stylesheets/scaffold.css ~
>
	class BlogController < Applica*tionController
<	app/controllers/application_controller.rb ~
>
	class ApplicationController < ActionCont*roller::Base
<	.../action_controller/base.rb ~
>
	fixtures :pos*ts
<	test/fixtures/posts.yml ~
>
	layout :pri*nt
<	app/views/layouts/print.html.erb ~
>
	<%= link_to "New", new_comme*nt_path %>
<	app/controllers/comments_controller.rb (jumps to def new) ~

In the last example, the controller and action for the named route are
determined by evaluating routes.rb as Ruby and doing some introspection.  This
means code from the application is executed.  Keep this in mind when
navigating unfamiliar applications.

Alternate and Related Files ~
						*rails-alternate-related*
Two commands, :A and :R, are used to quickly jump to an "alternate" and a
"related" file, defined below.

	*rails-:A* *rails-:AE* *rails-:AS* *rails-:AV* *rails-:AT* *rails-:AD*
:A			These commands were picked to mimic Michael Sharpe's
:AE			a.vim.  Briefly, they edit the "alternate" file, in
:AS			either the same window (:A and :AE), a new split
:AV			window (:AS), a new vertically split window (:AV), a
:AT			new tab (:AT), or read it into the current buffer
:AD			(:AD).

	*rails-:R* *rails-:RE* *rails-:RS* *rails-:RV* *rails-:RT* *rails-:RD*
:R			These are similar |rails-:A| and friends above, only
:RE			they jump to the "related" file rather than the
:RS			"alternate."  With a file name argument, they edit
:RV			a file relative to the application root (:R Rakefile),
:RT			and with a count and a file name argument, they find a
:RD			file in 'path' (e.g., :1R PostsController.)  You can
			also append a line number (post.rb:42) or a method
			(PostsController#index) to both forms.

					*rails-alternate* *rails-related*
The alternate file is most frequently the test file, though there are
exceptions.  The related file varies, and is sometimes dependent on current
location in the file.  For example, when editing a controller, the related
file is template for the method currently being edited.

The easiest way to learn these commands is to experiment.  A few examples of
alternate and related files for a Test::Unit application follow:

Current file		Alternate file		Related file ~
model			unit test		schema definition
controller (in method)	functional test		template (view)
template (view)		functional test  	controller (jump to method)
migration		previous migration	next migration
database.yml		database.example.yml	environments/*.rb

Alternates can be tweaked with |rails-projections|.

File Type Navigation Commands ~
						*rails-type-navigation*
For the less common cases, a more deliberate set of commands are provided.
Each of the upcoming commands takes an optional argument (with tab completion)
but defaults to a reasonable guess.  Commands that default to the current
model or controller generally behave like you'd expect in other file types.
For example, in app/helpers/posts_helper.rb, the current controller is
"posts", and in test/fixtures/comments.yml, the current model is "comment".
In model related files, the current controller is the pluralized model name,
and in controller related files, the current model is the singularized
controller name.

Each of the following commands has variants for splitting, vertical splitting,
opening in a new tab, and reading the file into the current buffer.  For
:Emodel, those variants would be :Smodel, :Vmodel, :Tmodel, and :Dmodel.
They also allow for jumping to methods or line numbers using the same syntax
as |:R|, and file creation (with a bit of boilerplate) can be forced by adding
a ! after the filename (not after the command itself!).

There are also "classic" versions of these commands that start with :R (e.g.,
:Rmodel, :RSmodel, :RVmodel, :RTmodel, and :RDmodel).

:Econtroller					|rails-:Econtroller|
:Eenvironment					|rails-:Eenvironment|
:Efixtures					|rails-:Efixtures|
:Efunctionaltest				|rails-:Efunctionaltest|
:Ehelper					|rails-:Ehelper|
:Einitializer					|rails-:Einitializer|
:Eintegrationtest				|rails-:Eintegrationtest|
:Ejavascript					|rails-:Ejavascript|
:Elayout					|rails-:Elayout|
:Elib						|rails-:Elib|
:Elocale					|rails-:Elocale|
:Emailer					|rails-:Emailer|
:Emigration					|rails-:Emigration|
:Emodel						|rails-:Emodel|
:Eschema					|rails-:Eschema|
:Espec						|rails-:Espec|
:Estylesheet					|rails-:Estylesheet|
:Etask						|rails-:Etask|
:Eunittest					|rails-:Eunittest|
:Eview						|rails-:Eview|

				*rails-:Econtroller* *rails-:Rcontroller*
:Econtroller [{name}]	Edit the specified or current controller.

				*rails-:Eenvironment* *rails-:Renvironment*
:Eenvironment [{name}]  Edit the config/environments file specified.  With no
			argument, defaults to editing config/application.rb
			or config/environment.rb.

				*rails-:Efixtures* *rails-:Rfixtures*
:Efixtures [{name}]	Edit the fixtures for the given or current model.  If
			an argument is given, it must be pluralized, like the
			final filename (this may change in the future).  If
			omitted, the current model is pluralized.  An optional
			extension can be given, to distinguish between YAML
			and CSV fixtures.

			*rails-:Efunctionaltest* *rails-:Rfunctionaltest*
:Efunctionaltest [{name}]
			Edit the functional test or controller spec for the
			specified or current controller.

				*rails-:Ehelper* *rails-:Rhelper*
:Ehelper [{name}]	Edit the helper for the specified name or current
			controller.

				*rails-:Einitializer* *rails-:Rinitializer*
:Einitializer [{name}]  Edit the config/initializers file specified.  With no
			argument, defaults to editing config/routes.rb.

			*rails-:Eintegrationtest* *rails-:Rintegrationtest*
:Eintegrationtest [{name}]
			Edit the integration test, integration spec, or
			cucumber feature specified.  With no argument,
			defaults to editing test/test_helper.rb.

				*rails-:Ejavascript* *rails-:Rjavascript*
:Ejavascript [{name}]	Edit the JavaScript for the specified name or current
			controller.  Also supports CoffeeScript in
			app/scripts/.

				*rails-:Elayout* *rails-:Rlayout*
:Elayout [{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-:Elib* *rails-:Rlib*
:Elib [{name}]		Edit the library from the lib directory for the
			specified name.  With no argument, defaults to editing
			the application Gemfile (a task formally handled by
			the defunct :Rplugin).

				*rails-:Elocale* *rails-:Rlocale*
:Elocale [{name}]	Edit the config/locale file specified, optionally
			adding a yml or rb extension if none is given.  With
			no argument, checks config/environment.rb for the
			default locale.

				*rails-:Emailer* *rails-:Rmailer*
:Emailer [{name}]	Edit the mailer specified.  This looks in both
			app/mailers for Rails 3 and app/models for older
			versions of Rails but only tab completes the former.

				*rails-:Emigration* *rails-:Rmigration*
:Emigration [{pattern}]	If {pattern} is a number, find the migration for that
			particular set of digits, zero-padding if necessary.
			Otherwise, find the newest migration containing the
			given pattern.  Omitting the pattern selects the
			latest migration.  Give a numeric argument of 0 to edit
			db/seeds.rb.

				*rails-:Emodel* *rails-:Rmodel*
:Emodel [{name}]	Edit the specified or current model.

				*rails-:Espec* *rails-:Rspec*
:Espec [{name}]		Edit the given spec.  With no argument, defaults to
			editing spec/spec_helper.rb (If you want to jump to
			the spec for the given file, use |:A| instead).  This
			command is only defined if there is a spec folder in
			the root of the application.

				*rails-:Eschema* *rails-:Rschema*
:Eschema [{table}]	Edit the schema and optionally jump to the specified
			table.

				*rails-:Estylesheet* *rails-:Rstylesheet*
:Estylesheet [{name}]	Edit the stylesheet for the specified name or current
			controller.  Also supports Sass and SCSS.

				*rails-:Etask* *rails-:Rtask*
:Etask [{name}]		Edit the .rake file from lib/tasks for the specified
			name.  If no argument is given, the application
			Rakefile is edited.

				*rails-:Eunittest* *rails-:Runittest*
:Eunittest [{name}]	Edit the unit test or model spec for the specified
			name or current model.

				*rails-:Eview* *rails-:Rview*
:Eview [[{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.

Finally, one Vim feature that proves helpful in conjunction with all of the
above is |CTRL-^|.  This keystroke edits the previous file, and is helpful to
back out of any of the above commands.

RAKE						*rails-rake*

Rake integration happens through the :Rake command.

						*rails-:Rake*
:[range]Rake {targets}	Calls |:make!| {targets} (with 'makeprg' being rake,
			or `bundle exec rake` if bundler.vim is active) and
			opens the quickfix window if there were any errors.
			An argument of "-" reruns the last task.  If {targets}
			are omitted, :Rake defaults to something sensible as
			described below.  Giving a line number argument may
			affect that default.

						*rails-:Rake!*
:[range]Rake! {targets}	Called with a bang, :Rake will forgo opening the
			quickfix window.

						*rails-rake-defaults*

Generally, the default task is one that runs the test you'd expect.  For
example, if you're in a view in an RSpec application, the view spec is run,
but if it's a Test::Unit application, the functional test for the
corresponding controller is run.  The following table lists the most
interesting mappings:

File			Task ~
unit test		test:units TEST=...
functional test		test:functionals TEST=...
integration test	test:integration TEST=...
spec			spec SPEC=...
feature			cucumber FEATURE=...
model			test:units TEST=...		spec SPEC=...
controller		test:functionals TEST=...	spec SPEC=...
helper			test:functionals TEST=...	spec SPEC=...
view			test:functionals TEST=...	spec SPEC=...
fixtures		db:fixtures:load FIXTURES=...
migration		db:migrate VERSION=...
config/routes.rb	routes
db/seeds.rb		db:seed

Additionally, when :Rake is given a line number (e.g., :.Rake), the following
additional tasks can be invoked:

File			Task ~
unit test		test:units TEST=... TESTOPTS=-n...
functional test		test:functionals TEST=... TESTOPTS=-n...
integration test	test:integration TEST=... TESTOPTS=-n...
spec			spec SPEC=...:...
feature			cucumber FEATURE=...:...
controller		routes CONTROLLER=...
fixtures		db:fixtures:identify LABEL=...
migration in self.up	db:migrate:up VERSION=...
migration in self.down	db:migrate:down VERSION=...
migration elsewhere	db:migrate:redo VERSION=...
task			... (try to guess currently edited declaration)

Finally, you can override the default task with a comment like "# rake ..."
before the method pointed to by [range] or at the top of the file.

SCRIPT WRAPPERS					*rails-scripts*

The following commands are wrappers around the scripts in the script directory
of the Rails application.  Most have extra features beyond calling the script.
A limited amount of completion with <Tab> is supported.


						*rails-:Rails*
:Rails {command} [options]
			Depending on the Rails version, invoke one of
			"bin/rails {command}", "script/rails {command}", or
			"script/{command}".

						*rails-:Rscript*
:Rscript {command} [options]
			Deprecated alias for |:Rails| {command}.  Defaults to
			calling |:Rails| console.

						*rails-:Rrunner*
:[range]Rrunner [file]	Run the given file or code with rails runner and load
:Rrunner {code}		the results in to the quickfix list, using the error
			parser from the "ruby" |:compiler|.  If the file looks
			like a test, spec, or cucumber feature, the
			"rubyunit", "rspec", or "cucumber" |:compiler| will be
			used instead.  If provided, [range] is passed to the
			test runner to restrict execution to a particular
			line.  With no argument, defaults to running the test
			for the current file.

						*rails-:Rp*
:[range]Rp {code}	Use rails runner to execute "p begin {code} end" and
			echo the result.

						*rails-:Rpp*
:[range]Rpp {code}	Like :Rp, but with pp (pretty print).

						*rails-:Rgenerate*
:Rgenerate {options}	Calls rails generate {options} and loads the
			generated files into the quickfix list.  Use ! to
			surpress jumping to the first file.

						*rails-:Rdestroy*
:Rdestroy {options}	Calls rails destroy {options} and loads the destroyed
			files into the quickfix list.

						*rails-:Rserver*
:Rserver {options}	Launches rails server {options} in the background.
			On win32, this means |!start|.  Otherwise, the
			--daemon option is passed in.

						*rails-:Rserver!*
:Rserver! {options}	Kill the pid found in tmp/pids/server.pid and then
			invoke |:Rserver|.

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 part of a view to a partial, part
of a helper to another helper, or part of a model or controller to a concern.

						*rails-:Rextract*
:[range]Rextract [{controller}/]{name}
			Create a {name} partial from [range] lines (default:
			current line).  Only available in views.

:[range]Rextract {helper}
			Create a {name} helper from [range] lines (default:
			current line).  Only available in helpers.

:[range]Rextract {concern}
			Create a {name} concern from [range] lines (default:
			current line).  Only available in models and
			controllers.

If this is your file, in app/views/blog/show.html.erb: >

 1	<div>
 2	  <h2><%= @post.title %></h2>
 3	  <p><%= @post.body %></p>
 4	</div>

And you issue this command: >

	:2,3Rextract post

Your file will change to this: >

 1	<div>
 2	  <%= render 'post' %>
 3	</div>

And app/views/blog/_post.html.erb will now contain: >

 1	<h2><%= @post.title %></h2>
 2	<p><%= @post.body %></p>
<
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.
			Newer versions of Rails provide increasingly good
			support for reversible migration definitions, so this
			command is deprecated and no longer maintained.

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/.

						*rails-:Rdbext* *rails-dbext*
:Rdbext [{environment}] This command is only provided when the |dbext| plugin
			is installed.  Loads the {environment} configuration
			(defaults to $RAILS_ENV or development) from
			config/database.yml and uses it to configure dbext.
			The configuration is cached on a per application
			basis.  With dbext version 8.00 and newer, this
			command is called automatically when needed.  When
			dbext is configured, you can execute SQL directly from
			Vim: >
				:Select * from posts order by id desc
				:Update comments set author_id = 1
<
						*rails-surround*
The |surround| plugin available from vim.org enables adding and removing
"surroundings" like parentheses, quotes, and HTML tags.  Even by itself, it is
quite useful for Rails development, particularly eRuby editing.  When coupled
with this plugin, a few additional replacement surroundings are available in
eRuby files.  See the |surround| documentation for details on how to use them.
The table below uses ^ to represent the position of the surrounded text.

Key	Surrounding ~
=	<%= ^ %>
-	<% ^ -%>
#	<%# ^ %>
<C-E>	<% ^ -%>\n<% end -%>

The last surrounding is particularly useful in insert mode with the following
map in one's vimrc.  Use Alt+o to open a new line below the current one.  This
works nicely even in a terminal (where most alt/meta maps will fail) because
most terminals send <M-o> as <Esc>o anyways.
>
	imap <M-o> <Esc>o
<
One can also use the <C-E> surrounding in a plain Ruby file to append a bare
"end" on the following line.

						*rails-abolish*
Among the many features of |abolish| on vim.org is the ability to change the
inflection of the word under the cursor.  For example, one can hit crs to
change from MixedCase to snake_case.  This plugin adds two additional
inflections: crl for alternating between the singular and plural, and crt for
altering between tableize and classify.  The latter is useful in changing
constructs like BlogPost.all to current_user.blog_posts.all and vice versa.

						*rails-rspec*
The presence of a spec directory causes several additional behaviors to
activate.  :A knows about specs and will jump to them (but Test::Unit files
still get priority).  The associated controller or model of a spec is
detected, so all navigation commands should work as expected inside a spec
file.  :Rake in a spec runs just that spec, and in a model, controller, or
helper, runs the associated spec.

|:Eunittest| and |:Efunctionaltest| lead double lives, handling model/helper
and controller/mailer specs respectively.  For view specs, you can use
|:Espec|, or define your own navigation commands:
>
	Rnavcommand specview spec/views -glob=**/* -suffix=_spec.rb
<
ABBREVIATIONS				*rails-abbreviations* *rails-snippets*

Abbreviations are "snippets lite".  They may later be extracted into a
separate plugin, or removed entirely.

						*rails-:Rabbrev*
:Rabbrev		List all Rails abbreviations.

:Rabbrev {abbr} {expn} [{extra}]
			Define a new Rails abbreviation. {extra} is permitted
			if and only if {expn} ends with "(".

						*rails-:Rabbrev!*
:Rabbrev! {abbr}	Remove an abbreviation.

Rails abbreviations differ from regular abbreviations in that they only expand
after a <C-]> (see |i_CTRL-]|) or a <Tab> (if <Tab> does not work, it is
likely mapped by another plugin).  If the abbreviation ends in certain
punctuation marks, additional expansions are possible.  A few examples will
hopefully clear this up (all of the following are enabled by default in
appropriate file types).

Command				Sequence typed		Resulting text ~
Rabbrev rp( render :partial\ =>	rp(			render(:partial =>
Rabbrev rp( render :partial\ =>	rp<Tab>			render :partial =>
Rabbrev vs( validates_size_of	vs(			validates_size_of(
Rabbrev pa[ params		pa[:id]			params[:id]
Rabbrev pa[ params		pa<C-]>			params
Rabbrev pa[ params		pa.inspect		params.inspect
Rabbrev AR:: ActionRecord	AR::Base		ActiveRecord::Base

In short, ( expands on (, :: expands on . and :, and [ expands on . and [.
These trailing punctuation marks are NOT part of the final abbreviation, and
you cannot have two mappings that differ only by punctuation.

You must escape spaces in your expansion, either as "\ " or as "<Space>".  For
an abbreviation ending with "(", you may define where to insert the
parenthesis by splitting the expansion into two parts (divided by an unescaped
space).

You can also define abbreviations as a hash in |g:rails_abbreviations| or by
using |rails-projection-abbreviations|:
>
	let g:rails_abbreviations = {
		\ "AE::": "ActiveResource",
		\ "p[": "params",
		\ "rj(": ["render", "json: "]}
<
Many abbreviations are provided by default: use :Rabbrev to list them.  They
vary depending on the type of file (models have different abbreviations than
controllers).

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.

						*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*
A string literal using %Q<> or %<> delimiters will have its contents
highlighted as HTML.  This is sometimes useful when writing helpers. >
	link = %<<a href="http://www.vim.org">Vim</a>>.html_safe
<
						*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'*
Indent settings are no longer adjusted by default.  Install sleuth.vim, or try
this in your vimrc instead: >
	autocmd FileType ruby set sw=2 sts=2 et
<
					*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
<
					*rails-'includeexpr'*	*rails-'inex'*
The 'includeexpr' option is set to enable the magic described in |rails-gf|.

					*rails-'filetype'*	*rails-'ft'*
The 'filetype' is sometimes adjusted for Rails files.  Most notably, *.rxml
and *.rjs are treated as Ruby files, and files that have been falsely
identified as Mason sources are changed back to eRuby files (but only when
they are part of a Rails application).

					*rails-'completefunc'*	*rails-'cfu'*
A 'completefunc' is provided (if not already set).  It is very simple, as it
uses syntax highlighting to make its guess.  See |i_CTRL-X_CTRL-U|.

PROJECTIONS		*rails-config/projections.json* *rails-projections*

The bulk of rails.vim features support core Rails conventions and a just a
handful of popular additions (such as RSpec).  Projections let you teach
rails.vim about app specific and gem specific behavior.

There are four primary ways to define projections:

1. Globally, in |g:rails_projections|.
2. Per app, in config/projections.json.
3. Per bundled gem, in |g:rails_gem_projections| (requires bundler.vim).
4. Inside a bundled gem, in lib/rails/projections.json (requires bundler.vim).

Vim syntax looks a lot like JSON, but with funky |line-continuation|:
>
	let g:rails_projections = {
	      \ "app/uploaders/*_uploader.rb": {
	      \   "command": "uploader",
	      \   "template":
	      \     "class %SUploader < CarrierWave::Uploader::Base\nend",
	      \   "test": [
	      \     "test/unit/%s_uploader_test.rb",
	      \     "spec/models/%s_uploader_spec.rb"
	      \   ],
	      \   "keywords": "process version"
	      \ },
	      \ "features/support/*.rb": {"command": "support"},
	      \ "features/support/env.rb": {"command": "support"}}

Keys can be either literal file names or globs containing a single asterisk.
In the latter case, you can use placeholders in the values to plug in some
variant of the variable portion:

%s: original
%p: pluralized
%i: singularized
%S: camelized
%h: humanized

The full list of available options is as follows:

						*rails-projection-alternate*
"alternate" ~
	Determines the destination of the |rails-:A| command.  If this is a
	list, the first readable file will be used.
						*rails-projection-related*
"related" ~
	Determines the destination of the |rails-:R| and :.A commands.  In
	addition to the standard placeholders, %d can be used for the current
	'define' match (typically a method).
						*rails-projection-test*
"test" ~
	Determines the default test file to run with |rails-:Rrunner| and
	|rails-:Rake|.  Also serves as a default for "alternate".
						*rails-projection-task*
"task" ~
	Determines the default rake task to run.  Provide %l or %d to
	substitute the current line or 'define' match (typically a method), or
	just a bare % (like |:_%|) to substitute the current file name.  If a
	list with two tasks is provided, the first will be used when a line
	number is given, and the second when it's omitted.
						*rails-projection-compiler*
"compiler" ~
	Determines the |:compiler| plugin to use with |rails-:Rrunner|.
						*rails-projection-keywords*
"keywords" ~
	Provides a whitespace delimited list of keywords to syntax highlight.
						*rails-projection-abbreviations*
"abbreviations" ~
	Provides a dictionary of abbreviations to define.  See
	|rails-abbreviations|.  You might consider setting this in a "*"
	projection.
						*rails-projection-command*
"command" ~
	Names a navigation command to be created.  Use the same name on
	multiple projections to combine them into a single command.  Glob
	keys are used when the command is given an argument, and literal file
	keys are used when no argument is given.  See the "features/support"
	entries above for an example :Esupport that defaults to env.
						*rails-projection-affinity*
"affinity" ~
	Provide this if the root of your file name corresponds to either
	a model or controller.  The root of a helper generally corresponds to
	a controller, for example, so a "helper" projection would have an
	"affinity" of "controller".  You can also provide "collection" if it
	corresponds to a plural model (e.g., fixtures), or "resource" if it
	corresponds to a singular controller.  Providing this lets you use
	other affiliated commands without an argument, and determines the
	default if a command has no literal file name.
						*rails-projection-template*
"template" ~
	If you provide a ! after the argument to the navigation command (that
	is, :Euploader foo!, NOT :Euploader! foo), and a new file is created,
	this will be used as the body.

CONFIGURATION					*rails-configuration*

In addition to projections (described above) and the crude hammer of global
settings (described below), rails.vim provides a few different mechanisms for
configuration.

					*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! Lcd
	autocmd User Rails		map <buffer> <F9> :Rake<CR>

There used to be autocommands that fire based on the "type" or file name of
the buffer, but they have been removed.  If you still need to execute code for
certain file types only, use the bare User Rails event above and check
rails#buffer().relative() for the path relative to the Rails root.

						*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*
This file used to be sourced automatically from the root of the application,
but has been superseded by |rails-projections|.

						*rails-:Rnavcommand*
:Rnavcommand		This command has been superseded by
			|rails-projections|.

						*rails-:Rset*
:Rset			This command has been superseded by
			|rails-projections|.

GLOBAL SETTINGS					*rails-global-settings*

When all else fails, set a global.

						*g:rails_abbreviations*
Dictionary of additional abbreviations.  See |rails-abbreviations|.

This variable was formerly used to globally disable abbreviations.  Use
g:rails_no_abbreviations if you want to do that.

						*g:rails_ctags_arguments*
Additional arguments to pass to ctags from |:Ctags|.  Defaults to ignoring
JavaScript files, since ctags has a tendency to choke on those.
>
	let g:rails_ctags_arguments = ['--languages=-javascript']
<
						*g:rails_projections*  >
Defines the set of globally available projections.  See |rails-projections|.
Where possible, it is generally advisable to use |g:rails_gem_projections| or
|config/projections.json| instead.

						*g:rails_gem_projections*
This is a dictionary where the keys are gem names and the values are
projection dictionaries.  Projections are only used if the given gem is
bundled (requires bundler.vim).
>
	let g:rails_gem_projections = {
	      \ "active_model_serializers": {
	      \   "app/serializers/*_serializer.rb": {
	      \     "command": "serializer",
	      \     "affinity": "model"}},
	      \ "fabrication": {
	      \   "spec/fabricators/*_fabricator.rb": {
	      \     "command": "fabricator",
	      \     "affinity": "model",
	      \     "alternate": "app/models/%s.rb",
	      \     "related": "db/schema.rb#%p",
	      \     "test": "spec/models/%s_spec.rb",
	      \     "template": "Fabricator :%s do\nend"}}}
<
See |rails-projections|.  Generally, you should prefer these gem projections
over global projections to avoid getting a bunch of useless commands in every
single project.

Gem maintainers may also provide custom projections by placing them in
lib/rails/projections.json.

ABOUT					*rails-about* *rails-plugin-author*

The latest stable version can be found at
	http://www.vim.org/scripts/script.php?script_id=1567

Bugs can be reported and the very latest development version can be retrieved
from GitHub:
	https://github.com/tpope/vim-rails >
	git clone git://github.com/tpope/vim-rails.git
<
						*rails-license*
Copyright (c) Tim Pope.  Distributed under the same terms as Vim itself.
See |license|.

 vim:tw=78:ts=8:ft=help:norl: