Project

General

Profile

Bug #6929 ยป 0001-Documentation-for-Ripper.patch

zzak (Zachary Scott), 08/26/2012 02:34 AM

View differences:

ext/ripper/extconf.rb
3 3
require 'mkmf'
4 4
require 'rbconfig'
5 5

  
6
def main
6
def main # :nodoc:
7 7
  unless find_executable('bison')
8 8
    unless File.exist?('ripper.c') or File.exist?("#{$srcdir}/ripper.c")
9 9
      raise 'missing bison; abort'
ext/ripper/lib/ripper.rb
2 2
require 'ripper/lexer'
3 3
require 'ripper/filter'
4 4
require 'ripper/sexp'
5

  
6
# Ripper is a Ruby script parser.
7
#
8
# You can get information from the parser with event-based style.
9
# Information such as abstract syntax trees or simple lexical analysis of the
10
# Ruby program.
11
#
12
# == Usage
13
#
14
# Ripper provides an easy interface for parsing your program into a symbolic
15
# expression tree (or S-expression).
16
#
17
# Understanding the output of the parser may come as a challenge, it's
18
# recommended you use PP to format the output for legibility.
19
#
20
#   require 'ripper'
21
#   require 'pp'
22
#
23
#   pp Ripper.sexp('def hello(world); "Hello, #{world}!"; end')
24
#     #=> [:program,
25
#          [[:def,
26
#            [:@ident, "hello", [1, 4]],
27
#            [:paren,
28
#             [:params, [[:@ident, "world", [1, 10]]], nil, nil, nil, nil, nil, nil]],
29
#            [:bodystmt,
30
#             [[:void_stmt],
31
#              [:string_literal,
32
#               [:string_content,
33
#                [:@tstring_content, "Hello, ", [1, 19]],
34
#                [:string_embexpr, [[:var_ref, [:@ident, "world", [1, 28]]]]],
35
#                [:@tstring_content, "!", [1, 34]]]]],
36
#             nil,
37
#             nil,
38
#             nil]]]]
39
#
40
# You can see in the example above, the expression starts with +:program+.
41
#
42
# From here, a method definition at +:def+, followed by the method's identifier
43
# <code>:@ident</code>. After the method's identifier comes the parentheses
44
# +:paren+ and the method parameters under +:params+.
45
#
46
# Next is the method body, starting at +:bodystmt+ (+stmt+ meaning statement),
47
# which contains the full definition of the method.
48
#
49
# In our case, we're simply returning a String, so next we have the
50
# +:void_stmt+ followed by a +:string_literal+.
51
#
52
# Within our +:string_literal+ you'll notice two <code>@tstring_content</code>,
53
# this is the literal part for <code>Hello, </code> and <code>!</code>. Between
54
# the two <code>@tstring_content</code> statements is a +:string_embexpr+,
55
# where _embexpr_ is an embedded expression. Our expression consists of a local
56
# variable, or +var_ref+, with the identifier (<code>@ident</code>) of +world+.
57
#
58
# == Resources
59
#
60
# * {Ruby Inside}[http://www.rubyinside.com/using-ripper-to-see-how-ruby-is-parsing-your-code-5270.html]
61
#
62
# == Requirements
63
#
64
# * ruby 1.9 (support CVS HEAD only)
65
# * bison 1.28 or later (Other yaccs do not work)
66
#
67
# == License
68
#
69
#   Ruby License.
70
#
71
#                                                 Minero Aoki
72
#                                         aamine@loveruby.net
73
#                                       http://i.loveruby.net
74
class Ripper; end
ext/ripper/lib/ripper/core.rb
12 12

  
13 13
class Ripper
14 14

  
15
  # Parses Ruby program read from _src_.
16
  # _src_ must be a String or a IO or a object which has #gets method.
15
  # Parses the given Ruby program read from +src+.
16
  # +src+ must be a String or an IO or a object with a #gets method.
17 17
  def Ripper.parse(src, filename = '(ripper)', lineno = 1)
