summaryrefslogtreecommitdiff
path: root/ext/ripper/lib
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-09-12 23:04:41 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-09-12 23:04:41 +0000
commit8f0d172f581351e89497ce5f9893b4be0f887b6d (patch)
tree677c73a013d2f023b5f926952f738cc39753e963 /ext/ripper/lib
parent857ec7118f69b140f5fd09b16fac9e28b90508f8 (diff)
* 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] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36954 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/ripper/lib')
-rw-r--r--ext/ripper/lib/ripper.rb70
-rw-r--r--ext/ripper/lib/ripper/core.rb8
-rw-r--r--ext/ripper/lib/ripper/filter.rb21
-rw-r--r--ext/ripper/lib/ripper/lexer.rb17
-rw-r--r--ext/ripper/lib/ripper/sexp.rb4
5 files changed, 100 insertions, 20 deletions
diff --git a/ext/ripper/lib/ripper.rb b/ext/ripper/lib/ripper.rb
index cb19da3..43116c7 100644
--- a/ext/ripper/lib/ripper.rb
+++ b/ext/ripper/lib/ripper.rb
@@ -2,3 +2,73 @@ require 'ripper/core'
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@loveruby.net
+# http://i.loveruby.net
+class Ripper; end
diff --git a/ext/ripper/lib/ripper/core.rb b/ext/ripper/lib/ripper/core.rb
index 35aa54d..637a72f 100644
--- a/ext/ripper/lib/ripper/core.rb
+++ b/ext/ripper/lib/ripper/core.rb
@@ -12,8 +12,8 @@ require 'ripper.so'
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 @@ class Ripper
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
diff --git a/ext/ripper/lib/ripper/filter.rb b/ext/ripper/lib/ripper/filter.rb
index 898501b..239f9f0 100644
--- a/ext/ripper/lib/ripper/filter.rb
+++ b/ext/ripper/lib/ripper/filter.rb
@@ -13,9 +13,13 @@ require 'ripper/lexer'
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 @@ class Ripper
@__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 @@ class Ripper
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
diff --git a/ext/ripper/lib/ripper/lexer.rb b/ext/ripper/lib/ripper/lexer.rb
index 5bbee39..b3b78ef 100644
--- a/ext/ripper/lib/ripper/lexer.rb
+++ b/ext/ripper/lib/ripper/lexer.rb
@@ -12,13 +12,13 @@ require 'ripper/core'
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 Ripper
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 @@ class Ripper
MAP[tok] or raise CompileError, "unknown token: #{tok}"
end
- class MatchData
+ class MatchData # :nodoc:
def initialize(tokens, match)
@tokens = tokens
@match = match
diff --git a/ext/ripper/lib/ripper/sexp.rb b/ext/ripper/lib/ripper/sexp.rb
index 08bd152..66bd691 100644
--- a/ext/ripper/lib/ripper/sexp.rb
+++ b/ext/ripper/lib/ripper/sexp.rb
@@ -15,7 +15,7 @@ class Ripper
# [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 @@ class Ripper
# [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'