[Top] [Contents] [Index] [ ? ]

Rinari

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

Links


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Introduction

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] [ ? ]

2. Install

Emacs

Having a working copy and working knowledge of Emacs are definite prerequisites for using Rinari.

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

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] [ ? ]

2.1 Basic Setup

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] [ ? ]

2.2 Rhtml Setup

There are three options for editing .rhtml files in Emacs. They are presented here in order of decreasing functionality.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.1 nXhtml-Mode

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] [ ? ]

2.2.2 MuMaMo-Mode

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] [ ? ]

2.2.3 rhtml-Mode

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] [ ? ]

2.3 Optional Setup

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] [ ? ]

3. Navigation

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] [ ? ]

4. Test/Behavior Driven Development

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.

Function: rinari-test

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] [ ? ]

5. Execution

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.

Function: rinari-rake

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.

Function: rinari-console

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

Function: rinari-sql

Browse the application’s database. Looks up login information from your conf/database.sql file.

Function: rinari-web-server

Run script/server. Dump output to a compilation buffer allowing jumping between errors and source code.

Function: rinari-test

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] [ ? ]

6. Miscellaneous

Miscellaneous functions...

Function: rinari-rgrep

Search through the rails project using ‘rgrep’ for a string or ‘regexp’. With optional prefix argument just run ‘rgrep’.

Function: rinari-insert-erb-skeleton

Insert an erb skeleton at point, with optional prefix argument don’t include an ’=’.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Add Ons

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

Other Tools


[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

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.