18 18
    new(src, filename, lineno).parse
19 19
  end
......
42 42
  end
43 43

  
44 44
  # This method is called when weak warning is produced by the parser.
45
  # _fmt_ and _args_ is printf style.
45
  # +fmt+ and +args+ is printf style.
46 46
  def warn(fmt, *args)
47 47
  end
48 48

  
49 49
  # This method is called when strong warning is produced by the parser.
50
  # _fmt_ and _args_ is printf style.
50
  # +fmt+ and +args+ is printf style.
51 51
  def warning(fmt, *args)
52 52
  end
53 53

  
ext/ripper/lib/ripper/filter.rb
13 13
class Ripper
14 14

  
15 15
  # This class handles only scanner events,
16
  # and they are dispatched in the `right' order (same with input).
16
  # which are dispatched in the 'right' order (same with input).
17 17
  class Filter
18 18

  
19
    # Creates a new Ripper::Filter instance, passes parameters +src+,
20
    # +filename+, and +lineno+ to Ripper::Lexer.new
21
    #
22
    # The lexer is for internal use only.
19 23
    def initialize(src, filename = '-', lineno = 1)
20 24
      @__lexer = Lexer.new(src, filename, lineno)
21 25
      @__line = nil
......
41 45
      @__col
42 46
    end
43 47

  
44
    # Starts parsing.  _init_ is a data accumulator.
45
    # It is passed to the next event handler (as of Enumerable#inject).
48
    # Starts the parser.
49
    # +init+ is a data accumulator and is passed to the next event handler (as
50
    # of Enumerable#inject).
46 51
    def parse(init = nil)
47 52
      data = init
48 53
      @__lexer.lex.each do |pos, event, tok|
......
57 62

  
58 63
    private
59 64

  
60
    # This method is called when some event handler have not defined.
61
    # _event_ is :on_XXX, _token_ is scanned token, _data_ is a data
62
    # accumulator.  The return value of this method is passed to the
63
    # next event handler (as of Enumerable#inject).
65
    # This method is called when some event handler is undefined.
66
    # +event+ is :on_XXX, +token+ is the scanned token, and +data+ is a data
67
    # accumulator.
68
    #
69
    # The return value of this method is passed to the next event handler (as
70
    # of Enumerable#inject).
64 71
    def on_default(event, token, data)
65 72
      data
66 73
    end
ext/ripper/lib/ripper/lexer.rb
12 12

  
13 13
class Ripper
14 14

  
15
  # Tokenizes Ruby program and returns an Array of String.
15
  # Tokenizes the Ruby program and returns an Array of String.
16 16
  def Ripper.tokenize(src, filename = '-', lineno = 1)
17 17
    Lexer.new(src, filename, lineno).tokenize
18 18
  end
19 19

  
20
  # Tokenizes Ruby program and returns an Array of Array,
21
  # which is formatted like [[lineno, column], type, token].
20
  # Tokenizes the Ruby program and returns an Array of an Array,
21
  # which is formatted like <code>[[lineno, column], type, token]</code>.
22 22
  #
23 23
  #   require 'ripper'
24 24
  #   require 'pp'
......
90 90

  
91 91
  class TokenPattern   #:nodoc:
92 92

  
93
    class Error < ::StandardError; end
94
    class CompileError < Error; end
95
    class MatchError < Error; end
93
    class Error < ::StandardError # :nodoc:
94
    end
95
    class CompileError < Error # :nodoc:
96
    end
97
    class MatchError < Error # :nodoc:
98
    end
96 99

  
97 100
    class << self
98 101
      alias compile new
......
155 158
      MAP[tok]  or raise CompileError, "unknown token: #{tok}"
156 159
    end
157 160

  
158
    class MatchData
161
    class MatchData # :nodoc:
159 162
      def initialize(tokens, match)
160 163
        @tokens = tokens
161 164
        @match = match
