123456789_123456789_123456789_123456789_123456789_

Class: Ripper

Relationships & Source Files
Namespace Children
Classes:
Extension / Inclusion / Inheritance Descendants
Subclasses:
Ripper::Lexer, Ripper::SexpBuilder, Ripper::SexpBuilderPP
Inherits: Object
Defined in: ext/ripper/lib/ripper.rb,
parse.y,
ext/ripper/lib/ripper/core.rb,
ext/ripper/lib/ripper/filter.rb,
ext/ripper/lib/ripper/lexer.rb,
ext/ripper/lib/ripper/sexp.rb

Overview

Ripper is a Ruby script parser.

You can get information from the parser with event-based style. Information such as abstract syntax trees or simple lexical analysis of the Ruby program.

Usage

Ripper provides an easy interface for parsing your program into a symbolic expression tree (or S-expression).

Understanding the output of the parser may come as a challenge, it's recommended you use PP to format the output for legibility.

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

You can see in the example above, the expression starts with :program.

From here, a method definition at :def, followed by the method's identifier :@ident. After the method's identifier comes the parentheses :paren and the method parameters under :params.

Next is the method body, starting at :bodystmt (stmt meaning statement), which contains the full definition of the method.

In our case, we're simply returning a String, so next we have the :string_literal expression.

Within our :string_literal you'll notice two @tstring_content, this is the literal part for Hello, and !. Between the two @tstring_content statements is a :string_embexpr, where embexpr is an embedded expression. Our expression consists of a local variable, or var_ref, with the identifier (@ident) of world.

Resources

Requirements

  • ruby 1.9 (support CVS HEAD only)

  • bison 1.28 or later (Other yaccs do not work)

License

Ruby License.

                                              Minero Aoki
                                      aamine@loveruby.net

i.loveruby.net

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(src, filename = "(ripper)", lineno = 1) ⇒ Ripper

Create a new Ripper object. src must be a String, an IO, or an ::Object which has #gets method.

This method does not starts parsing. See also #parse and .parse.

Class Method Details

.lex(src, filename = '-', lineno = 1)

Tokenizes the Ruby program and returns an array of an array, which is formatted like [[lineno, column], type, token].

require 'ripper'
require 'pp'

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

  
# File 'ext/ripper/lib/ripper/lexer.rb', line 42

def Ripper.lex(src, filename = '-', lineno = 1)
  Lexer.new(src, filename, lineno).lex
end

.parse(src, filename = '(ripper)', lineno = 1)

Parses the given Ruby program read from src. src must be a String or an IO or a object with a #gets method.

[ GitHub ]

  
# File 'ext/ripper/lib/ripper/core.rb', line 17

def Ripper.parse(src, filename = '(ripper)', lineno = 1)
  new(src, filename, lineno).parse
end

.sexp(src, filename = '-', lineno = 1)

EXPERIMENTAL

Parses src and create S-exp tree. Returns more readable tree rather than .sexp_raw. This method is mainly for developer use.

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

  
# File 'ext/ripper/lib/ripper/sexp.rb', line 30

def Ripper.sexp(src, filename = '-', lineno = 1)
  builder = SexpBuilderPP.new(src, filename, lineno)
  sexp = builder.parse
  sexp unless builder.error?
end

.sexp_raw(src, filename = '-', lineno = 1)

EXPERIMENTAL

Parses src and create S-exp tree. This method is mainly for developer use.

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

  
# File 'ext/ripper/lib/ripper/sexp.rb', line 56

def Ripper.sexp_raw(src, filename = '-', lineno = 1)
  builder = SexpBuilder.new(src, filename, lineno)
  sexp = builder.parse
  sexp unless builder.error?
end

.slice(src, pattern, n = 0)

EXPERIMENTAL

Parses src and return a string which was matched to pattern. pattern should be described as 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"
[ GitHub ]

  
# File 'ext/ripper/lib/ripper/lexer.rb', line 84

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)

Tokenizes the Ruby program and returns an array of strings.

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

  
# File 'ext/ripper/lib/ripper/lexer.rb', line 20

def Ripper.tokenize(src, filename = '-', lineno = 1)
  Lexer.new(src, filename, lineno).tokenize
end

Instance Attribute Details

#end_seen?Boolean (readonly)

Return true if parsed source ended by _END_.

#error?Boolean (readonly)

Return true if parsed source has errors.

#yydebugBoolean (rw)

Get yydebug.

#yydebug=(flag) (rw)

Set yydebug.

Instance Method Details

#columnInteger

Return column number of current parsing line. This number starts from 0.

#compile_error(msg) (private)

This method is called when the parser found syntax error.

[ GitHub ]

  
# File 'ext/ripper/lib/ripper/core.rb', line 55

def compile_error(msg)
end

#encodingEncoding

Return encoding of the source.

#filenameString

Return current parsing filename.

#linenoInteger

Return line number of current parsing line. This number starts from 1.

#parse

Start parsing and returns the value of the root action.

#warn(fmt, *args) (private)

This method is called when weak warning is produced by the parser. fmt and args is printf style.

[ GitHub ]

  
# File 'ext/ripper/lib/ripper/core.rb', line 46

def warn(fmt, *args)
end

#warning(fmt, *args) (private)

This method is called when strong warning is produced by the parser. fmt and args is printf style.

[ GitHub ]

  
# File 'ext/ripper/lib/ripper/core.rb', line 51

def warning(fmt, *args)
end