類別 Ripper

Ripper 是 Ruby 腳本解析器。

您可以使用基於事件的風格從解析器中獲取信息。例如，Ruby 程式的抽象語法樹或簡單的詞法分析等信息。

用法¶ ↑

Ripper 提供了一個簡單的介面，將您的程式解析為符號表達樹（或 S-表達式）。

理解解析器的輸出可能會有挑戰性，建議您使用 PP 將輸出格式化以便閱讀。

require 'ripper'
require 'pp'

pp Ripper.sexp('def hello(world) "Hello, #{world}!"; end')
  #=> [:program,
       [[:def,
         [:@ident, "hello", [1, 4]],
         [:paren,
          [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]],
         [:bodystmt,
          [[:string_literal,
            [:string_content,
             [:@tstring_content, "Hello, ", [1, 18]],
             [:string_embexpr, [[:var_ref, [:@ident, "world", [1, 27]]]]],
             [:@tstring_content, "!", [1, 33]]]]],
          nil,
          nil,
          nil]]]]

您可以在上面的示例中看到，表達式以 :program 開始。

從這裡開始，是一個方法定義，以 :def 開始，後跟方法的識別符 :@ident。在方法的識別符之後是括號 :paren 和方法參數，位於 :params 下。

接下來是方法主體，從 :bodystmt 開始（stmt 表示語句），其中包含方法的完整定義。

在我們的例子中，我們只是返回一個字符串，所以接下來是 :string_literal 表達式。

在我們的 :string_literal 中，您會注意到兩個 @tstring_content，這是 Hello, 和 ! 的文字部分。在兩個 @tstring_content 語句之間是一個 :string_embexpr，其中 embexpr 是一個嵌入式表達式。我們的表達式包括一個本地變量，或者說是 var_ref，帶有識別符（@ident）為 world。

資源¶ ↑

Ruby Inside

需求¶ ↑

ruby 1.9（僅支援 CVS HEAD）
bison 1.28 或更新版本（其他 yacc 不適用）

許可證¶ ↑

Ruby 許可證。

常數

事件: 此陣列包含所有 ripper 事件的名稱。
EXPR_ARG: 換行符號重要，+/- 是一個運算子。
EXPR_ARG_ANY: 等同於 (EXPR_ARG | EXPR_CMDARG)
EXPR_BEG: 忽略換行符號，+/- 是一個符號。
EXPR_BEG_ANY: 等同於 (EXPR_BEG | EXPR_MID | EXPR_CLASS)
EXPR_CLASS: ‘class’ 後立即出現，沒有這裡文件。
EXPR_CMDARG: 換行符號重要，+/- 是一個運算子。
EXPR_DOT: ‘，沒有保留字。
EXPR_END: 換行符號重要，+/- 是一個運算子。
EXPR_ENDARG: 同上，且未綁定大括號。
EXPR_ENDFN: 同上，且未綁定大括號。
EXPR_END_ANY: 等同於 (EXPR_END | EXPR_ENDARG | EXPR_ENDFN)
EXPR_FITEM: 符號文字串作為 FNAME。
EXPR_FNAME: 忽略換行符號，沒有保留字。
EXPR_LABEL: 標記位，允許標籤。
EXPR_LABELED: 標記位，剛好在標籤後。
EXPR_MID: 換行符號重要，+/- 是一個運算子。
EXPR_NONE: 等同於 0
EXPR_VALUE: 等同於 EXPR_BEG
PARSER_EVENTS: 此陣列包含解析器事件的名稱。
SCANNER_EVENTS: 此陣列包含掃描器事件的名稱。
版本: Ripper 的版本

公共類方法

dedent_string(p1, p2) 點擊以切換來源

static VALUE
parser_dedent_string(VALUE self, VALUE input, VALUE width)
{
    struct parser_params *p;
    rb_parser_config_t *config;
    struct dedent_string_arg args;

    config = rb_ruby_parser_config_new(ruby_xmalloc);
    rb_parser_config_initialize(config);
    p = rb_ruby_parser_new(config);

    args.p = p;
    args.input = input;
    args.width = width;
    return rb_ensure(parser_dedent_string0, (VALUE)&args, parser_config_free, (VALUE)config);
}

