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
A Hash that maps file extensions regular expressions to parsers that will consume them.
Use parse_files_matching to register a parser’s file extensions.
Alias an extension to another extension. After this call, files ending “new_ext” will be parsed using the same parser as “old_ext”
# File lib/rdoc/parser.rb, line 61 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
Determines if the file is a “binary” file which basically means it has content that an RDoc parser shouldn’t try to consume.
# File lib/rdoc/parser.rb, line 77 def self.binary?(file) return false if file =~ /\.(rdoc|txt)$/ s = File.read(file, 1024) or return false have_encoding = s.respond_to? :encoding if have_encoding then return false if s.encoding != Encoding::ASCII_8BIT and s.valid_encoding? end return true if s[0, 2] == Marshal.dump('')[0, 2] or s.index("\x00") if have_encoding then s.force_encoding Encoding.default_external not s.valid_encoding? else if 0.respond_to? :fdiv then s.count("\x00-\x7F", "^ -~\t\r\n").fdiv(s.size) > 0.3 else # HACK 1.8.6 (s.count("\x00-\x7F", "^ -~\t\r\n").to_f / s.size) > 0.3 end end end
Return a parser that can handle a particular extension
# File lib/rdoc/parser.rb, line 141 def self.can_parse(file_name) parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last # HACK Selenium hides a jar file using a .txt extension return if parser == RDoc::Parser::Simple and zip? file_name # The default parser must not parse binary files ext_name = File.extname file_name return parser if ext_name.empty? return if parser == RDoc::Parser::Simple and ext_name !~ /txt|rdoc/ parser end
Find the correct parser for a particular file name. Return a SimpleParser for ones that we don’t know
# File lib/rdoc/parser.rb, line 159 def self.for(top_level, file_name, body, options, stats) return if binary? file_name # If no extension, look for shebang if file_name !~ /\.\w+$/ && body =~ %{\A#!(.+)} then shebang = $1 case shebang when %{env\s+ruby}, %{/ruby} file_name = "dummy.rb" end end parser = can_parse file_name return unless parser parser.new top_level, file_name, body, options, stats end
Creates a new Parser storing top_level, file_name, content, options and stats in instance variables.
Usually invoked by super
# File lib/rdoc/parser.rb, line 193 def initialize(top_level, file_name, content, options, stats) @top_level = top_level @file_name = file_name @content = content @options = options @stats = stats end
Record which file types this parser can understand.
It is ok to call this multiple times.
# File lib/rdoc/parser.rb, line 183 def self.parse_files_matching(regexp) RDoc::Parser.parsers.unshift [regexp, self] end
Processes common directives for CodeObjects for the C and Ruby parsers.
Applies directive‘s value to code_object, if appropriate
# File lib/rdoc/parser.rb, line 108 def self.process_directive code_object, directive, value case directive when 'nodoc' then code_object.document_self = nil # notify nodoc code_object.document_children = value.downcase != 'all' when 'doc' then code_object.document_self = true code_object.force_documentation = true when 'yield', 'yields' then # remove parameter &block code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params code_object.block_params = value when 'arg', 'args' then code_object.params = value end end
Checks if file is a zip file in disguise. Signatures from www.garykessler.net/library/file_sigs.html
# File lib/rdoc/parser.rb, line 130 def self.zip? file zip_signature = File.read file, 4 zip_signature == "PK\x03\x04" or zip_signature == "PK\x05\x06" or zip_signature == "PK\x07\x08" end
Generated with the Darkfish Rdoc Generator 2.