RDoc::Parser

A parser is simple a class that implements

  #initialize(file_name, body, options)

and

  #scan

The initialize method takes a file name to be used, the body of the file, and an RDoc::Options object. The scan method is then called to return an appropriately parsed TopLevel code object.

The ParseFactory is used to redirect to the correct parser given a filename extension. This magic works because individual parsers have to register themselves with us as they are loaded in. The do this using the following incantation

  require "rdoc/parser"

  class RDoc::Parser::Xyz < RDoc::Parser
    parse_files_matching /\.xyz$/ # <<<<

    def initialize(file_name, body, options)
      ...
    end

    def scan
      ...
    end
  end

Just to make life interesting, if we suspect a plain text file, we also look for a shebang line just in case it’s a potential shell script

Attributes

parsers[R]

Public Class Methods

alias_extension(old_ext, new_ext) click to toggle source

Alias an extension to another extension. After this call, files ending “new_ext“ will be parsed using the same parser as “old_ext“

    # File lib/rdoc/parser.rb, line 53
53:   def self.alias_extension(old_ext, new_ext)
54:     old_ext = old_ext.sub(/^\.(.*)/, '\1')
55:     new_ext = new_ext.sub(/^\.(.*)/, '\1')
56: 
57:     parser = can_parse "xxx.#{old_ext}"
58:     return false unless parser
59: 
60:     RDoc::Parser.parsers.unshift [/\.#{new_ext}$/, parser]
61: 
62:     true
63:   end

binary?(file) click to toggle source

Determines if the file is a “binary” file which basically means it has content that an RDoc parser shouldn’t try to consume.

    # File lib/rdoc/parser.rb, line 79
79:   def self.binary?(file)
80:     s = File.read(file, 1024) or return false
81:     set_encoding(s)
82: 
83:     if s[0, 2] == Marshal.dump('')[0, 2] then
84:       true
85:     elsif file =~ /erb\.rb$/ then
86:       false
87:     elsif s.scan(/<%|%>/).length >= 4 || s.index("\x00") then
88:       true
89:     elsif 0.respond_to? :fdiv then
90:       s.count("^ -~\t\r\n").fdiv(s.size) > 0.3
91:     else # HACK 1.8.6
92:       (s.count("^ -~\t\r\n").to_f / s.size) > 0.3
93:     end
94:   end

can_parse(file_name) click to toggle source

Return a parser that can handle a particular extension

     # File lib/rdoc/parser.rb, line 111
111:   def self.can_parse(file_name)
112:     parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last
113: 
114:     # HACK Selenium hides a jar file using a .txt extension
115:     return if parser == RDoc::Parser::Simple and zip? file_name
116: 
117:     # The default parser must not parse binary files
118:     ext_name = File.extname file_name
119:     return parser if ext_name.empty?
120:     return if parser == RDoc::Parser::Simple and ext_name !~ /txt|rdoc/
121: 
122:     parser
123:   end

for(top_level, file_name, body, options, stats) click to toggle source

Find the correct parser for a particular file name. Return a SimpleParser for ones that we don’t know

     # File lib/rdoc/parser.rb, line 129
129:   def self.for(top_level, file_name, body, options, stats)
130:     return if binary? file_name
131: 
132:     # If no extension, look for shebang
133:     if file_name !~ /\.\w+$/ && body =~ %{\A#!(.+)} then
134:       shebang = $1
135:       case shebang
136:       when %{env\s+ruby}, %{/ruby}
137:         file_name = "dummy.rb"
138:       end
139:     end
140: 
141:     parser = can_parse file_name
142: 
143:     return unless parser
144: 
145:     parser.new top_level, file_name, body, options, stats
146:   end

new(top_level, file_name, content, options, stats) click to toggle source

     # File lib/rdoc/parser.rb, line 157
157:   def initialize(top_level, file_name, content, options, stats)
158:     @top_level = top_level
159:     @file_name = file_name
160:     @content = content
161:     @options = options
162:     @stats = stats
163:   end

parse_files_matching(regexp) click to toggle source

Record which file types this parser can understand.

It is ok to call this multiple times.

     # File lib/rdoc/parser.rb, line 153
153:   def self.parse_files_matching(regexp)
154:     RDoc::Parser.parsers.unshift [regexp, self]
155:   end

set_encoding(string) click to toggle source

    # File lib/rdoc/parser.rb, line 65
65:   def self.set_encoding(string)
66:     if defined? Encoding then
67:       if /coding[=:]\s*([^\s;]+)/ =~ string[%\A(?:#!.*\n)?.*\n"]
68:         if enc = ::Encoding.find($1)
69:           string.force_encoding(enc)
70:         end
71:       end
72:     end
73:   end

zip?(file) click to toggle source

Checks if file is a zip file in disguise. Signatures from www.garykessler.net/library/file_sigs.html

     # File lib/rdoc/parser.rb, line 100
100:   def self.zip? file
101:     zip_signature = File.read file, 4
102: 
103:     zip_signature == "PK\x03\x04" or
104:       zip_signature == "PK\x05\x06" or
105:       zip_signature == "PK\x07\x08"
106:   end

Home Classes Methods

In Files

Parent

Namespace

Methods

Files

Class Index

RDoc::Parser

Attributes

Public Class Methods