class Ripper

要約

Ruby プログラムのパーサです。

Ruby プログラムをテキストとして扱いたい場合、例えばソース色付けを行いたい場合は、 Ripper::Filter クラスを使うとよいでしょう。

目次

特異メソッド

• new
• parse

インスタンスメソッド

• column
• encoding
• end_seen?
• filename
• lineno
• parse
• yydebug
• yydebug=

privateメソッド

• compile_error
• warn
• warning

追加されるメソッド

• lex
• sexp
• sexp_raw
• slice
• token_match
• tokenize

定数

• EVENTS
• PARSER_EVENT_TABLE
• PARSER_EVENTS
• SCANNER_EVENT_TABLE
• SCANNER_EVENTS
• Version

特異メソッド

new(src, filename = "(ripper)", lineno = 1) -> RipperRuby 1.9.3 から[permalink][rdoc][edit]

Ripper オブジェクトを作成します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "(ripper)" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

src の解析を行うには更に Ripper#parse などの呼び出しが必要です。

[SEE_ALSO] Ripper.parse, Ripper#parse

parse(src, filename = '(ripper)', lineno = 1) -> nilRuby 1.9.3 から[permalink][rdoc][edit]

指定された文字列を解析します。常に nil を返します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "(ripper)" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

[SEE_ALSO] Ripper#parse

インスタンスメソッド

column -> Integer | nilRuby 1.9.3 から[permalink][rdoc][edit]

現在のトークンの桁番号を 0 から始まる数値で返します。

このメソッドはイベントハンドラの中でのみ意味のある値を返します。イベントハンドラの中で self.column を実行してください。

encoding -> EncodingRuby 1.9.3 から[permalink][rdoc][edit]

自身の持つ Ruby プログラムの文字エンコーディングを返します。

Ruby プログラムの解析前は Encoding::US_ASCII を返します。

end_seen? -> boolRuby 1.9.3 から[permalink][rdoc][edit]

これまでに解析した Ruby プログラムの中に __END__ が含まれていたかどうかを返します。

filename -> StringRuby 1.9.3 から[permalink][rdoc][edit]

自身の持つ Ruby プログラムのファイル名を文字列で返します。

lineno -> Integer | nilRuby 1.9.3 から[permalink][rdoc][edit]

現在のトークンの行番号を 1 から始まる数値で返します。

このメソッドはイベントハンドラの中でのみ意味のある値を返します。イベントハンドラの中で self.lineno を実行してください。

parse -> nilRuby 1.9.3 から[permalink][rdoc][edit]

自身の持つ Ruby プログラムを解析します。常に nil を返します。

サブクラスでオーバライドして使用します。Ruby プログラムの解析は行いますが、そのままでは解析結果は利用できません。サブクラスでイベントハンドラの定義や本メソッドの戻り値の追加などで対応する必要があります。

[SEE_ALSO] Ripper.parse

yydebug -> boolRuby 2.7.0 から[permalink][rdoc][edit]

yydebugの構文解析器の追跡機能が有効か無効かを返します。

yydebug=(flag)Ruby 2.7.0 から[permalink][rdoc][edit]

yydebugの構文解析器の追跡機能が有効か無効かを指定します。

[PARAM] flag:

true か false を指定します。

privateメソッド

compile_error(msg) -> nilRuby 1.9.3 から[permalink][rdoc][edit]

解析した Ruby プログラムの中にコンパイルエラーがあった場合に実行されます。

[PARAM] msg:

エラーメッセージ。

サブクラスでオーバライドして使用します。

warn(fmt, *args) -> nilRuby 1.9.3 から[permalink][rdoc][edit]

解析した Ruby プログラムの中に警告($-w が true の時だけ出力される警告)を出力するようなものがあった場合に実行されます。

[PARAM] fmt:

エラーメッセージのフォーマット文字列です。

[PARAM] args:

エラーメッセージのフォーマットされる引数です。

サブクラスでオーバライドして使用します。

引数のエラーメッセージは printf フォーマットに従って渡されます。

warning(fmt, *args) -> nilRuby 1.9.3 から[permalink][rdoc][edit]

解析した Ruby プログラムの中に重要な警告($-w が false の時だけ出力される警告)を出力するようなものがあった場合に実行されます。

