Module RDoc::ParserFactory
In: parsers/parserfactory.rb

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

Methods

alias_extension   can_parse   parse_files_matching   parser_for  

Constants

Parsers = Struct.new(:regexp, :parser)

Public Class methods

alias_extension(old_ext, new_ext)

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

[Source]

    # File parsers/parserfactory.rb, line 70
70:     def ParserFactory.alias_extension(old_ext, new_ext)
71:       parser = ParserFactory.can_parse("xxx.#{old_ext}")
72:       return false unless parser
73:       @@parsers.unshift Parsers.new(Regexp.new("\\.#{new_ext}$"), parser.parser)
74:       true
75:     end
can_parse(file_name)

Return a parser that can handle a particular extension

[Source]

    # File parsers/parserfactory.rb, line 62
62:     def ParserFactory.can_parse(file_name)
63:       @@parsers.find {|p| p.regexp.match(file_name) }
64:     end
parser_for(top_level, file_name, body, options, stats)

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

[Source]

    # File parsers/parserfactory.rb, line 80
80:     def ParserFactory.parser_for(top_level, file_name, body, options, stats)
81:       # If no extension, look for shebang
82:       if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)}
83:         shebang = $1
84:         case shebang
85:         when %r{env\s+ruby}, %r{/ruby}
86:           file_name = "dummy.rb"
87:         end
88:       end
89:       parser_description = can_parse(file_name)
90:       if parser_description
91:         parser = parser_description.parser 
92:       else
93:         parser = SimpleParser
94:       end
95: 
96:       parser.new(top_level, file_name, body, options, stats)
97:     end

Public Instance methods

parse_files_matching(regexp)

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

[Source]

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

[Validate]