lex(src, filename = '-', lineno = 1, **kw) 點擊以切換來源

將 Ruby 程式進行標記化，並返回一個格式如 [[lineno, column], type, token, state] 的陣列。 filename 參數大多被忽略。默認情況下，此方法不處理 src 中的語法錯誤，請使用 raise_errors 關鍵字將 src 中的錯誤報告為 SyntaxError。

require 'ripper'
require 'pp'

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

# File ripper/lib/ripper/lexer.rb, line 51
def Ripper.lex(src, filename = '-', lineno = 1, **kw)
  Lexer.new(src, filename, lineno).lex(**kw)
end

lex_state_name(p1) 點擊以切換來源

static VALUE
ripper_lex_state_name(VALUE self, VALUE state)
{
    struct parser_params *p;
    rb_parser_config_t *config;
    struct lex_state_name_arg args;

    config = rb_ruby_parser_config_new(ruby_xmalloc);
    rb_parser_config_initialize(config);
    p = rb_ruby_parser_new(config);

    args.p = p;
    args.state = state;

    return rb_ensure(lex_state_name0, (VALUE)&args, parser_config_free, (VALUE)config);
}

new(src, filename="(ripper)", lineno=1) → ripper 點擊以切換來源

創建一個新的 Ripper 物件。 src 必須是一個字串、一個 IO 或是具有 gets 方法的 Object。

此方法不會開始解析。參見也 Ripper#parse 和 Ripper.parse。

static VALUE
ripper_initialize(int argc, VALUE *argv, VALUE self)
{
    struct parser_params *p;
    VALUE src, fname, lineno;
    VALUE (*gets)(struct parser_params*,VALUE);
    VALUE input, sourcefile_string;
    const char *sourcefile;
    int sourceline;

    p = ripper_parser_params(self, false);
    rb_scan_args(argc, argv, "12", &src, &fname, &lineno);
    if (RB_TYPE_P(src, T_FILE)) {
        gets = ripper_lex_io_get;
    }
    else if (rb_respond_to(src, id_gets)) {
        gets = ripper_lex_get_generic;
    }
    else {
        StringValue(src);
        gets = rb_ruby_ripper_lex_get_str;
    }
    input = src;
    if (NIL_P(fname)) {
        fname = STR_NEW2("(ripper)");
        OBJ_FREEZE(fname);
    }
    else {
        StringValueCStr(fname);
        fname = rb_str_new_frozen(fname);
    }
    rb_ruby_ripper_parser_initialize(p);

    sourcefile_string = fname;
    sourcefile = RSTRING_PTR(fname);
    sourceline = NIL_P(lineno) ? 0 : NUM2INT(lineno) - 1;

    rb_ruby_parser_ripper_initialize(p, gets, input, sourcefile_string, sourcefile, sourceline);

    return Qnil;
}

parse(src, filename = '(ripper)', lineno = 1) 點擊以切換源碼

解析從 src 讀取的給定 Ruby 程式。 src 必須是一個字串、一個 IO 或是具有 gets 方法的物件。

# File ripper/lib/ripper/core.rb, line 18
def Ripper.parse(src, filename = '(ripper)', lineno = 1)
  new(src, filename, lineno).parse
end

sexp(src, filename = '-', lineno = 1, raise_errors: false) 點擊以切換源碼

實驗性功能

解析 src 並建立 S-表達式樹。返回比 Ripper.sexp_raw 更易讀的樹。此方法主要供開發者使用。通常忽略 filename 參數。默認情況下，此方法不處理 src 中的語法錯誤，對於這些情況返回 nil。使用 raise_errors 關鍵字來在 src 中的錯誤引發 SyntaxError。

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, nil, nil]],
        [:bodystmt, [[:var_ref, [:@kw, "nil", [1, 9]]]], nil, nil, nil]]]]

