класс 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, поэтому дальше идёт выражение :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 или более поздней версии (другие yaccs не работают)

Лицензия

Лицензия Ruby.

Minero Aoki
aamine@loveruby.net
i.loveruby.net

Константы

EVENTS: Этот массив содержит имена всех событий ripper.
PARSER_EVENTS: Этот массив содержит имена событий парсера.
SCANNER_EVENTS: Этот массив содержит имена событий сканера.
Version: версия Ripper

Публичные методы класса

dedent_string(input, width) → Integer Показать исходный код

static VALUE
parser_dedent_string(VALUE self, VALUE input, VALUE width)
{
    int wid, col;

    StringValue(input);
    wid = NUM2UINT(width);
    col = dedent_string(input, wid);
    return INT2NUM(col);
}

ТОЛЬКО ДЛЯ ИСПОЛЬЗОВАНИЯ БИБЛИОТЕКИ RIPPER.

Удаляет до width ведущих пробелов из input, и возвращает ширину отступов после удаления.

lex(src, filename = '-', lineno = 1, **kw) Показать исходный код

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

Токенизирует программу Ruby и возвращает массив массивов, отформатированный как [[lineno, column], type, token, state]. Аргумент filename в основном игнорируется. По умолчанию этот метод не обрабатывает синтаксические ошибки в src, используйте ключевое слово raise_errors для поднятия исключения SyntaxError для ошибки в src.

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

lex_state_name(integer) → string Показать исходный код

static VALUE
ripper_lex_state_name(VALUE self, VALUE state)
{
    return rb_parser_lex_state_name(NUM2INT(state));
}

Возвращает строковое представление lex_state.

new(src, filename="(ripper)", lineno=1) → ripper Показать исходный код

static VALUE
ripper_initialize(int argc, VALUE *argv, VALUE self)
{
    struct parser_params *p;
    VALUE src, fname, lineno;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    rb_scan_args(argc, argv, "12", &src, &fname, &lineno);
    if (RB_TYPE_P(src, T_FILE)) {
        p->lex.gets = ripper_lex_io_get;
    }
    else if (rb_respond_to(src, id_gets)) {
        p->lex.gets = ripper_lex_get_generic;
    }
    else {
        StringValue(src);
        p->lex.gets = lex_get_str;
    }
    p->lex.input = src;
    p->eofp = 0;
    if (NIL_P(fname)) {
        fname = STR_NEW2("(ripper)");
        OBJ_FREEZE(fname);
    }
    else {
        StringValueCStr(fname);
        fname = rb_str_new_frozen(fname);
    }
    parser_initialize(p);

    p->ruby_sourcefile_string = fname;
    p->ruby_sourcefile = RSTRING_PTR(fname);
    p->ruby_sourceline = NIL_P(lineno) ? 0 : NUM2INT(lineno) - 1;

    return Qnil;
}

Создаёт новый объект Ripper. src должен быть String, IO или Object с методом gets.

Этот метод не запускает разбор. См. также Ripper#parse и Ripper.parse.

parse(src, filename = '(ripper)', lineno = 1) Показать исходный код

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

Парсит заданную программу Ruby, прочитанную из src. src должно быть String, IO или объектом с методом gets.

sexp(src, filename = '-', lineno = 1, raise_errors: false) Показать исходный код

# File ext/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

ЭКСПЕРИМЕНТАЛЬНО

Парсит src и создаёт дерево S-выражений. Возвращает более читаемое дерево, чем Ripper.sexp_raw. Этот метод предназначен в основном для использования разработчиками. Аргумент filename в основном игнорируется. По умолчанию этот метод не обрабатывает синтаксические ошибки в src, возвращая nil в таких случаях. Используйте ключевое слово raise_errors для поднятия исключения SyntaxError для ошибки в src.

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

sexp_raw(src, filename = '-', lineno = 1, raise_errors: false) Показать исходный код

# File ext/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

ЭКСПЕРИМЕНТАЛЬНО

Парсит src и создаёт дерево S-выражений. Этот метод предназначен в основном для использования разработчиками. Аргумент filename в основном игнорируется. По умолчанию этот метод не обрабатывает синтаксические ошибки в src, возвращая nil в таких случаях. Используйте ключевое слово raise_errors для поднятия исключения SyntaxError для ошибки в src.

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

slice(src, pattern, n = 0) Показать исходный код

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

ЭКСПЕРИМЕНТАЛЬНО

Парсит src и возвращает строку, которая соответствовала pattern. pattern должно быть описано как Regexp.

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"

tokenize(src, filename = '-', lineno = 1, **kw) Показать исходный код

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

Токенизирует программу Ruby и возвращает массив строк. Аргументы filename и lineno в основном игнорируются, так как возвращаемое значение — это просто токенизированный ввод. По умолчанию этот метод не обрабатывает синтаксические ошибки в src, используйте ключевое слово raise_errors для поднятия исключения SyntaxError для ошибки в src.

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

Публичные методы экземпляров

column → Целое Показать исходный код

static VALUE
ripper_column(VALUE self)
{
    struct parser_params *p;
    long col;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    if (NIL_P(p->parsing_thread)) return Qnil;
    col = p->lex.ptok - p->lex.pbeg;
    return LONG2NUM(col);
}

