ruby-changes:24902
From: zzak <ko1@a...>
Date: Thu, 13 Sep 2012 08:05:05 +0900 (JST)
Subject: [ruby-changes:24902] zzak:r36954 (trunk): * ext/ripper/lib/ripper.rb: Documentation for Ripper.
zzak 2012-09-13 08:04:41 +0900 (Thu, 13 Sep 2012) New Revision: 36954 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=36954 Log: * ext/ripper/lib/ripper.rb: Documentation for Ripper. * ext/ripper/lib/ripper/lexer.rb: ditto. * ext/ripper/lib/ripper/sexp.rb: ditto. * ext/ripper/lib/ripper/filter.rb: ditto. * ext/ripper/lib/ripper/core.rb: ditto. [Bug #6929] [ruby-core:47309] Modified files: trunk/ChangeLog trunk/ext/ripper/lib/ripper/core.rb trunk/ext/ripper/lib/ripper/filter.rb trunk/ext/ripper/lib/ripper/lexer.rb trunk/ext/ripper/lib/ripper/sexp.rb trunk/ext/ripper/lib/ripper.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 36953) +++ ChangeLog (revision 36954) @@ -1,3 +1,12 @@ +Thu Sep 13 08:00:00 2012 Zachary Scott <zzak@r...> + + * ext/ripper/lib/ripper.rb: Documentation for Ripper. + * ext/ripper/lib/ripper/lexer.rb: ditto. + * ext/ripper/lib/ripper/sexp.rb: ditto. + * ext/ripper/lib/ripper/filter.rb: ditto. + * ext/ripper/lib/ripper/core.rb: ditto. + [Bug #6929] [ruby-core:47309] + Wed Sep 12 22:59:07 2012 Nobuyoshi Nakada <nobu@r...> * vm_insnhelper.c (vm_method_missing, vm_call_method): reuse arguments Index: ext/ripper/lib/ripper/lexer.rb =================================================================== --- ext/ripper/lib/ripper/lexer.rb (revision 36953) +++ ext/ripper/lib/ripper/lexer.rb (revision 36954) @@ -12,13 +12,13 @@ class Ripper - # Tokenizes Ruby program and returns an Array of String. + # Tokenizes the Ruby program and returns an Array of String. def Ripper.tokenize(src, filename = '-', lineno = 1) Lexer.new(src, filename, lineno).tokenize end - # Tokenizes Ruby program and returns an Array of Array, - # which is formatted like [[lineno, column], type, token]. + # Tokenizes the Ruby program and returns an Array of an Array, + # which is formatted like <code>[[lineno, column], type, token]</code>. # # require 'ripper' # require 'pp' @@ -90,9 +90,12 @@ class TokenPattern #:nodoc: - class Error < ::StandardError; end - class CompileError < Error; end - class MatchError < Error; end + class Error < ::StandardError # :nodoc: + end + class CompileError < Error # :nodoc: + end + class MatchError < Error # :nodoc: + end class << self alias compile new @@ -155,7 +158,7 @@ MAP[tok] or raise CompileError, "unknown token: #{tok}" end - class MatchData + class MatchData # :nodoc: def initialize(tokens, match) @tokens = tokens @match = match Index: ext/ripper/lib/ripper/sexp.rb =================================================================== --- ext/ripper/lib/ripper/sexp.rb (revision 36953) +++ ext/ripper/lib/ripper/sexp.rb (revision 36954) @@ -15,7 +15,7 @@ # [EXPERIMENTAL] # Parses +src+ and create S-exp tree. # Returns more readable tree rather than Ripper.sexp_raw. - # This method is for mainly developer use. + # This method is mainly for developer use. # # require 'ripper' # require 'pp' @@ -33,7 +33,7 @@ # [EXPERIMENTAL] # Parses +src+ and create S-exp tree. - # This method is for mainly developer use. + # This method is mainly for developer use. # # require 'ripper' # require 'pp' Index: ext/ripper/lib/ripper/filter.rb =================================================================== --- ext/ripper/lib/ripper/filter.rb (revision 36953) +++ ext/ripper/lib/ripper/filter.rb (revision 36954) @@ -13,9 +13,13 @@ class Ripper # This class handles only scanner events, - # and they are dispatched in the `right' order (same with input). + # which are dispatched in the 'right' order (same with input). class Filter + # Creates a new Ripper::Filter instance, passes parameters +src+, + # +filename+, and +lineno+ to Ripper::Lexer.new + # + # The lexer is for internal use only. def initialize(src, filename = '-', lineno = 1) @__lexer = Lexer.new(src, filename, lineno) @__line = nil @@ -41,8 +45,9 @@ @__col end - # Starts parsing. _init_ is a data accumulator. - # It is passed to the next event handler (as of Enumerable#inject). + # Starts the parser. + # +init+ is a data accumulator and is passed to the next event handler (as + # of Enumerable#inject). def parse(init = nil) data = init @__lexer.lex.each do |pos, event, tok| @@ -57,10 +62,12 @@ private - # This method is called when some event handler have not defined. - # _event_ is :on_XXX, _token_ is scanned token, _data_ is a data - # accumulator. The return value of this method is passed to the - # next event handler (as of Enumerable#inject). + # This method is called when some event handler is undefined. + # +event+ is :on_XXX, +token+ is the scanned token, and +data+ is a data + # accumulator. + # + # The return value of this method is passed to the next event handler (as + # of Enumerable#inject). def on_default(event, token, data) data end Index: ext/ripper/lib/ripper/core.rb =================================================================== --- ext/ripper/lib/ripper/core.rb (revision 36953) +++ ext/ripper/lib/ripper/core.rb (revision 36954) @@ -12,8 +12,8 @@ class Ripper - # Parses Ruby program read from _src_. - # _src_ must be a String or a IO or a object which has #gets method. + # Parses the given Ruby program read from +src+. + # +src+ must be a String or an IO or a object with a #gets method. def Ripper.parse(src, filename = '(ripper)', lineno = 1) new(src, filename, lineno).parse end @@ -42,12 +42,12 @@ end # This method is called when weak warning is produced by the parser. - # _fmt_ and _args_ is printf style. + # +fmt+ and +args+ is printf style. def warn(fmt, *args) end # This method is called when strong warning is produced by the parser. - # _fmt_ and _args_ is printf style. + # +fmt+ and +args+ is printf style. def warning(fmt, *args) end Index: ext/ripper/lib/ripper.rb =================================================================== --- ext/ripper/lib/ripper.rb (revision 36953) +++ ext/ripper/lib/ripper.rb (revision 36954) @@ -2,3 +2,73 @@ require 'ripper/lexer' require 'ripper/filter' require 'ripper/sexp' + +# 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, +# [[:void_stmt], +# [:string_literal, +# [:string_content, +# [:@tstring_content, "Hello, ", [1, 19]], +# [:string_embexpr, [[:var_ref, [:@ident, "world", [1, 28]]]]], +# [:@tstring_content, "!", [1, 34]]]]], +# 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 +# <code>:@ident</code>. 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 +# +:void_stmt+ followed by a +:string_literal+. +# +# Within our +:string_literal+ you'll notice two <code>@tstring_content</code>, +# this is the literal part for <code>Hello, </code> and <code>!</code>. Between +# the two <code>@tstring_content</code> statements is a +:string_embexpr+, +# where _embexpr_ is an embedded expression. Our expression consists of a local +# variable, or +var_ref+, with the identifier (<code>@ident</code>) of +world+. +# +# == Resources +# +# * {Ruby Inside}[http://www.rubyinside.com/using-ripper-to-see-how-ruby-is-parsing-your-code-5270.html] +# +# == Requirements +# +# * ruby 1.9 (support CVS HEAD only) +# * bison 1.28 or later (Other yaccs do not work) +# +# == License +# +# Ruby License. +# +# Minero Aoki +# aamine@l... +# http://i.loveruby.net +class Ripper; end -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/