ext/ripper/lib/ripper/sexp.rb
15 15
  # [EXPERIMENTAL]
16 16
  # Parses +src+ and create S-exp tree.
17 17
  # Returns more readable tree rather than Ripper.sexp_raw.
18
  # This method is for mainly developer use.
18
  # This method is mainly for developer use.
19 19
  #
20 20
  #   require 'ripper'
21 21
  #   require 'pp'
......
33 33

  
34 34
  # [EXPERIMENTAL]
35 35
  # Parses +src+ and create S-exp tree.
36
  # This method is for mainly developer use.
36
  # This method is mainly for developer use.
37 37
  #
38 38
  #   require 'ripper'
39 39
  #   require 'pp'
ext/ripper/tools/generate.rb
2 2

  
3 3
require 'optparse'
4 4

  
5
def main
5
def main # :nodoc:
6 6
  mode = nil
7 7
  ids1src = nil
8 8
  ids2src = nil
......
60 60
  end
61 61
end
62 62

  
63
def usage(msg)
63
def usage(msg) # :nodoc:
64 64
  $stderr.puts msg
65 65
  $stderr.puts @parser.help
66 66
  exit false
67 67
end
68 68

  
69
def generate_eventids1(ids)
69
def generate_eventids1(ids) # :nodoc:
70 70
  buf = ""
71 71
  ids.each do |id, arity|
72 72
    buf << %Q[static ID ripper_id_#{id};\n]
......
94 94
  buf
95 95
end
96 96

  
97
def generate_eventids2_table(ids)
97
def generate_eventids2_table(ids) # :nodoc:
98 98
  buf = ""
99 99
  buf << %Q[static void\n]
100 100
  buf << %Q[ripper_init_eventids2_table(VALUE self)\n]
......
110 110
  buf
111 111
end
112 112

  
113
def read_ids1(path)
113
def read_ids1(path) # :nodoc:
114 114
  strip_locations(read_ids1_with_locations(path))
115 115
end
116 116

  
117
def strip_locations(h)
117
def strip_locations(h) # :nodoc:
118 118
  h.map {|event, list| [event, list.first[1]] }\
119 119
      .sort_by {|event, arity| event.to_s }
120 120
end
121 121

  
122
def check_arity(h)
122
def check_arity(h) # :nodoc:
123 123
  invalid = false
124 124
  h.each do |event, list|
125 125
    unless list.map {|line, arity| arity }.uniq.size == 1
......
131 131
  abort if invalid
132 132
end
133 133

  
134
def read_ids1_with_locations(path)
134
def read_ids1_with_locations(path) # :nodoc:
135 135
  h = {}
136 136
  File.open(path) {|f|
137 137
    f.each do |line|
......
145 145
  h
146 146
end
147 147

  
148
def read_ids2(path)
148
def read_ids2(path) # :nodoc:
149 149
  File.open(path) {|f|
150 150
    return f.read.scan(/ripper_id_(\w+)/).flatten.uniq.sort
151 151
  }
ext/ripper/tools/preproc.rb
2 2

  
3 3
require 'optparse'
4 4

  
5
def main
5
def main # :nodoc:
6 6
  output = nil
7 7
  parser = OptionParser.new
8 8
  parser.banner = "Usage: #{File.basename($0)} [--output=PATH] <parse.y>"
......
38 38
  end
39 39
end
40 40

  
41
def prelude(f, out)
41
def prelude(f, out) # :nodoc:
42 42
  while line = f.gets
43 43
    case line
44 44
    when %r</\*%%%\*/>
......
60 60
  end
61 61
end
62 62

  
63
def grammar(f, out)
63
def grammar(f, out) # :nodoc:
64 64
  while line = f.gets
65 65
    case line
66 66
    when %r</\*%%%\*/>
......
82 82
  end
83 83
end
84 84

  
85
def usercode(f, out)
85
def usercode(f, out) # :nodoc:
86 86
  while line = f.gets
87 87
    out << line
88 88
  end
89
-