Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

In Files

  • rdoc/parsers/parserfactory.rb


Class/Module Index [+]



A parser is simple a class that implements

#initialize(file_name, body, options)



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/parsers/parsefactory"

module RDoc

  class XyzParser
    extend ParseFactory                  <<<<
    parse_files_matching /\.xyz$/        <<<<

    def initialize(file_name, body, options)

    def scan

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



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 rdoc/parsers/parserfactory.rb, line 70
def ParserFactory.alias_extension(old_ext, new_ext)
  parser = ParserFactory.can_parse("xxx.#{old_ext}")
  return false unless parser
  @@parsers.unshift Parsers.new(Regexp.new("\\.#{new_ext}$"), parser.parser)
can_parse(file_name) click to toggle source

Return a parser that can handle a particular extension

               # File rdoc/parsers/parserfactory.rb, line 62
def ParserFactory.can_parse(file_name)
  @@parsers.find {|p| p.regexp.match(file_name) }
parser_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 rdoc/parsers/parserfactory.rb, line 80
def ParserFactory.parser_for(top_level, file_name, body, options, stats)
  # If no extension, look for shebang
  if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)}
    shebang = $1
    case shebang
    when %r{env\s+ruby}, %r{/ruby}
      file_name = "dummy.rb"
  parser_description = can_parse(file_name)
  if parser_description
    parser = parser_description.parser 
    parser = SimpleParser

  parser.new(top_level, file_name, body, options, stats)

Public Instance Methods

parse_files_matching(regexp) click to toggle source

Record the fact that a particular class parses files that match a given extension

               # File rdoc/parsers/parserfactory.rb, line 56
def parse_files_matching(regexp)
  @@parsers.unshift Parsers.new(regexp, self)

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.