RDoc::Parser

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

Attributes

parsers[R]

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/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) click to toggle source

Return a parser that can handle a particular extension

 
               # File rdoc/parser.rb, line 83
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) 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/parser.rb, line 102
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

  #
  # This method must return a parser.
  #
  if !parser then
    parser = RDoc::Parser::Simple
  end

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

new(top_level, file_name, content, options, stats) click to toggle source

 
               # File rdoc/parser.rb, line 131
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) click to toggle source

Record which file types this parser can understand.

 
               # File rdoc/parser.rb, line 127
def self.parse_files_matching(regexp)
  RDoc::Parser.parsers.unshift [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.