Module RDoc
In: code_objects.rb
diagram.rb
dot.rb
rdoc.rb
template.rb
tokenstream.rb
usage.rb
parsers/parse_c.rb
parsers/parse_f95.rb
parsers/parserfactory.rb
doc-tmp/rdoc/code_objects.rb
doc-tmp/rdoc/diagram.rb
doc-tmp/rdoc/dot.rb
doc-tmp/rdoc/rdoc.rb
doc-tmp/rdoc/template.rb
doc-tmp/rdoc/tokenstream.rb
doc-tmp/rdoc/usage.rb

An ERB wrapper.

This TemplatePage operates similarly to RDoc 1.x‘s TemplatePage, but uses ERB instead of a custom template language.

Converting from a RDoc 1.x template to an RDoc 2.x template is fairly easy.

  • %blah% becomes <%= values["blah"] %>
  • !INCLUDE! becomes <%= template_include %>
  • HREF:aref:name becomes <%= href values["aref"], values["name"] %>
  • IF:blah becomes <% if values["blah"] then %>
  • IFNOT:blah becomes <% unless values["blah"] then %>
  • ENDIF:blah becomes <% end %>
  • START:blah becomes <% values["blah"].each do |blah| %>
  • END:blah becomes <% end %>

To make nested loops easier to convert, start by converting START statements to:

  <% values["blah"].each do |blah| $stderr.puts blah.keys %>

So you can see what is being used inside which loop.

Methods

Public Class methods

Given an array of flow items and an array of section names, extract those sections from the flow which have headings corresponding to a section name in the list. Return them in the order of names in the sections array.

[Source]

     # File usage.rb, line 165
165:   def RDoc.extract_sections(flow, sections)
166:     result = []
167:     sections.each do |name|
168:       name = name.downcase
169:       copy_upto_level = nil
170: 
171:       flow.each do |item|
172:         case item
173:         when SM::Flow::H
174:           if copy_upto_level && item.level >= copy_upto_level
175:             copy_upto_level = nil
176:           else
177:             if item.text.downcase == name
178:               result << item
179:               copy_upto_level = item.level
180:             end
181:           end
182:         else
183:           if copy_upto_level
184:             result << item
185:           end
186:         end
187:       end
188:     end
189:     if result.empty?
190:       puts "Note to developer: requested section(s) [#{sections.join(', ')}] " +
191:            "not found"
192:       result = flow
193:     end
194:     result
195:   end

Given an array of flow items and an array of section names, extract those sections from the flow which have headings corresponding to a section name in the list. Return them in the order of names in the sections array.

[Source]

     # File doc-tmp/rdoc/usage.rb, line 165
165:   def RDoc.extract_sections(flow, sections)
166:     result = []
167:     sections.each do |name|
168:       name = name.downcase
169:       copy_upto_level = nil
170: 
171:       flow.each do |item|
172:         case item
173:         when SM::Flow::H
174:           if copy_upto_level && item.level >= copy_upto_level
175:             copy_upto_level = nil
176:           else
177:             if item.text.downcase == name
178:               result << item
179:               copy_upto_level = item.level
180:             end
181:           end
182:         else
183:           if copy_upto_level
184:             result << item
185:           end
186:         end
187:       end
188:     end
189:     if result.empty?
190:       puts "Note to developer: requested section(s) [#{sections.join(', ')}] " +
191:            "not found"
192:       result = flow
193:     end
194:     result
195:   end

[Source]

     # File usage.rb, line 141
141:   def RDoc.find_comment(file)
142:     catch(:exit) do
143:       # skip leading blank lines
144:       0 while (line = gets(file)) && (line =~ /^\s*$/)
145: 
146:       comment = []
147:       while line && line =~ /^\s*#/
148:         comment << line
149:         line = gets(file)
150:       end
151: 
152:       0 while line && (line = gets(file))
153:       return no_comment if comment.empty?
154:       return comment.join
155:     end
156:   end

[Source]

     # File doc-tmp/rdoc/usage.rb, line 141
141:   def RDoc.find_comment(file)
142:     catch(:exit) do
143:       # skip leading blank lines
144:       0 while (line = gets(file)) && (line =~ /^\s*$/)
145: 
146:       comment = []
147:       while line && line =~ /^\s*#/
148:         comment << line
149:         line = gets(file)
150:       end
151: 
152:       0 while line && (line = gets(file))
153:       return no_comment if comment.empty?
154:       return comment.join
155:     end
156:   end

