class RDoc::Markup::PreProcess

Handle common directives that can occur in a block of text:

:include: filename

Directives can be escaped by preceding them with a backslash.

RDoc plugin authors can register additional directives to be handled by using ::register.

Any directive that is not built-in to RDoc (including those registered via plugins) will be stored in the metadata hash on the CodeObject the comment is attached to. See Directives at RDoc::Markup for the list of built-in directives.

Attributes

options[RW]

An RDoc::Options instance that will be filled in with overrides from directives

Public Class Methods

new(input_file_name, include_path) click to toggle source

Creates a new pre-processor for input_file_name that will look for included files in include_path

# File lib/rdoc/markup/pre_process.rb, line 77
def initialize(input_file_name, include_path)
 @input_file_name = input_file_name
 @include_path = include_path
 @options = nil
end

post_process(&block) click to toggle source

Adds a post-process handler for directives. The handler will be called with the result RDoc::Comment (or text String) and the code object for the comment (if any).

# File lib/rdoc/markup/pre_process.rb, line 29
def self.post_process &block
 @post_processors << block
end

post_processors() click to toggle source

Registered post-processors

# File lib/rdoc/markup/pre_process.rb, line 36
def self.post_processors
 @post_processors
end

Registers directive as one handled by RDoc. If a block is given the directive will be replaced by the result of the block, otherwise the directive will be removed from the processed text.

The block will be called with the directive name and the directive parameter:

RDoc::Markup::PreProcess.register 'my-directive' do |directive, param|
 # replace text, etc.
end

# File lib/rdoc/markup/pre_process.rb, line 52
def self.register directive, &block
 @registered[directive] = block
end

registered() click to toggle source

Registered directives

# File lib/rdoc/markup/pre_process.rb, line 59
def self.registered
 @registered
end

reset() click to toggle source

Clears all registered directives and post-processors

# File lib/rdoc/markup/pre_process.rb, line 66
def self.reset
 @post_processors = []
 @registered = {}
end

Public Instance Methods

find_include_file(name) click to toggle source

Look for the given file in the directory containing the current file, and then in each of the directories specified in the RDOC_INCLUDE path

# File lib/rdoc/markup/pre_process.rb, line 282
def find_include_file(name)
 to_search = [File.dirname(@input_file_name)].concat @include_path
 to_search.each do |dir|
 full_name = File.join(dir, name)
 stat = File.stat(full_name) rescue next
 return full_name if stat.readable?
 end
 nil
end

handle(text, code_object = nil, &block) click to toggle source

Look for directives in the given text.

Options that we don't handle are yielded. If the block returns false the directive is restored to the text. If the block returns nil or no block was given the directive is handled according to the registered directives. If a String was returned the directive is replaced with the string.

If no matching directive was registered the directive is restored to the text.

If code_object is given and the directive is unknown then the directive's parameter is set as metadata on the code_object. See RDoc::CodeObject#metadata for details.

# File lib/rdoc/markup/pre_process.rb, line 98
def handle text, code_object = nil, &block
 if RDoc::Comment === text then
 comment = text
 text = text.text
 end
 encoding = text.encoding if defined?(Encoding)
 # regexp helper (square brackets for optional)
 # 1ドル 2ドル 3ドル 4ドル 5ドル
 # [prefix][\]:directive:[spaces][param]newline
 text.gsub!(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\?):(\w+):([ \t]*)(.+)?(\r?\n|$)/) do
 # skip something like ':toto::'
 next $& if 4ドル.empty? and 5ドル and 5ドル[0, 1] == ':'
 # skip if escaped
 next "#1ドル:#3ドル:#4ドル#5ドル\n" unless 2ドル.empty?
 # This is not in handle_directive because I didn't want to pass another
 # argument into it
 if comment and 3ドル == 'markup' then
 next "#{1ドル.strip}\n" unless 5ドル
 comment.format = 5ドル.downcase
 next "#{1ドル.strip}\n"
 end
 handle_directive 1ドル, 3ドル, 5ドル, code_object, encoding, &block
 end
 comment = text unless comment
 self.class.post_processors.each do |handler|
 handler.call comment, code_object
 end
 text
end

handle_directive(prefix, directive, param, code_object = nil, encoding = nil) { |directive, param| ... } click to toggle source

Performs the actions described by directive and its parameter param.

code_object is used for directives that operate on a class or module. prefix is used to ensure the replacement for handled directives is correct. encoding is used for the include directive.

For a list of directives in RDoc see RDoc::Markup.

# File lib/rdoc/markup/pre_process.rb, line 147
def handle_directive prefix, directive, param, code_object = nil,
 encoding = nil
 blankline = "#{prefix.strip}\n"
 directive = directive.downcase
 case directive
 when 'arg', 'args' then
 return "#{prefix}:#{directive}: #{param}\n" unless code_object
 code_object.params = param
 blankline
 when 'category' then
 if RDoc::Context === code_object then
 section = code_object.add_section param
 code_object.temporary_section = section
 end
 blankline # ignore category if we're not on an RDoc::Context
 when 'doc' then
 return blankline unless code_object
 code_object.document_self = true
 code_object.force_documentation = true
 blankline
 when 'enddoc' then
 return blankline unless code_object
 code_object.done_documenting = true
 blankline
 when 'include' then
 filename = param.split.first
 include_file filename, prefix, encoding
 when 'main' then
 @options.main_page = param if @options.respond_to? :main_page
 blankline
 when 'nodoc' then
 return blankline unless code_object
 code_object.document_self = nil # notify nodoc
 code_object.document_children = param !~ /all/i
 blankline
 when 'notnew', 'not_new', 'not-new' then
 return blankline unless RDoc::AnyMethod === code_object
 code_object.dont_rename_initialize = true
 blankline
 when 'startdoc' then
 return blankline unless code_object
 code_object.start_doc
 code_object.force_documentation = true
 blankline
 when 'stopdoc' then
 return blankline unless code_object
 code_object.stop_doc
 blankline
 when 'title' then
 @options.default_title = param if @options.respond_to? :default_title=
 blankline
 when 'yield', 'yields' then
 return blankline unless code_object
 # remove parameter &block
 code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
 code_object.block_params = param
 blankline
 else
 result = yield directive, param if block_given?
 case result
 when nil then
 code_object.metadata[directive] = param if code_object
 if RDoc::Markup::PreProcess.registered.include? directive then
 handler = RDoc::Markup::PreProcess.registered[directive]
 result = handler.call directive, param if handler
 else
 result = "#{prefix}:#{directive}: #{param}\n"
 end
 when false then
 result = "#{prefix}:#{directive}: #{param}\n"
 end
 result
 end
end

include_file(name, indent, encoding) click to toggle source

Handles the :include: filename directive.

If the first line of the included file starts with '#', and contains an encoding information in the form 'coding:' or 'coding=', it is removed.

If all lines in the included file start with a '#', this leading '#' is removed before inclusion. The included content is indented like the :include: directive.

# File lib/rdoc/markup/pre_process.rb, line 257
def include_file name, indent, encoding
 full_name = find_include_file name
 unless full_name then
 warn "Couldn't find file to include '#{name}' from #{@input_file_name}"
 return ''
 end
 content = RDoc::Encoding.read_file full_name, encoding, true
 # strip magic comment
 content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
 # strip leading '#'s, but only if all lines start with them
 if content =~ /^[^#]/ then
 content.gsub(/^/, indent)
 else
 content.gsub(/^#?/, indent)
 end
end