Module: RDoc::ParserFactory

Module | RDoc::ParserFactory
In: | rdoc/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 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)

Return a parser that can handle a particular extension

[Source]

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

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

[Source]

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

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

[Source]

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

[Validate]