RSense ユーザーマニュアル

Index

[English]

1. はじめに

1.1. RSenseとは？

RSenseはEmacsやVimなどの高機能テキストエディタに特化したRubyのための開発援助ツールです。UNIXの思想に従うことで高い透明性を実現し、ユーザーが簡単に学習・拡張・修正できるように設計されています。また、コピーレフトライセンス（GPLv3+）を採用することで、自由なソフトウェアであり続けることを保証しています。

1.2. 特徴

将来的には以下の機能も利用可能になる予定です。

2. ダウンロード

RSenseのトップページからダウンロードできます。

3. インストール

3.1. 要件

3.2. Rubyのインストール

Rubyインタプリタをインストールする必要があります。

UNIX系システムを使ってる場合、パッケージマネージャを使ってインストールしてください。例えばDebian GNU/Linuxでは次のようにインストールします。

apt-get install ruby

Windowsではインストーラを使うのがよいでしょう。インストーラはRubyのダウンロードページから見つかります。RSenseはRumixを使ってテストしています。

Rubyインタプリタを起動できるようPATH環境変数を変更することを忘れないでください。大抵の場合はインストーラがやってくれます。

インストール後はコマンドプロンプトからRubyインタプリタが起動できることを確認してください。

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

3.3. JREのインストール

Java Runtime Environment 1.5あるいはそれ以降のバージョンをインストールする必要があります。SunJDKとOpenJDKをサポートしています。例えばDebian GNU/Linuxでは次のようにインストールします。

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

3.4. RSenseのインストール

基本的にはパッケージディレクトリをどこかのディレクトリにコピーするだけでインストールできます。

3.4.1. UNIX系システム

パッケージディレクトリをどこかのディレクトリにコピーしてください。大抵は~/optや/optあるいは/usr/libになるでしょう。

$ cp -av rsense-0.1 ~/opt

本節以降はRSENSE_HOME環境変数を、ここでインストールしたディレクトリに読みかえてください。

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

インストール後はbin/rsenseスクリプトが実行できることを確認してください。このスクリプトはサーバー/クライアントモデルの複雑さを隠蔽する役割を持っており、UNIX系システムではfork(2)とsetsid(2)を利用して必要な時に自動的にサーバーを起動するようになっています。そのためユーザーはサーバー/クライアントを特に意識することなく利用できます。

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

最後に~/.rsenseという名前の設定ファイルを作成します。RSenseはこの設定ファイルを読み込み、load-pathやgem-pathといった変数を取得します。etc/config.rbスクリプトはRubyのランタイムから適切なload-pathとgem-pathを取得して、この設定ファイルを作ってくれます。

$ 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

パッケージディレクトリをどこかのディレクトリにコピーしてください。大抵の場合はC:\あるいはC:\Program Filesになるでしょう。本節以降はRSENSE_HOME環境変数を、ここでインストールしたディレクトリに読みかえてください。

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

インストール後はbin\rsenseスクリプトが実行できることを確認してください。このスクリプトはサーバー/クライアントモデルの複雑さを隠蔽する役割を持っています。ただし、UNIX系システムとは違ってWindowsでは自動的にサーバーを起動する有効な手段がないため、ユーザーは手動でサーバーを起動する必要があります。サーバーを起動するには二つの方法があり、一つはコマンドプロンプト内でbin\rsenseにserverコマンドを渡して起動する方法、もう一つはRSenseをWindowsサービスとして起動する方法です。どちらの方法もRSenseの利用に先立ってサーバーあるいはサービスを起動しておく必要があります。コマンドプロンプト内で起動する場合は次のコマンドを実行します。

> ruby bin\rsense server

RSenseをWindowsサービスとして動作させるためにはまず、次のようにRubyGemsからwin32-serviceをインストールする必要があります。インストールにはgemプログラムが必要になりますが、大抵のRubyインストーラは同時にgemをインストールしてくれます。

> gem install win32-service

次にRSenseをWindowsサービスとして登録します。この作業は最初に一度だけ行います。

> ruby bin\rsense service create

サービスの削除は次のようにします。

> ruby bin\rsense service delete

登録されたサービスを起動するには、「コントロールパネル」>「コンピュータの管理」>「サービス」からRSenseを選択し「起動」するか、次のコマンドを実行します。

> ruby bin\rsense service start
Service started

netプログラムを利用することも可能です。

> net start RSense

サービスを停止するには、同様に「サービス」からRSenseを選択し「停止」するか、次のコマンドを実行します。

> ruby bin\rsense service stop
Service stopped

netプログラムを利用することも可能です。

> net stop RSense

サービスの状態は次のように確認できます。

