[Top] | [Contents] | [Index] | [ ? ] |
This manual is for Rinari. A Ruby on Rails Minor Mode for Emacs.
Copyright © 2008 Eric Schulte, 2006 - 2007 Phil Hagelberg, Forrest Chang, Ryan Davis, Paul Stickne, and others
(This manual is modeled off of the very fine org-mode info documentation.)
Contents
1. Introduction | Brief summary of what Rinari is (and isn’t) | |
2. Install | Installing Rinari in your Emacs | |
3. Navigation | Jumping between files in your Rails project | |
4. Test/Behavior Driven Development | Support for Test Driven Development | |
5. Execution | Running tests, consoles, and web-servers | |
6. Miscellaneous | Leftover functions | |
7. Add Ons | Additional Emacs tools that work well with Rinari and Rails |
Links
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Rinari Is Not A Ruby IDE.
Well, OK it kind of is. Rinari is a set of Emacs Lisp functions aimed towards making Emacs (or XEmacs) into a top-notch Ruby on Rails development environment.
Currently Rinari focuses on the core functionality most everyone would use when working on a Rails applications including...
Rinari does not deal with syntax highlighting for rhtml files (or .html.erb from here on out all erb templated html files will be referred to as “rhtml” files), while all of the Rinari functions will be available from within your rhtml files you are free to chose from the many stand-alone options for editing rhtml files (see section Rhtml Setup).
Rinari development is fueled largely by the discussion on the mailing list at http://groups.google.com/group/emacs-on-rails. If you have any questions, comments, or suggestions for improving Rinari please take them to the list. The latest version of Rinari will always be available at http://github.com/eschulte/rinari/tree/master.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs
Having a working copy and working knowledge of Emacs are definite prerequisites for using Rinari.
C-ht
(meaning press the “h” key while holding down the “Ctrl”
key and then press the “t” key).
ELPA
Rinari and the Major Modes mentioned below are now available through ELPA (the “Emacs List Package Archive”) see http://tromey.com/elpa/ for more information on using ELPA to install Rinari.
Currently the version of Rinari available through ELPA does not work well with Rails3. If you want Rinari for Rails3 then download the latest from GitHub at http://github.com/eschulte/rinari. See the Basic Setup section.
Emacs Starter Kit
Available at http://github.com/technomancy/emacs-starter-kit/tree/master, the Emacs Starter Kit contains a good default Emacs setup and comes pre-bundled with many useful packages including Rinari and relevant Ruby and web development Major Modes. This can be a good way for beginners to get a jump start on their Emacs setup and for experienced Emacs users to organize their setup and see many new tools they may have missed.
Major Modes
There are a collection of Major Modes which are useful when working on a Rails project (not the least of which is Ruby-Mode!). You might want to check this Major Mode List (see section Add Ons) to ensure that you aren’t missing anything vital.
Manual Rinari Setup
2.1 Basic Setup | The minimum required to get going with Rinari | |
2.2 Rhtml Setup | Select and setup a Major mode for rhtml files | |
2.3 Optional Setup | Some additional setup options |
From here on out
The remainder of this document describes the functions and usage of
Rinari in detail. To see all of the functions provided by rinari try
C-hb
then search for rinari, or M-x rinari-<tab>
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The latest Rinari can be obtained from http://github.com/eschulte/rinari/tree/master. Select the “download” button to grab an archive of the source code, or checkout a copy using git (Note: when cloning Rinari using git it is necessary to explicitly update the submodules included with Rinari) by executing the following.
git clone git://github.com/eschulte/rinari.git cd rinari git submodule init git submodule update |
Place the base rinari directory into your Emacs lisp directory. To automatically load Rinari every time you open Emacs add these lines of code to your .emacs file:
;; Interactively Do Things (highly recommended, but not strictly required) (require 'ido) (ido-mode t) ;; Rinari (add-to-list 'load-path "~/path/to/your/elisp/rinari") (require 'rinari) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are three options for editing .rhtml files in Emacs. They are presented here in order of decreasing functionality.
2.2.1 nXhtml-Mode | a package for web development | |
2.2.2 MuMaMo-Mode | allows multiple major modes in a single buffer | |
2.2.3 rhtml-Mode | edit rhtml files without using multiple major modes |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
nXhtml-Mode is a package for web development with Emacs. For more information see http://www.emacswiki.org/cgi-bin/wiki/NxhtmlMode#toc1.
To use nXhtml-Mode mode download it from http://ourcomments.org/Emacs/nXhtml/doc/nxhtml.html. Then save the resulting directory into your elisp directory and add the following to your Emacs init file (replacing “nxml-directory” with the name of your downloaded nxml directory).
;;; nxml (HTML ERB template support) (load "~/path/to/your/elisp/nxml-directory/autostart.el") (setq nxhtml-global-minor-mode t mumamo-chunk-coloring 'submode-colored nxhtml-skip-welcome t indent-region-mode t rng-nxml-auto-validate-flag nil nxml-degraded t) (add-to-list 'auto-mode-alist '("\\.html\\.erb$" . eruby-nxhtml-mumamo-mode)) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
MuMaMo-Mode allow Multiple Major Modes in a single Emacs buffer. For more information see http://www.emacswiki.org/cgi-bin/wiki/MuMaMo.
MuMaMo-Mode comes bundled with nXhtml-Mode, so to install it download nXhtml-Mode from http://ourcomments.org/Emacs/nXhtml/doc/nxhtml.html. To use MuMaMo-Mode when editing rhtml files, save the resulting directory into your elisp directory, then add the following to your Emacs init file (replacing “nxml-directory” with the name of your downloaded nxml directory).
;; MuMaMo-Mode for rhtml files (add-to-list 'load-path "~/path/to/your/elisp/nxml-directory/util") (require 'mumamo-fun) (setq mumamo-chunk-coloring 'submode-colored) (add-to-list 'auto-mode-alist '("\\.rhtml$" . eruby-html-mumamo-mode)) (add-to-list 'auto-mode-alist '("\\.html\\.erb$" . eruby-html-mumamo-mode)) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
rhtml-mode is part of the original Rinari project. It allows editing of rhtml projects without having to use the often flaky MMM-Mode http://www.emacswiki.org/cgi-bin/wiki/MultipleModes. rhtml-mode is presented here as an alternate option to nxhtml-mode which doesn’t work for many people.
To use rhtml-mode for editing rhtml files, download the rhtml directory from http://github.com/eschulte/rhtml/tree/master and place it in your elisp directory, then include the following in you emacs .init file
;;; rhtml-mode (add-to-list 'load-path "~/path/to/your/elisp/rhtml") (require 'rhtml-mode) (add-hook 'rhtml-mode-hook (lambda () (rinari-launch))) |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
documentation
To make and install the info documentation cd into rinari
directory and run the following rake command (you must have super user
privileges to install the info documentation).
rake doc:install_info |
To make an html version of the documentation cd into the rinari
directory and run the following rake command.
rake doc:make_html |
ido-mode
While ido-mode http://www.emacswiki.org/cgi-bin/wiki/InteractivelyDoThings is not strictly required it is very helpful in combination with many of Rinari functions. Also, the Rinari functions were developed using ido-mode and may not work well in it’s absence. For more information about enabling ido-mode see the link below, or to just go ahead and try it out add the following to your emacs init file.
;; Interactively Do Things (require 'ido) (ido-mode t) |
TAGS
To have Rinari automatically update your tags-file-name
variable
to point to the tags of your current rails project, set
rinari-tags-file-name
(see section Navigation) to the path to your
tags file relative to the root of your rails applications.
(setq rinari-tags-file-name "TAGS") |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Rinari leverages the structure of Rails projects to allow immediate navigation between source files.
So for example if you are in a buffer open to foo_controller.rb,
a call to rinari-find-model
will open the foo.rb model
file. Say you are currently inside the bar method in a buffer
visiting foo_controller.rb, then calling rinari-find-test
will take you to the test_bar method in
test/functional/foo_controller_test.rb, or calling
rinari-find-view
will open app/views/foos/bar.rhtml.
All told there are currently 17 different rinari-find-* functions, which
are all bound to similar hopefully intuitive keybindings allowing you to
go anywhere from anywhere. To see the full range of rinari-find
functions along with their bindings enter a rails project, activate
rinari and call describe-bindings \H-b
. The current list is also
shown below.
C-c ; f c rinari-find-controller C-c ; f e rinari-find-environment C-c ; f f rinari-find-file-in-project C-c ; f h rinari-find-helper C-c ; f i rinari-find-migration C-c ; f j rinari-find-javascript C-c ; f l rinari-find-plugin C-c ; f m rinari-find-model C-c ; f n rinari-find-configuration C-c ; f o rinari-find-log C-c ; f p rinari-find-public C-c ; f s rinari-find-script C-c ; f t rinari-find-test C-c ; f v rinari-find-view C-c ; f w rinari-find-worker C-c ; f x rinari-find-fixture C-c ; f y rinari-find-stylesheet |
TAGS (jumping to method definitions)
Emacs (as all grownup text editors should) makes use of tags (for a
description of tags and their use see
http://ctags.sourceforge.net/whatis.html). In Emacs the
find-tag
command is bound by default to M-.
. It is often
convenient to use a different set of TAGS for every rails project.
Rinari facilitates this by automatically updating your
tags-file-name
variable whenever you enter a rails project,
through the use of the rinari-tags-file-name
variable. Just set
rianri-tags-file
to the path to your tags files relative to the
root of the rails project. For example...
(setq rinari-tags-file-name "TAGS") |
to create such a tags file using exuberant ctags (http://ctags.sourceforge.net/) try executing something like the following from the root of your rails project.
ctags-exuberant -a -e -f TAGS --tag-relative -R app lib vendor |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Rinari facilitates a development style reliant upon unit and functional
tests by providing a single command rinari-test
which executes
the unit or functional test related to the current buffer and method.
The results of the test are dumped into an emacs Compilation buffer
which allows jumping between error messages and the related source code.
Test the current ruby function. If current function is not a test, then try to jump to the related test and run it. Dump output to a compilation buffer allowing jumping between errors and source code.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some Rails tools work better inside of emacs. Specifically running rake tasks, tests, console, the web-server, and browsing your SQL database. Rinari provides functions for running all of these tools inside specialized emacs buffers.
Tab completion selection of a rake task to execute with the output dumped to a compilation buffer allowing jumping between errors and source code. With optional prefix argument allows editing of the rake command.
"Run script/console in a compilation buffer, with command history and links between errors and source code. Use a prefix argument to edit command line options."
Browse the application’s database. Looks up login information from your conf/database.sql file.
Run script/server. Dump output to a compilation buffer allowing jumping between errors and source code.
Test the current ruby function. If current function is not a test, then try to jump to the related test using ‘rinari-find-test’. Dump output to a compilation buffer allowing jumping between errors and source code.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Miscellaneous functions...
Search through the rails project using ‘rgrep’ for a string or ‘regexp’. With optional prefix argument just run ‘rgrep’.
Insert an erb skeleton at point, with optional prefix argument don’t include an ’=’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Previous versions of both emacs-rails mode, and Rinari were very feature rich, but bloated and cumbersome. To maintain a small, clean, reliable, functional, and hackable core Rinari will shun much of the “bells and whistles” type functionality. However that is not to say that these extra goodies might not be useful.
This page should serve as marshaling point for links to some other tools/packages that work well with Rinari and Rails in general. If you have any ideas for additions to this list, or for new Rinari features please let us know at http://groups.google.com/group/emacs-on-rails.
Essential Major Modes for working with Rails
/misc
directory
of your ruby distribution and at
http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/misc/
Other Tools
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Saleem Ansari on January 3, 2013 using texi2html 1.82.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ Up ] | Up | Up section | 1.2 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated by Saleem Ansari on January 3, 2013 using texi2html 1.82.