[PARAM] fmt:

エラーメッセージのフォーマット文字列です。

[PARAM] args:

エラーメッセージのフォーマットされる引数です。

サブクラスでオーバライドして使用します。

引数のエラーメッセージは printf フォーマットに従って渡されます。

追加されるメソッド

lex(src, filename = '-', lineno = 1, raise_errors: false) -> [[Integer, Integer], Symbol, String, Ripper::Lexer::State]Ruby 1.9.3 から[permalink][rdoc][edit] [added by ripper/lexer]

Ruby プログラム str をトークンに分割し、そのリストを返します。ただし Ripper.tokenize と違い、トークンの種類と位置情報も付属します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "-" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

[PARAM] raise_errors:

true を指定すると、src にエラーがある場合に例外(SyntaxError)を発生させます。省略すると false になります。

[EXCEPTION] SyntaxError:

raise_errors が true で、src に文法エラーがある場合に発生します。

require 'ripper'

pp Ripper.lex("def m(a) nil end")
# => [[[1, 0], :on_kw, "def", FNAME],
#     [[1, 3], :on_sp, " ", FNAME],
#     [[1, 4], :on_ident, "m", ENDFN],
#     [[1, 5], :on_lparen, "(", BEG|LABEL],
#     [[1, 6], :on_ident, "a", ARG],
#     [[1, 7], :on_rparen, ")", ENDFN],
#     [[1, 8], :on_sp, " ", BEG],
#     [[1, 9], :on_kw, "nil", END],
#     [[1, 12], :on_sp, " ", END],
#     [[1, 13], :on_kw, "end", END]]

Ripper.lex("def req(true) end", raise_errors: true)
# ~> SyntaxError: syntax error, unexpected `true', expecting ')'

Ripper.lex は分割したトークンを詳しい情報とともに返します。返り値の配列の要素は 4 要素の配列 (概念的にはタプル) です。その内訳を以下に示します。

位置情報 (Integer,Integer)

トークンが置かれている行 (1-origin) と桁 (0-origin) の 2 要素の配列です。

種類 (Symbol)

トークンの種類が「:on_XXX」の形式のシンボルで渡されます。

トークン (String)

トークン文字列です。

ステート (Ripper::Lexer::State)

トークンの状態を表す Ripper::Lexer::State のインスタンスです。

sexp(src, filename = '-', lineno = 1) -> objectRuby 1.9.3 から[permalink][rdoc][edit] [added by ripper/sexp]

Ruby プログラム str を解析して S 式のツリーにして返します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "-" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

実行結果は、括弧の代わりに配列の要素として S 式のツリーを表現しています。

例

require 'ripper'
require 'pp'

pp Ripper.sexp("def m(a) nil end")
# => [:program,
#     [[:def,
#       [:@ident, "m", [1, 4]],
#       [:paren, [:params, [[:@ident, "a", [1, 6]]], nil, nil, nil, nil]],
#       [:bodystmt, [[:var_ref, [:@kw, "nil", [1, 9]]]], nil, nil, nil]]]]

パーサイベントは以下のような形式になります。

[:イベント名, ...]

例

[:program, ...]

スキャナイベントは以下のような形式になります。

[:@イベント名, トークン, 位置情報(行、桁の配列)]

例

[:@ident, "m", [1, 4]]

また、Ripper.sexp は Ripper.sexp_raw とは異なり、読みやすさのために stmts_add や stmts_new のような _add、_new で終わるパーサイベントを省略します。_add で終わるパーサイベントはハンドラの引数が 0 個のものが省略されます。詳しくは Ripper::PARSER_EVENTS を確認してください。

[SEE_ALSO] Ripper.sexp_raw

sexp_raw(src, filename = '-', lineno = 1) -> objectRuby 1.9.3 から[permalink][rdoc][edit] [added by ripper/sexp]

Ruby プログラム str を解析して S 式のツリーにして返します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "-" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

実行結果は、括弧の代わりに配列の要素として S 式のツリーを表現しています。

例

require 'ripper'
require 'pp'