# File ripper/lib/ripper/sexp.rb, line 35
def Ripper.sexp(src, filename = '-', lineno = 1, raise_errors: false)
  builder = SexpBuilderPP.new(src, filename, lineno)
  sexp = builder.parse
  if builder.error?
    if raise_errors
      raise SyntaxError, builder.error
    end
  else
    sexp
  end
end

sexp_raw(src, filename = '-', lineno = 1, raise_errors: false) 點擊以切換源碼

實驗性功能

解析 src 並建立 S-表達式樹。此方法主要供開發者使用。通常忽略 filename 參數。默認情況下，此方法不處理 src 中的語法錯誤，對於這些情況返回 nil。使用 raise_errors 關鍵字來在 src 中的錯誤引發 SyntaxError。

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

# File ripper/lib/ripper/sexp.rb, line 71
def Ripper.sexp_raw(src, filename = '-', lineno = 1, raise_errors: false)
  builder = SexpBuilder.new(src, filename, lineno)
  sexp = builder.parse
  if builder.error?
    if raise_errors
      raise SyntaxError, builder.error
    end
  else
    sexp
  end
end

slice(src, pattern, n = 0) 點擊以切換源碼

實驗性功能

解析 src 並返回與 pattern 匹配的字串。 pattern 應描述為正則表達式。

require 'ripper'

p Ripper.slice('def m(a) nil end', 'ident')                   #=> "m"
p Ripper.slice('def m(a) nil end', '[ident lparen rparen]+')  #=> "m(a)"
p Ripper.slice("<<EOS\nstring\nEOS",
               'heredoc_beg nl $(tstring_content*) heredoc_end', 1)
    #=> "string\n"

# File ripper/lib/ripper/lexer.rb, line 270
def Ripper.slice(src, pattern, n = 0)
  if m = token_match(src, pattern)
  then m.string(n)
  else nil
  end
end

tokenize(src, filename = '-', lineno = 1, **kw) 點擊以切換源碼

對 Ruby 程式進行標記化，並返回一個字串數組。大多數情況下，filename 和 lineno 參數都被忽略，因為返回值只是標記化的輸入。默認情況下，此方法不處理 src 中的語法錯誤，使用 raise_errors 關鍵字來在 src 中的錯誤引發 SyntaxError。

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

# File ripper/lib/ripper/lexer.rb, line 25
def Ripper.tokenize(src, filename = '-', lineno = 1, **kw)
  Lexer.new(src, filename, lineno).tokenize(**kw)
end

公開的實例方法

column → Integer 點擊以切換源碼

返回當前解析行的列號。此號碼從 0 開始。

static VALUE
ripper_column(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);
    long col;

    if (NIL_P(rb_ruby_parser_parsing_thread(p))) return Qnil;
    col = rb_ruby_ripper_column(p);
    return LONG2NUM(col);
}

debug_output → obj 點擊以切換源碼

獲取調試輸出。

static VALUE
ripper_parser_get_debug_output(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, false);

    return rb_ruby_parser_debug_output(p);
}

debug_output = obj 點擊以切換源碼

設置調試輸出。

static VALUE
ripper_parser_set_debug_output(VALUE self, VALUE output)
{
    struct parser_params *p = ripper_parser_params(self, false);

    rb_ruby_parser_set_debug_output(p, output);
    return output;
}

encoding → encoding 點擊以切換源碼

返回源文件的编码。

static VALUE
ripper_parser_encoding(VALUE vparser)
{
    struct parser_params *p = ripper_parser_params(vparser, false);

    return rb_ruby_parser_encoding(p);
}

end_seen? → 布尔值点击切换源代码

如果解析的源代码以 +_END_+ 结束，则返回 true。

static VALUE
ripper_parser_end_seen_p(VALUE vparser)
{
    struct parser_params *p = ripper_parser_params(vparser, false);

    return RBOOL(rb_ruby_parser_end_seen_p(p));
}