Find the first comment in the file (that isn‘t a shebang line) If the file doesn‘t start with a comment, report the fact and return empty string

[Source]

     # File usage.rb, line 133
133:   def RDoc.gets(file)
134:     if (line = file.gets) && (line =~ /^#!/) # shebang
135:       throw :exit, find_comment(file)
136:     else
137:       line
138:     end
139:   end

Find the first comment in the file (that isn‘t a shebang line) If the file doesn‘t start with a comment, report the fact and return empty string

[Source]

     # File doc-tmp/rdoc/usage.rb, line 133
133:   def RDoc.gets(file)
134:     if (line = file.gets) && (line =~ /^#!/) # shebang
135:       throw :exit, find_comment(file)
136:     else
137:       line
138:     end
139:   end

Report the fact that no doc comment count be found

[Source]

     # File usage.rb, line 199
199:   def RDoc.no_comment
200:     $stderr.puts "No usage information available for this program"
201:     ""
202:   end

Report the fact that no doc comment count be found

[Source]

     # File doc-tmp/rdoc/usage.rb, line 199
199:   def RDoc.no_comment
200:     $stderr.puts "No usage information available for this program"
201:     ""
202:   end

Display usage information from the comment at the top of the file. String arguments identify specific sections of the comment to display. An optional integer first argument specifies the exit status (defaults to 0)

[Source]

    # File doc-tmp/rdoc/usage.rb, line 81
81:   def RDoc.usage(*args)
82:     exit_code = 0
83: 
84:     if args.size > 0
85:       status = args[0]
86:       if status.respond_to?(:to_int)
87:         exit_code = status.to_int
88:         args.shift
89:       end
90:     end
91: 
92:     # display the usage and exit with the given code
93:     usage_no_exit(*args)
94:     exit(exit_code)
95:   end

Display usage information from the comment at the top of the file. String arguments identify specific sections of the comment to display. An optional integer first argument specifies the exit status (defaults to 0)

[Source]

    # File usage.rb, line 81
81:   def RDoc.usage(*args)
82:     exit_code = 0
83: 
84:     if args.size > 0
85:       status = args[0]
86:       if status.respond_to?(:to_int)
87:         exit_code = status.to_int
88:         args.shift
89:       end
90:     end
91: 
92:     # display the usage and exit with the given code
93:     usage_no_exit(*args)
94:     exit(exit_code)
95:   end

Display usage

[Source]

     # File usage.rb, line 98
 98:   def RDoc.usage_no_exit(*args)
 99:     main_program_file, = caller[-1].split(/:\d+/, 2)
100:     comment = File.open(main_program_file) do |file|
101:       find_comment(file)
102:     end
103: 
104:     comment = comment.gsub(/^\s*#/, '')
105: 
106:     markup = SM::SimpleMarkup.new
107:     flow_convertor = SM::ToFlow.new
108:     
109:     flow = markup.convert(comment, flow_convertor)
110: 
111:     format = "plain"
112: 
113:     unless args.empty?
114:       flow = extract_sections(flow, args)
115:     end
116: 
117:     options = RI::Options.instance
118:     if args = ENV["RI"]
119:       options.parse(args.split)
120:     end
121:     formatter = options.formatter.new(options, "")
122:     formatter.display_flow(flow)
123:   end

Display usage

[Source]

     # File doc-tmp/rdoc/usage.rb, line 98
 98:   def RDoc.usage_no_exit(*args)
 99:     main_program_file, = caller[-1].split(/:\d+/, 2)
100:     comment = File.open(main_program_file) do |file|
101:       find_comment(file)
102:     end
103: 
104:     comment = comment.gsub(/^\s*#/, '')
105: 
106:     markup = SM::SimpleMarkup.new
107:     flow_convertor = SM::ToFlow.new
108:     
109:     flow = markup.convert(comment, flow_convertor)
110: 
111:     format = "plain"
112: 
113:     unless args.empty?
114:       flow = extract_sections(flow, args)
115:     end
116: 
117:     options = RI::Options.instance
118:     if args = ENV["RI"]
119:       options.parse(args.split)
120:     end
121:     formatter = options.formatter.new(options, "")
122:     formatter.display_flow(flow)
123:   end

[Validate]