Class: RDoc::Parser [rdoc-2.2.1 Documentation]

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

Methods

Classes and Modules

Class RDoc::Parser::C
Class RDoc::Parser::F95
Class RDoc::Parser::PerlPOD
Class RDoc::Parser::Ruby
Class RDoc::Parser::Simple

Attributes

parsers [R]

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“

[show source]

# File lib/rdoc/parser.rb, line 53
  def self.alias_extension(old_ext, new_ext)
    old_ext = old_ext.sub(/^\.(.*)/, '\1')
    new_ext = new_ext.sub(/^\.(.*)/, '\1')

    parser = can_parse "xxx.#{old_ext}"
    return false unless parser

    RDoc::Parser.parsers.unshift [/\.#{new_ext}$/, parser]

    true
  end

can_parse (file_name)

Return a parser that can handle a particular extension

[show source]

# File lib/rdoc/parser.rb, line 78
  def self.can_parse(file_name)
    parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last

    #
    # The default parser should *NOT* parse binary files.
    #
    if parser == RDoc::Parser::Simple then
      if binary? file_name then
        return nil
      end
    end

    return parser
  end

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

[show source]

# File lib/rdoc/parser.rb, line 97
  def self.for(top_level, file_name, body, options, stats)
    # If no extension, look for shebang
    if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)} then
      shebang = $1
      case shebang
      when %r{env\s+ruby}, %r{/ruby}
        file_name = "dummy.rb"
      end
    end

    parser = can_parse file_name

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

new (top_level, file_name, content, options, stats)

[show source]

# File lib/rdoc/parser.rb, line 119
  def initialize(top_level, file_name, content, options, stats)
    @top_level = top_level
    @file_name = file_name
    @content = content
    @options = options
    @stats = stats
  end

parse_files_matching (regexp)

Record which file types this parser can understand.

[show source]

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