pp Ripper.sexp_raw("def m(a) nil end")
# => [:program,
#     [:stmts_add,
#      [:stmts_new],
#      [:def,
#       [:@ident, "m", [1, 4]],
#       [:paren, [:params, [[:@ident, "a", [1, 6]]], nil, nil, nil]],
#       [:bodystmt,
#        [:stmts_add, [:stmts_new], [:var_ref, [:@kw, "nil", [1, 9]]]],
#        nil,
#        nil,
#        nil]]]]

Ripper.sexp_raw は Ripper.sexp とは異なり解析結果を加工しません。

[SEE_ALSO] Ripper.sexp

slice(src, pattern, n = 0) -> String | nilRuby 1.9.3 から[permalink][rdoc][edit] [added by ripper/lexer]

Ruby プログラム src のうち、パターン pattern の n 番目の括弧にマッチする文字列を取り出します。

マッチしない場合は nil を返します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] pattern:

取り出すプログラムのパターンを文字列で指定します。

[PARAM] n:

pattern で指定した文字列の内、n 番目の括弧の中の文字列だけが必要な時に指定します。省略すると 0 (pattern 全体)になります。

pattern は Ripper のイベント ID のリストを文字列で記述します。また pattern には Ruby の正規表現と同じメタ文字も使えます。ただし「.」は任意のトークン 1 つにマッチし、その他のメタ文字もすべて文字単位ではなくトークン単位で動作します。

使用例

require 'ripper'
p Ripper.slice(%(<<HERE\nstring\#{nil}\nHERE),
               "heredoc_beg .*? nl $(.*?) heredoc_end", 1)
    # => "string\#{nil}\n"

イベント ID は Ripper::SCANNER_EVENTS で確認できます。

token_match(src, pattern) -> Ripper::TokenPattern::MatchData | nilRuby 1.9.3 から[permalink][rdoc][edit] [added by ripper/lexer]

Ruby プログラム src に対してパターン pattern をマッチし、マッチデータを返します。

ライブラリ内部で使用します。

tokenize(src, filename = '-', lineno = 1, raise_errors: false) -> [String]Ruby 1.9.3 から[permalink][rdoc][edit] [added by ripper/lexer]

Ruby プログラム str をトークンに分割し、そのリストを返します。

[PARAM] src:

Ruby プログラムを文字列か IO オブジェクトで指定します。

[PARAM] filename:

src のファイル名を文字列で指定します。省略すると "-" になります。

[PARAM] lineno:

src の開始行番号を指定します。省略すると 1 になります。

[PARAM] raise_errors:

true を指定すると、src にエラーがある場合に例外(SyntaxError)を発生させます。省略すると false になります。

[EXCEPTION] SyntaxError:

raise_errors が true で、src に文法エラーがある場合に発生します。

require 'ripper'

p Ripper.tokenize("def m(a) nil end")
# => ["def", " ", "m", "(", "a", ")", " ", "nil", " ", "end"]

Ripper.tokenize("def req(true) end", raise_errors: true)
# ~> SyntaxError: syntax error, unexpected `true', expecting ')'

Ripper.tokenize は空白やコメントも含め、元の文字列にある文字は 1 バイトも残さずに分割します。ただし、ごく僅かな例外として、__END__ 以降の文字列は黙って捨てられます。これは現在のところ仕様と考えてください。

定数

EVENTS -> [Symbol]Ruby 1.9.3 から[permalink][rdoc][edit]

ripper の扱う全てのイベント ID (シンボル) のリストを返します。

PARSER_EVENTS -> [Symbol]Ruby 1.9.3 から[permalink][rdoc][edit]

パーサイベントのイベント ID (シンボル) のリストを返します。

PARSER_EVENT_TABLE -> {Symbol => Integer}Ruby 1.9.3 から[permalink][rdoc][edit]

パーサイベントのイベント ID (シンボル) と対応するハンドラの引数の個数のリストをハッシュで返します。

SCANNER_EVENTS -> [Symbol]Ruby 1.9.3 から[permalink][rdoc][edit]

スキャナイベントのイベント ID (シンボル) のリストを返します。

SCANNER_EVENT_TABLE -> {Symbol => Integer}Ruby 1.9.3 から[permalink][rdoc][edit]

スキャナイベントのイベント ID (シンボル) と対応するハンドラの引数の個数のリストをハッシュで返します。

Version -> StringRuby 1.9.3 から[permalink][rdoc][edit]

ripper のバージョンを文字列で返します。