Возвращает номер столбца текущей строки разбора. Номер начинается с 0.

Также алиасируется как: column

debug_output → обьект Показать исходный код

VALUE
rb_parser_get_debug_output(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    return p->debug_output;
}

Получить отладочный вывод.

Также алиасируется как: debug_output

debug_output = обьект Показать исходный код

VALUE
rb_parser_set_debug_output(VALUE self, VALUE output)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    return p->debug_output = output;
}

Set отладочный вывод.

Также алиасируется как: debug_output=

encoding → кодировка Показать исходный код

VALUE
rb_parser_encoding(VALUE vparser)
{
    struct parser_params *p;

    TypedData_Get_Struct(vparser, struct parser_params, &parser_data_type, p);
    return rb_enc_from_encoding(p->enc);
}

Возвращает кодировку источника.

Также алиасируется как: encoding

end_seen? → Булево Показать исходный код

VALUE
rb_parser_end_seen_p(VALUE vparser)
{
    struct parser_params *p;

    TypedData_Get_Struct(vparser, struct parser_params, &parser_data_type, p);
    return p->ruby__end__seen ? Qtrue : Qfalse;
}

Возвращает true, если анализируемый источник завершается +_END_+.

Также алиасируется как: end_seen?

error? → Булево Показать исходный код

static VALUE
ripper_error_p(VALUE vparser)
{
    struct parser_params *p;

    TypedData_Get_Struct(vparser, struct parser_params, &parser_data_type, p);
    return p->error_p ? Qtrue : Qfalse;
}

Возвращает true, если в анализируемом источнике есть ошибки.

Также алиасируется как: error?

filename → Строка Показать исходный код

static VALUE
ripper_filename(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    return p->ruby_sourcefile_string;
}

Возвращает имя текущего файла разбора.

Также алиасируется как: filename

lineno → Целое Показать исходный код

static VALUE
ripper_lineno(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    if (NIL_P(p->parsing_thread)) return Qnil;
    return INT2NUM(p->ruby_sourceline);
}

Возвращает номер строки текущей строки разбора. Номер начинается с 1.

Также алиасируется как: lineno

parse Показать исходный код

static VALUE
ripper_parse(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    if (!NIL_P(p->parsing_thread)) {
        if (p->parsing_thread == rb_thread_current())
            rb_raise(rb_eArgError, "Ripper#parse is not reentrant");
        else
            rb_raise(rb_eArgError, "Ripper#parse is not multithread-safe");
    }
    p->parsing_thread = rb_thread_current();
    rb_ensure(ripper_parse0, self, ripper_ensure, self);

    return p->result;
}

Начинает разбор и возвращает значение корневого действия.

Также алиасируется как: parse

state → Целое Показать исходный код

static VALUE
ripper_state(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    if (NIL_P(p->parsing_thread)) return Qnil;
    return INT2NUM(p->lex.state);
}

Возвращает состояние сканера текущего токена.

Также алиасируется как: state

token → Строка Показать исходный код

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

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    if (!ripper_initialized_p(p)) {
        rb_raise(rb_eArgError, "method called for uninitialized object");
    }
    if (NIL_P(p->parsing_thread)) return Qnil;
    pos = p->lex.ptok - p->lex.pbeg;
    len = p->lex.pcur - p->lex.ptok;
    return rb_str_subseq(p->lex.lastline, pos, len);
}

Возвращает строку текущего токена.

Также алиасируется как: token

yydebug → true или false Показать исходный код

VALUE
rb_parser_get_yydebug(VALUE self)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    return p->debug ? Qtrue : Qfalse;
}

Получить yydebug.

Также алиасируется как: yydebug

yydebug = флаг Показать исходный код

VALUE
rb_parser_set_yydebug(VALUE self, VALUE flag)
{
    struct parser_params *p;

    TypedData_Get_Struct(self, struct parser_params, &parser_data_type, p);
    p->debug = RTEST(flag);
    return flag;
}

Set yydebug.

Также алиасируется как: yydebug=

Приватные методы экземпляров

compile_error(msg) Показать исходный код

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

Этот метод вызывается, когда парсер обнаружил синтаксическую ошибку.

dedent_string(input, width) → Целое Показать исходный код

static VALUE
parser_dedent_string(VALUE self, VALUE input, VALUE width)
{
    int wid, col;

    StringValue(input);
    wid = NUM2UINT(width);
    col = dedent_string(input, wid);
    return INT2NUM(col);
}

ИСПОЛЬЗОВАНИЕ ТОЛЬКО БИБЛИОТЕКИ RIPPER.

Удаляет до width начальных пробелов из input, и возвращает ширину удаленных пробелов.

Также алиасируется как: dedent_string, dedent_string, dedent_string

warn(fmt, *args) Показать исходный код

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

Этот метод вызывается, когда парсер генерирует слабое предупреждение. fmt и args имеют формат printf.

warning(fmt, *args) Показать исходный код

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

Этот метод вызывается, когда парсер генерирует сильное предупреждение. fmt и args имеют формат printf.

Ruby Core © 1993–2020 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.