RDoc::ParserFactory

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

module RDoc

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

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

    def scan
      ...
    end
  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

Constants

Parsers

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)
  true
end

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) }
end

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"
    end
  end
  parser_description = can_parse(file_name)
  if parser_description
    parser = parser_description.parser 
  else
    parser = SimpleParser
  end

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

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)
end

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 see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Methods

Files

Class/Module Index

RDoc::ParserFactory

Constants

Public Class Methods

Public Instance Methods