> ruby bin\rsense service status
Running

サーバーはデフォルトでTCP/77367をリッスンします。サーバーをruby bin\rsense serverもしくはサービスで起動した後に、別のコマンドプロンプトからクライアントを実行してみましょう。

> ruby bin\rsense version
RSense 0.1

正しく動作しているのが確認できると思います。最後に%HOME%\.rsenseという名前の設定ファイルを作成します。RSenseはこの設定ファイルを読み込み、load-pathやgem-pathといった変数を取得します。HOME環境変数の値は次のコマンドで見ることができます。

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

etc/config.rbスクリプトはRubyのランタイムから適切なload-pathとgem-pathを取得して、この設定ファイルを作ってくれます。

> 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. Emacs拡張のインストール

Emacs拡張はetc/rsense.elにあります。次のコードを.emacsに追加してください。

;; $RSENSE_HOMEはRSenseをインストールしたディレクトリのフルパスに置き換えてください
(setq rsense-home "$RSENSE_HOME")
;; UNIX系システムでの例
;; (setq rsense-home "/home/tomo/opt/rsense-0.2")
;; あるいは
;; (setq rsense-home (expand-file-name "~/opt/rsense-0.2"))
;; Windowsでの例
;; (setq rsense-home "C:\\rsense-0.2")
(add-to-list 'load-path (concat rsense-home "/etc"))
(require 'rsense)

etc/rsense.elをload-pathの通ったディレクトリにコピーした場合はadd-to-listによるload-pathの登録は必要ありません。

auto-complete-modeと一緒に利用することも可能です。

3.6. Vimプラグインのインストール

Vimプラグインはetc/rsense.vimにあります。etc/rsense.vimをプラグインディレクトリにコピーしてください。UNIX系システムなら

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

で、Windowsなら

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

のようになるでしょう。詳しくはhelp 'runtimepath'を参照してください。

最後に.vimrcに次のコードを書いてください。

;; $RSENSE_HOMEはRSenseをインストールしたディレクトリに置き換えてください
let g:rsenseHome = "$RSENSE_HOME"

4. 使い方

Windowsの場合、はじめにサーバーを起動しておく必要があります。詳しくはインストールを参照してください。

4.1. Emacs

まず最初に、M-x rsense-versionでバージョン情報が表示されることを動作していることを確認してください。何も出力がない場合は、おそらく正しく動作していません。トラブルシューティングを参照してください。

4.1.1. コード補完

.あるいは::の直後にM-x rsense-completeでメソッド名や定数名を補完できます。

次のようにキーバインドを設定するとよいかもしれません。

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

auto-complete-modeを利用している場合、M-x ac-complete-rsenseでも補完できます。

次のようにキーバインドを設定するとよいかもしれません。

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

.や::を入力した直後に自動的に補完を開始したいなら、ac-sourcesにac-source-rsense-methodとac-source-rsense-contantを追加してください。

(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. 型ヘルプ

M-x rsense-type-helpでポイントしている式の型を見ることができます。

popup.elがない場合はミニバッファに表示されます。

4.1.3. 定義元ジャンプ

M-x rsense-jump-to-definitionでポイントしているメソッドや定数の定義元にジャンプすることができます。

4.1.4. Where Is

M-x rsense-where-isで編集しているクラスやメソッドの名前を確認することができます。自分が今どこを編集しているか確認するのに便利でしょう。

4.1.5. その他のコマンド

他にもプロジェクトやRSenseを操作するコマンドがあります。

rsense-version
RSenseのバージョンを表示します。
rsense-open-project
指定されたディレクトリでプロジェクトを開きます。
rsense-close-project
指定された名前のプロジェクトを閉じます。
rsense-service-start
Windowsサービスを起動します。
rsense-service-stop
Windowsサービスを停止します。
rsense-service-status
Windowsサービスの状態を表示します。
rsense-clear
現在の環境をクリアします。
rsense-exit
RSenseサーバーを終了します。

4.2. Vim

まず最初に、:RSenseVersionでバージョン情報が表示されることを確認してください。何も出力がない場合は、おそらく正しく動作していません。トラブルシューティングを参照してください。

4.2.1. コード補完

.あるいは::の直後に^X ^Uでメソッド名や定数名を補完できます。

自動的に補完するには次のコードを.vimrcに書いてVimを再起動してください。

let g:rsenseUseOmniFunc = 1

autocomplpop.vimや関連するプラグインを利用していない場合は、自動的に補完されないので^X ^Oでオムニ補完を開始してください。

4.2.2. 型ヘルプ

:RSenseTypeHelpでポイントしている式の型を見ることができます。

4.2.3. 定義元ジャンプ

:RSenseJumpToDefinitionでポイントしているメソッドや定数の定義元にジャンプすることができます。

4.2.4. Where Is

:RSenseWhereIsで編集しているクラスやメソッドの名前を確認することができます。自分が今どこを編集しているか確認するのに便利でしょう。

4.2.5. その他のコマンド

他にもプロジェクトやRSenseを操作するコマンドがあります。

:RSenseVersion
RSenseのバージョンを表示します。
:RSenseOpenProject
指定されたディレクトリでプロジェクトを開きます。
:RSenseCloseProject
指定された名前のプロジェクトを閉じます。
:RSenseServiceStart
Windowsサービスを起動します。
:RSenseServiceStop
Windowsサービスを停止します。
:RSenseServiceStatus
Windowsサービスの状態を表示します。
:RSenseClear
現在の環境をクリアします。
:RSenseExit
RSenseサーバーを終了します。

4.3. コマンドラインインターフェース

RSenseはCLI(command line interface)としてターミナルから使うこともできます。CLIには二つのフロントエンドが存在します。一つはプリミティブフロントエンドと呼ばれ、コマンドごとにRSenseのプロセスを起動します。もう一つはラッパーフロントエンドと呼ばれ、RSenseのプロセスを隠蔽してくれます。つまりラッパーフロントエンドではサーバー/クライアントモデルや初期化時間を気にする必要がないのです。通常はラッパーフロントエンドを利用します。

本節以降のコードはUNIX系システムでのみ有効です。

4.3.1. プリミティブフロントエンド

プリミティブフロントエンドの主たるコンポーネントはlib/rsense.jarです。つまりプリミティブフロントエンドを使うには次のようにjavaコマンドで起動しなくてはなりません。

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

言うまでもありませんが、クラスパスの設定は必須です。面倒くさいですか？私も面倒xです。とにかくプリミティブフロントエンドで使えるコマンドとオプションを以下に列挙します。

4.3.1.1. code-completionコマンド

このコマンドは指定されたファイルの指定された場所でコード補完を行います。ファイルは--file=オプションで指定し、場所は--location=オプションで指定します。--location=オプションは次のどれかです。

例えば、--location=123はファイルの先頭から123にあるコード補完を意味し、--location=10:8は10行目の8カラム目でのコード補完を意味し、--location=_|_はファイルで始めに_|_が見つかる場所でのコード補完を意味します。--location=オプションが省略された場合は--location=_|_が使われます。

オフセットやカラム番号の単位はバイトではなく文字です。ソースコードが非ASCII文字を含む場合は、--encoding=オプションで正しいエンコーディンを与える必要があるでしょう。利用可能なエンコーディングについてはJava Supported Encodingsを参照してください。

処理結果の各行はcompletion: <name> <qualified-name> <base-name> <kind>という形式をとります。<kind>はCLASS, MODULE, CONSTANT, METHODのいずれかです。

例:

クラスパスオプションは省略されています。

$ 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コマンド

code-completionコマンドと同じですが、式の型を出力するところが違います。code-completionコマンドで利用可能なオプションは、このコマンドでも利用可能です。

例:

$ 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コマンド

このコマンドは--file=オプションと--location=オプションで指示されたメソッド呼び出しや定数参照の定義元を検索して出力します。出力結果はlocation: <line> <filename>という形式になります。

例:

$ 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コマンド

このコマンドは--file=オプションと--lineオプションで指定された場所の直近のクラス名やメソッド名を出力します。出力結果はArrayやString#splitのように修飾された名前になります。

例:

$ 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コマンド

指定されたファイルを読み込みます。

例:

$ java -cp ... org.cx4a.rsense.Main load --file=test1.rb
4.3.1.6. scriptコマンド

このコマンドは一連のコマンドを何度も実行するのに便利です。スクリプトファイルが与えられない場合は標準入力からコマンドを読み込みます。各コマンドの終了は--end-mark=で指定されたマークで検出されます。--end-mark=オプションが省略された場合は、--end-mark=EOFが使われます。

このコマンドではいくつかの特別なコマンドが使えます。exitあるいはquitコマンドはRSenseを直ちに終了します。

例:

$ 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コマンド

現在の環境をクリアします。このコマンドは主にスクリプトで利用します。

4.3.1.8. list-projectコマンド

現在開いているプロジェクトを一覧します。--verboseオプションが与えられた場合はプロジェクトの詳細も出力します。プロジェクトも参照してください。

4.3.1.9. open-projectコマンド

指定されたディレクトリのプロジェクトを開きます。プロジェクトも参照してください。

4.3.1.10. close-projectコマンド

指定された名前のプロジェクトを閉じます。プロジェクトも参照してください。

4.3.1.11. environmentコマンド

現在のRSenseの環境を出力します。

4.3.1.12. helpコマンド

ヘルプを表示します。

4.3.1.13. versionバージョン

バージョンを表示します。

4.3.1.14. --homeオプション

RSenseのホームディレクトリを指定します。~/.rsenseがある場合は、指定する必要はないでしょう。

4.3.1.15. --debugオプション

デバッグ用メッセージを表示するためのオプションです。

4.3.1.16. --log=オプション

ログを出力するファイルを指定します。

4.3.1.17. --progress=オプション

コマンドの進捗状況を出力します。値が省略された場合は、進捗イベントを受けとるたびに即座に出力します。整数を指定すると、その秒数だけ遅延したのちに出力します。

4.3.1.18. --format=オプション

出力の形式を指定します。emacsとplainが利用できます。デフォルトはplainです。

4.3.1.19. --verboseオプション

詳細な出力を行います。

4.3.1.20. --timeオプション

コマンドの実行にかかった時間を出力します。

4.3.1.21. --encoding=オプション

ファイルのエンコーディングを指定します。エンコーディング文字列はJava Supported Encodingsのどれかである必要があります。このオプションが省略された場合は、--encoding=UTF-8が使われます。

4.3.1.22. --load-path=オプション

追加のload-pathを指定します。

4.3.1.23. --gem-path=オプション

追加のgem-pathを指定します。

4.3.1.24. --config=オプション

指定された設定ファイルを読み込みます。設定ファイルを参照してください。

4.3.1.25. --project=オプション

プロジェクトを指定します。RSenseはそのプロジェクトの環境（load-pathやgem-path）でコマンドを処理します。プロジェクトも参照してください。

4.3.1.26. --detect-project=オプション

RSenseは--fileオプションあるいはこのオプションで指定されたファイルからプロジェクトを検出して、コマンドの処理に利用します。プロジェクトも参照してください。

4.3.2. ラッパーフロントエンド

bin/rsenseはサーバー/クライアントモデルの複雑さを隠蔽するためのラッパーフロントエンドです。初期化時間なしでrsense.jarと同じように使えます。bin/rsenseは自動的にプリミティブフロントエンドをバックグラウンドデーモン（サーバー）として起動し、そのデーモンと通信しながら処理を行います[1]。

利用可能なコマンドはプリミティブフロントエンドと大体同じです。

例:

$ 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. 設定ファイル

CLIフロントエンドに設定ファイルを指定することができます。設定ファイルは一連のオプションを列挙したものです。例えば

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

は、次と同等です。

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

ラッパーフロントエンドは~/.rsenseを特別に読み込みます。このファイルはインストール時に作成したものです。

6. プロジェクト

RSenseは正しいload-pathを取得するためにプロジェクト管理を行います。各プロジェクトは次のような.rsenseという設定ファイルをプロジェクトのルートディレクトリに持っておくべきです。

name = MyProject
load-path = lib

--projectオプションが与えられた場合（上のケースなら--project=MyProject）、RSenseは設定ファイルに記述されたload-pathを使ってそのコマンドを処理します。--detect-projectオプションが与えられた場合は、.rsenseファイルを探して自動的にプロジェクトを検出します。

RSenseはload-pathとプロジェクト名の以上のことに関してはなにもケアしません。とてもシンプルです。

7. Rubyリファレンスマニュアル

この節ではRubyリファレンスマニュアル（略してrefm）をRSenseから使う方法を説明します。

まずhttp://www.ruby-lang.org/ja/man/archive/から最新のスナップショットをダウンロードしてください。次にアーカイブを展開して、例えば~/src/ruremaにコピーしてください。

$ 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

最後に次のコードを.emacsに書いてください。

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

補完ヘルプは自動的に表示されます。現在のところ補完ヘルプはEmacsでのみ対応しています。

8. 制限事項

現在のところ以下が未対応となっています。

9. トラブルシューティング

チェックリスト:

チェックリストに問題がない場合は、RSenseのjavaとrubyのプロセスをキルし、pidファイルを削除したのち、最後試してください。pidファイルはUNIX系システムの場合は$RSENSE_HOME/rsense-pidあるいは/tmp/rsense-pid、Windowsの場合は%RSENSE_HOME%\rsense-pidにあります。

それでも問題が解決できない場合は開発者に連絡してください。

10. バグレポート

RSenseのバグトラッキングシステムに新しいチケットを登録してください。

  1. Windowsの場合はあらかじめサーバーを起動しておく必要があります ↩