RDoc::Markup::PreProcess

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

: include : filename

RDoc plugin authors can register additional directives to be handled through RDoc::Markup::PreProcess::register

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/preprocess.rb, line 35
35:   def initialize(input_file_name, include_path)
36:     @input_file_name = input_file_name
37:     @include_path = include_path
38:   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.

    # File lib/rdoc/markup/preprocess.rb, line 20
20:   def self.register directive, &block
21:     @registered[directive] = block
22:   end

registered() click to toggle source

Registered directives

    # File lib/rdoc/markup/preprocess.rb, line 27
27:   def self.registered
28:     @registered
29:   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/preprocess.rb, line 119
119:   def find_include_file(name)
120:     to_search = [File.dirname(@input_file_name)].concat @include_path
121:     to_search.each do |dir|
122:       full_name = File.join(dir, name)
123:       stat = File.stat(full_name) rescue next
124:       return full_name if stat.readable?
125:     end
126:     nil
127:   end

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

Look for directives in a chunk of 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 param is set as metadata on the code_object. See RDoc::CodeObject#metadata

    # File lib/rdoc/markup/preprocess.rb, line 54
54:   def handle text, code_object = nil
55:     text.gsub!(/^([ \t]*#?[ \t]*):(\w+):([ \t]*)(.+)?\n/) do
56:       next $& if $3.empty? and $4 and $4[0, 1] == ':'
57: 
58:       prefix    = $1
59:       directive = $2.downcase
60:       param     = $4
61: 
62:       case directive
63:       when 'include' then
64:         filename = param.split[0]
65:         include_file filename, prefix
66: 
67:       else
68:         result = yield directive, param if block_given?
69: 
70:         case result
71:         when nil then
72:           code_object.metadata[directive] = param if code_object
73:           if RDoc::Markup::PreProcess.registered.include? directive then
74:             handler = RDoc::Markup::PreProcess.registered[directive]
75:             result = handler.call directive, param if handler
76:           else
77:             result = "#{prefix}:#{directive}: #{param}\n"
78:           end
79:         when false then
80:           result = "#{prefix}:#{directive}: #{param}\n"
81:         end
82: 
83:         result
84:       end
85:     end
86: 
87:     text
88:   end

include_file(name, indent) click to toggle source

Include a file, indenting it correctly.

     # File lib/rdoc/markup/preprocess.rb, line 93
 93:   def include_file(name, indent)
 94:     if full_name = find_include_file(name) then
 95:       content = if defined?(Encoding) then
 96:                   File.binread full_name
 97:                 else
 98:                   File.read full_name
 99:                 end
100:       # HACK determine content type and force encoding
101:       content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
102: 
103:       # strip leading '#'s, but only if all lines start with them
104:       if content =~ /^[^#]/ then
105:         content.gsub(/^/, indent)
106:       else
107:         content.gsub(/^#?/, indent)
108:       end
109:     else
110:       warn "Couldn't find file to include '#{name}' from #{@input_file_name}"
111:       ''
112:     end
113:   end

Home Classes Methods

In Files

Parent

Methods

Files

Class Index

RDoc::Markup::PreProcess

Public Class Methods

Public Instance Methods