error? → 布尔值点击切换源代码

如果解析的源代码存在错误，则返回 true。

static VALUE
ripper_error_p(VALUE vparser)
{
    struct parser_params *p = ripper_parser_params(vparser, false);

    return RBOOL(rb_ruby_parser_error_p(p));
}

filename → 字符串点击切换源代码

返回当前解析的文件名。

static VALUE
ripper_filename(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);

    return rb_ruby_parser_ruby_sourcefile_string(p);
}

lineno → 整数点击切换源代码

返回当前解析行的行号。行号从 1 开始计数。

static VALUE
ripper_lineno(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);

    if (NIL_P(rb_ruby_parser_parsing_thread(p))) return Qnil;
    return INT2NUM(rb_ruby_parser_ruby_sourceline(p));
}

parse 点击切换源代码

开始解析并返回根操作的值。

static VALUE
ripper_parse(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);
    VALUE result;

    if (!NIL_P(rb_ruby_parser_parsing_thread(p))) {
        if (rb_ruby_parser_parsing_thread(p) == rb_thread_current())
            rb_raise(rb_eArgError, "Ripper#parse is not reentrant");
        else
            rb_raise(rb_eArgError, "Ripper#parse is not multithread-safe");
    }
    rb_ruby_parser_set_parsing_thread(p, rb_thread_current());
    result = rb_ensure(ripper_parse0, self, ripper_ensure, self);
    RB_GC_GUARD(self);

    return result;
}

state → 整数点击切换源代码

返回当前令牌的扫描器状态。

static VALUE
ripper_state(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);

    if (NIL_P(rb_ruby_parser_parsing_thread(p))) return Qnil;
    return INT2NUM(rb_ruby_parser_lex_state(p));
}

token → 字符串点击切换源代码

返回当前令牌字符串。

static VALUE
ripper_token(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, true);
    long pos, len;

    if (NIL_P(rb_ruby_parser_parsing_thread(p))) return Qnil;
    pos = rb_ruby_ripper_column(p);
    len = rb_ruby_ripper_token_len(p);
    return rb_str_subseq(rb_ruby_ripper_lex_lastline(p), pos, len);
}

yydebug → true 或 false 点击切换源代码

获取 yydebug。

static VALUE
ripper_parser_get_yydebug(VALUE self)
{
    struct parser_params *p = ripper_parser_params(self, false);

    return RBOOL(rb_ruby_parser_get_yydebug(p));
}

yydebug = flag 点击切换源代码

设置 yydebug。

static VALUE
ripper_parser_set_yydebug(VALUE self, VALUE flag)
{
    struct parser_params *p = ripper_parser_params(self, false);

    rb_ruby_parser_set_yydebug(p, RTEST(flag));
    return flag;
}

私有实例方法

compile_error(msg) 点击切换源代码

当解析器发现语法错误时调用此方法。

# File ripper/lib/ripper/core.rb, line 63
def compile_error(msg)
end

dedent_string(p1, p2) 點擊以切換來源

static VALUE
parser_dedent_string(VALUE self, VALUE input, VALUE width)
{
    struct parser_params *p;
    rb_parser_config_t *config;
    struct dedent_string_arg args;

    config = rb_ruby_parser_config_new(ruby_xmalloc);
    rb_parser_config_initialize(config);
    p = rb_ruby_parser_new(config);

    args.p = p;
    args.input = input;
    args.width = width;
    return rb_ensure(parser_dedent_string0, (VALUE)&args, parser_config_free, (VALUE)config);
}

别名：dedent_string

warn(fmt, *args) 点击切换源代码

当解析器产生弱警告时调用此方法。 fmt 和 args 是 printf 样式的参数。

# File ripper/lib/ripper/core.rb, line 54
def warn(fmt, *args)
end

warning(fmt, *args) 点击切换源代码

当解析器产生强警告时调用此方法。 fmt 和 args 是 printf 样式的参数。

# File ripper/lib/ripper/core.rb, line 59
def warning(fmt, *args)
end