lib/rdoc/parser.rb

   1 require 'rdoc'
   2 require 'rdoc/code_objects'
   3 require 'rdoc/markup/preprocess'
   4 require 'rdoc/stats'
   5
   6 ##
   7 # A parser is simple a class that implements
   8 #
   9 #   #initialize(file_name, body, options)
  10 #
  11 # and
  12 #
  13 #   #scan
  14 #
  15 # The initialize method takes a file name to be used, the body of the file,
  16 # and an RDoc::Options object. The scan method is then called to return an
  17 # appropriately parsed TopLevel code object.
  18 #
  19 # The ParseFactory is used to redirect to the correct parser given a
  20 # filename extension. This magic works because individual parsers have to
  21 # register themselves with us as they are loaded in. The do this using the
  22 # following incantation
  23 #
  24 #   require "rdoc/parser"
  25 #
  26 #   class RDoc::Parser::Xyz < RDoc::Parser
  27 #     parse_files_matching /\.xyz$/ # <<<<
  28 #
  29 #     def initialize(file_name, body, options)
  30 #       ...
  31 #     end
  32 #
  33 #     def scan
  34 #       ...
  35 #     end
  36 #   end
  37 #
  38 # Just to make life interesting, if we suspect a plain text file, we also
  39 # look for a shebang line just in case it's a potential shell script
  40
  41 class RDoc::Parser
  42
  43   @parsers = []
  44
  45   class << self
  46     attr_reader :parsers
  47   end
  48
  49   ##
  50   # Alias an extension to another extension. After this call, files ending
  51   # "new_ext" will be parsed using the same parser as "old_ext"
  52
  53   def self.alias_extension(old_ext, new_ext)
  54     old_ext = old_ext.sub(/^\.(.*)/, '\1')
  55     new_ext = new_ext.sub(/^\.(.*)/, '\1')
  56
  57     parser = can_parse "xxx.#{old_ext}"
  58     return false unless parser
  59
  60     RDoc::Parser.parsers.unshift [/\.#{new_ext}$/, parser]
  61
  62     true
  63   end
  64
  65   ##
  66   # Return a parser that can handle a particular extension
  67
  68   def self.can_parse(file_name)
  69     RDoc::Parser.parsers.find { |regexp, parser| regexp =~ file_name }.last
  70   end
  71
  72   ##
  73   # Find the correct parser for a particular file name. Return a SimpleParser
  74   # for ones that we don't know
  75
  76   def self.for(top_level, file_name, body, options, stats)
  77     # If no extension, look for shebang
  78     if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)} then
  79       shebang = $1
  80       case shebang
  81       when %r{env\s+ruby}, %r{/ruby}
  82         file_name = "dummy.rb"
  83       end
  84     end
  85
  86     parser = can_parse file_name
  87
  88     parser.new top_level, file_name, body, options, stats
  89   end
  90
  91   ##
  92   # Record which file types this parser can understand.
  93
  94   def self.parse_files_matching(regexp)
  95     RDoc::Parser.parsers.unshift [regexp, self]
  96   end
  97
  98   def initialize(top_level, file_name, content, options, stats)
  99     @top_level = top_level
 100     @file_name = file_name
 101     @content = content
 102     @options = options
 103     @stats = stats
 104   end
 105
 106 end
 107
 108 require 'rdoc/parser/simple'
 109