RSense User Manual

Index

[Japanese]

1. Introduction

1.1. What is RSense?

RSense is a Ruby development tools, which is specialized for high function text editors such as Emacs, Vim, etc. Following UNIX philosophy, RSense has a high transparency and is easy to learn, extend and fix for users. Adopting copyleft license, it also keeps being a free software.

1.2. Features

In the future, the following features will be available:

2. Downloads

You can download from RSense top page.

3. Installation

3.1. Requirements

3.2. Install Ruby

You need to install Ruby interpreter.

For UNIX-like systems, use package manager. In Debian GNU/Linux, for example:

apt-get install ruby

For Windows, you can find several installers from Ruby downloads page. We use Rumix for testing.

Remember to change PATH environment variable for Ruby interpreter to be executable. Probably the installers do it automatically.

After installation, make sure that Ruby interpreter can be executed from command prompt:

> ruby -v
ruby 1.8.7 (2009-12-24 patchlevel 248) [i386-mswin32]

3.3. Install JRE

You need to install Java Runtime Environment 1.5 or later. SunJDK and OpenJDK are supported. In Debian GNU/Linux, for example, you can install like:

$ apt-get install openjdk-6-jdk # or openjdk-6-jre

3.4. Install RSense

Basically, You just copy a package directory to some directory.

3.4.1. UNIX-like Systems

You may copy the package directory to ~/opt, /opt or /usr/lib.

$ cp -av rsense-0.1 ~/opt

For later sections, RSENSE_HOME environment variable should be read as a directory where RSense was installed.

$ echo $RSENSE_HOME
/home/tomo/opt/rsense-0.1

After installation, make sure that you can execute bin/rsnese script. This script has a role hiding a complexity about server/client model and executes server on demand automatically by using fork(2) and setsid(2) in UNIX-like systems. So there is no need to care about server/client model for users.

$ cd $RSENSE_HOME
$ chmod +x bin/rsense
$ bin/rsense version
RSense 0.1

Finally create a config file named ~/.rsense that tells RSense load-path and gem-path of Ruby runtime. A script located at etc/config.rb creates a preferred config file automatically:

$ ruby etc/config.rb > ~/.rsense
$ cat ~/.rsense
home = /home/tomo/opt/rsense-0.1
load-path = /usr/local/lib/site_ruby/1.8:/usr/local/lib/site_ruby/1.8/x86_64-linux:/usr/local/lib/site_ruby:/usr/lib/ruby/vendor_ruby/1.8:/usr/lib/ruby/vendor_ruby/1.8/x86_64-linux:/usr/lib/ruby/vendor_ruby:/usr/lib/ruby/1.8:/usr/lib/ruby/1.8/x86_64-linux:.
gem-path = /home/tomo/.gem/ruby/1.8:/usr/lib/ruby/gems/1.8

3.4.2. Windows

You may copy the package directory to C:\ or C:\Program Files. For later secions, RSENSE_HOME environment variable should be read as a directory where RSense was installed.

> echo %RSENSE_HOME%
C:\rsense-0.1
> echo %RSENSE_HOME%

After installation, make sure that you can execute bin\rsense script, which hides a complexity about server/client model. Unlike UNIX-like systems, Windows doesn't have effective ways to execute server in background automatically, so users need to execute server manually. There are two ways to execute server. One is to execute bin\rsense with passing server command in command prompt and another is to execute as Windows service. You need to execute server before using RSense in both case. To execute in command prompt, execute the folloing command:

> ruby bin\rsense server

To execute as Windows service, first of all, you need to install win32-service from RubyGems as following. gem program must be installed, but almost installers install gem program automatically.

> gem install win32-service

Then, register RSense as a Windows service.

> ruby bin\rsense service create

To delete service, do

> ruby bin\rsense service delete

To start the service, click "Start" label in "Services" or do

> ruby bin\rsense service start
Service started

You can also use net program.

> net start RSense

To stop the service, clik "Stop" label in "Services" or do

> ruby bin\rsense service stop
Service stopped

You can also use net program.

> net stop RSense

To see service status, do

> ruby bin\rsense service status
Running

Server will be listening to TCP/77367 by default. Then run client in another command prompt:

> ruby bin\rsense version
RSense 0.1

You may find it is correctly running. Finally create a config file named %HOME%\.rsense that tells RSense load-path and gem-path of Ruby runtime. If you don't set HOME environment variable, you can see its default value and set by:

> echo %HOME%
%HOME%
> ruby -e "puts ENV['HOME']"
C:/Documents And Settings/tomo
> set HOME=C:\Documents And Settings\tomo

A script located at etc\config.rb creates a preferred config file automatically:

> ruby etc\config.rb > %HOME%\.rsense
> type %HOME%\.rsense
home = C:/rsense
load-path = C:/rumix/ruby/lib/ruby/site_ruby/1.8;C:/rumix/ruby/lib/ruby/site_ruby/1.8/i386-msvcrt;C:/rumix/ruby/lib/ruby/site_ruby;C:/rumix/ruby/lib/ruby/vendor_ruby/1.8;C:/rumix/ruby/lib/ruby/vendor_ruby/1.8/i386-msvcrt;C:/rumix/ruby/lib/ruby/vendor_ruby;C:/rumix/ruby/lib/ruby/1.8;C:/rumix/ruby/lib/ruby/1.8/i386-mswin32;.
gem-path = C:/rumix/ruby/lib/ruby/gems/1.8

3.5. Install Emacs Extension

An Emacs extension for RSense is found at etc/rsense.el. Add the following code to .emacs:

;; Replace $RSENSE_HOME with the directory where RSense was installed in full path
;; Example for UNIX-like systems
;; (setq rsense-home "/home/tomo/opt/rsense-0.2")
;; or
;; (setq rsense-home (expand-file-name "~/opt/rsense-0.2"))
;; Example for Windows
;; (setq rsense-home "C:\\rsense-0.2")
(setq rsense-home "$RSENSE_HOME")
(add-to-list 'load-path (concat rsense-home "/etc"))
(require 'rsense)

There is no need to setup load-path with add-to-list if you copy etc/rsense.el to load-path directories.

You also need to install auto-complete-mode if you want to use with aut-complete-mode. See documentation for how to install.

3.6. Install Vim Plugin

An Vim plugin for RSense is found at etc/rsense.vim. Just copy etc/rsense.vim to your plugins directory. For UNIX-like systems:

$ mkdir -p ~/.vim/plugin
$ cp etc/rsense.vim ~/.vim/plugin

For Windows:

> copy etc\rsense.vim "C:\Program Files\Vim\vim72\plugin"

See help 'runtimepath' for more detail.

Then write the following code to .vimrc:

;; Replace $RSENSE_HOME with the directory where RSense was installed
let g:rsenseHome = "$RSENSE_HOME"

4. Usage

For Windows, you have to run server before anytime you use client, as we said. See installation section for details.

4.1. Emacs

First of all, you should make sure that you can see RSense version information by M-x rsense-version. If you see nothing, there is a problem probably. See trouble shooting.

4.1.1. Code Completion

You can complete method name and constant name by M-x rsense-complete after . and ::.

You may like to bind some key like:

;; Complete by C-c .
(add-hook 'ruby-mode-hook
          (lambda ()
            (local-set-key (kbd "C-c .") 'rsense-complete)))

If you have auto-complete-mode, you can also complete method name and constant name by M-x ac-complete-rsense.

You may like to bind some key like:

;; Complete by C-c .
(add-hook 'ruby-mode-hook
          (lambda ()
            (local-set-key (kbd "C-c .") 'ac-complete-rsense)))

If you want to start completion automatically after inserting . and ::, add ac-source-rsense-method and ac-source-rsense-constant to ac-sources. This is called omni completion.

(add-hook 'ruby-mode-hook
          (lambda ()
            (add-to-list 'ac-sources 'ac-source-rsense-method)
            (add-to-list 'ac-sources 'ac-source-rsense-constant)))

4.1.2. Type Help

You can infer types of an expression at point by M-x rsense-type-help

If you don't have popup.el, it shows types in minibuffer.

4.1.3. Definition Jump

You can jump to definition of a method or a constant you are pointing at by M-x rsense-jump-to-definition.

4.1.4. Where Is

You can find which class/method you are editing by M-x rsense-where-is.

4.1.5. Other Commands

There are other commands operating a project and RSense itself.

rsense-version
See RSense version.
rsense-open-project
Open a project of specified directory.
rsense-close-project
Close currently opened project.
rsense-service-start
Start Windows service.
rsense-service-stop
STop Windows service.
rsense-service-status
Show Windows service status.
rsense-clear
Clear current environment.
rsense-exit
Exit RSense server.

4.2. Vim

First of all, you should make sure that you can see RSense version information by :RSenseVersion. If you see nothing, there is a problem probably. See trouble shooting.

4.2.1. Code Completion

You can complete method name and constant name by ^X ^U after . and ::.

If you want to start completion automatically, add the following code to .vimrc and restart Vim.

let g:rsenseUseOmniFunc = 1

If you don't use autocomplpop.vim or related plugins, you need to type ^X ^O to start omni completion.

4.2.2. Type Help

You can infer types of an expression at point by :RSenseTypeHelp.

4.2.3. Definition Jump

You can jump to definition of a method or a constant you are pointing at by :RSenseJumpToDefinition.

4.2.4. Where Is

You can find which class/method you are editing by :RSenseWhereIs.

4.2.5. Other Commands

There are other commands operating a project and RSense itself.

:RSenseVersion
See RSense version.
:RSenseOpenProject
Open a project of specified directory.
:RSenseCloseProject
Close currently opened project.
:RSenseServiceStart
Start Windows service.
:RSenseServiceStop
STop Windows service.
:RSenseServiceStatus
Show Windows service status.
:RSenseClear
Clear current environment.
:RSenseExit
Exit RSense server.

4.3. Command Line Interface

You can also use RSense from terminal as CLI (command line interface). There are two CLI frontends in RSense. The first one is called primitive frontend which means only one process can run once a command. The second one is called wrapper frontend which means you don't have to care about processes. In other words, in wrapper frontend, you can execute a command regardless server/client model and initialization time. Wrapper frontend would be used in general.

Code examples for later sections are valid only for UNIX-like systems.

4.3.1. Primitive Frontend

A main component of primitive frontend is lib/rsense.jar. So if you want to use primitive frontend, you have to execute java command like:

$ java -cp lib/jruby.jar:lib/antlr-runtime-3.2.jar:lib/rsense.jar org.cx4a.rsense.Main command option...

No need to say, you have to specify a correct classpath in Java. Do you think it's boring? Me too. Anyway, in primitive frontend, you can use following commads and options.

4.3.1.1. code-completion command

This command collects completions at a specified file location. Specify file name to analyze by --file= option and --location= option. --location= option can be one of:

For example, --location=123 means completions will be collected at an offset 123 from top of file. --location=10:8 means completions will be collected at line number 10 and column 8. --location=_|_ means completions will be collected where _|_ appears. If --location= option is omitted, --location=_|_ will be used instead.

An unit of offset number and column number is not byte based but character based. If a source code contains non-ascii characters, you may have to specify an encoding by --encoding= option. An encoding string must follow Java Supported Encodings.

The each line of the result takes a form of comletion: <name> <qualified-name> <base-name> <kind>. <kind> can be one of CLASS, MODULE, CONSTANT, and METHOD.

Example:

Classpath option is omitted.

$ cat test1.rb
1
$ java -cp ... org.cx4a.rsense.Main code-completion --file=test1.rb --location=1
completion: succ Integer#succ Integer METHOD
...
$ java -cp ... org.cx4a.rsense.Main code-completion --file=test1.rb --location=1:1
completion: succ Integer#succ Integer METHOD
...
$ cat test2.rb
1_|_
$ java -cp ... org.cx4a.rsense.Main code-completion --file=test1.rb --location=_|_
completion: succ Integer#succ Integer METHOD
...
4.3.1.2. type-inference command

Same to code-completion command except this command collects types of expressions. All of options of code-completion commands can be also used in this command.

Example:

$ cat test1.rb
1
$ java -cp ... org.cx4a.rsense.Main type-inference --file=test1.rb --location=1
type: Fixnum
$ java -cp ... org.cx4a.rsense.Main type-inference --file=test1.rb --location=1:1
type: Fixnum
$ cat test2.rb
1_|_
$ java -cp ... org.cx4a.rsense.Main type-inference --file=test1.rb --location=_|_
type: Fixnum
4.3.1.3. find-definition command

This command will tell you where a definition of the method is by pointing a method call or a constant reference with --file= option and --location= option. The output will be take a form of location: <line> <filename>.

Example:

$ cat test.rb
class C
  def f() end
end
class D
  def f() end
end
D.new.f_|_
$ java -cp ... org.cx4a.rsense.Main find-definition --file=test.rb
location: 5 test.rb
4.3.1.4. where command

This commad will tell you where you are editing at by specifying file name with --file= option and line number with --line=. The output will be a qualified class name or method name like Array and String#split.

Example:

$ cat test.rb
class C
  def f
    1
  end
end
$ java -cp ... org.cx4a.rsense.Main where --file=test.rb --line=3
name: C#f
4.3.1.5. load command

Load a specified file without any outputs.

Example:

$ java -cp ... org.cx4a.rsense.Main load --file=test1.rb
4.3.1.6. script command

This command is useful for processing a series of commands again and again. If no script files are given, this command reads commands from standard input. An end of each command is detected by mark specified by --end-mark= option. If --end-mark= option is not given, --end-mark=EOF will be used instead.

Some extra commands are allowed in script mode. exit or quit commands exit RSense immediately.

Example:

$ java -cp ... org.cx4a.rsense.Main script
> type-inference
1_|_
EOF
type: Fixnum
> code-completion
1_|_
EOF
completion: succ Integer#succ Integer METHOD
...
^D
$ cat test.rsense
type-inference --test=Foo --should-be=Fixnum
1_|_
EOF

type-inference --test=Bar --should-be=String
'Hello'_|_
EOF
$ java -cp ... org.cx4a.rsense.Main script test.rsense
Foo... [OK]
Bar... [OK]
test: count=2, success=2, failure=0
4.3.1.7. clear command

Clear current environmenta. This command will be used from script usually.

4.3.1.8. list-project command

List currently opened projects. If --verbose option given, print more details about projects. See also project.

4.3.1.9. open-project command

Open a project of specified directory. See also project.

4.3.1.10. close-project command

Close specified project. See also project.

4.3.1.11. environment command

Print current RSense environment.

4.3.1.12. help command

Show help.

4.3.1.13. version command

Show version of RSense.

4.3.1.14. --home option

Specify RSense home directory. You don't need to specify this option maybe if you have ~/.rsense.

4.3.1.15. --debug option

You can see debug messages by specifying this option.

4.3.1.16. --log= option

You can keep log messages into a file by specifying this option.

4.3.1.17. --progress= option

Specifying this option with/without interval in second, RSense will print progress of the specified command.

4.3.1.18. --format= option

Specifying this option, a command output will be formatted in the specified rule. Available format are plain and emacs. Default is plain.

4.3.1.19. --verbose option

Specifying this option, command output will be verbose.

4.3.1.20. --time option

Report an elapsed time of the specified command.

4.3.1.21. --encoding= option

Specify a file encoding. An encoding string must follow Java Supported Encodings. If this option is omitted, --encoding=UTF-8 will be used instead.

4.3.1.22. --load-path= option

Specify an additional load-path.

4.3.1.23. --gem-path= option

Specify an additional gem-path.

4.3.1.24. --config= option

Specify a config file name. See configuration file.

4.3.1.25. --project= option

Specify a project. RSense will use this project environment such as load-path and gem-path for processing.

4.3.1.26. --detect-project= option

Tell RSense detect a project from --file option or from specified file. See also project.

4.3.2. Wrapper Frontend

bin/rsense is a wrapper frontend that hides a complex of server/client model. You can use it like rsense.jar without initialization time. bin/rsense automatically execute a primitive frontend as a background daemon, and starts communication with it[1].

Available commands and options are mostly same to primitive frontend's. See example.

Example:

$ bin/rsense version
RSense 0.0.1
$ cat test1.rb
def f() 1 end
$ bin/rsense type-inference --file=test1.rb # define f()
$ cat test2.rb
f_|_
$ bin/rsense type-inference --file=test2.rb # use f()
type: Fixnum

5. Configuration File

You can specify a config file for CLI frontends. A config file takes a form of series of options. For example:

$ bin/rsense type-inference --debug --log=/tmp/rsense.log --format=emacs --encoding=UTF-8 --load-path=lib --file=a.rb --location=1

is equivalent to:

$ cat config
debug
log = /tmp/rsense.log
format = emacs
encoding = UTF-8
load-path = lib
$ bin/rsense --config=config --file=a.rb --location=1

Especially, wrapper frontend will load a config file located at ~/.rsense automatically, which may be created on installation.

6. Project

RSense manages projects mainly for finding correct load-path. Every project should have a config file named .rsense at root directory of the project like:

name = MyProject
load-path = lib

If --project option is given, --project=MyProject in above case, RSense uses its load-path for processing the command. If --detect-project is given, RSense will look for .rsenes file as a project root.

RSense will not care about anything such as files, resource, and etc except for load-path and its name. It's very simple.

7. Ruby Reference Manual

This section describe how to install and use Ruby Reference Manual (refm in abbreviation) from RSense.

Go to http://www.ruby-lang.org/ja/man/archive/ and download a latest snapshot of refm. Then extract files and rename the directory to ~/src/rurema, for example.

$ cd ~/tmp
$ wget http://www.ruby-lang.org/ja/man/archive/snapshot/ruby-refm-1.9.1-dynamic-snapshot.tar.bz2
$ tar xjf ruby-refm-1.9.1-dynamic-snapshot.tar.bz2
$ mv ruby-refm-1.9.1-dynamic-snapshot ~/src/rurema

After installation, if you use Emacs, you need to change rsense-rurema-home variable to that directory.

(setq rsense-rurema-home "~/src/rurema")

Candidate help will be shown automatically. Currently, candidate help can be used only from Emacs.

8. Limitations

Currently the following features are not supported:

9. Trouble Shooting

Check list:

If there is no problem in check list, kill java and ruby processes of RSense and delete pid file located. And then try again. Pid file is located at $RSENSE_HOME/rsense-pid or /tmp/rsense-pid for UNIX-like systems, and located at %RSENSE_HOME%\rsense-pid for Windows.

Please contant me you couldn't resolve the problem.

10. Reporting Bugs

Visit RSense Bug Tracking System and create a new ticket.

  1. For Windows, you have to start server separately ↩