Class RDoc::Generator::Context
In: generator.rb
doc-tmp/rdoc/generator.rb
Parent: Object

A Context is built by the parser to represent a container: contexts hold classes, modules, methods, require lists and include lists. ClassModule and TopLevel are the context objects we process here

Methods

Included Modules

MarkUp MarkUp

Public Class methods

[Source]

     # File generator.rb, line 184
184:     def self.build_class_list(classes, options, from, html_file, class_dir)
185:       classes << RDoc::Generator::Class.new(from, html_file, class_dir, options)
186: 
187:       from.each_classmodule do |mod|
188:         build_class_list(classes, options, mod, html_file, class_dir)
189:       end
190:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 184
184:     def self.build_class_list(classes, options, from, html_file, class_dir)
185:       classes << RDoc::Generator::Class.new(from, html_file, class_dir, options)
186: 
187:       from.each_classmodule do |mod|
188:         build_class_list(classes, options, mod, html_file, class_dir)
189:       end
190:     end

Generate:

[Source]

     # File doc-tmp/rdoc/generator.rb, line 167
167:     def self.build_indicies(toplevels, options)
168:       files = []
169:       classes = []
170: 
171:       toplevels.each do |toplevel|
172:         files << RDoc::Generator::File.new(toplevel, options,
173:                                            RDoc::Generator::FILE_DIR)
174:       end
175: 
176:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
177:         build_class_list(classes, options, cls, files[0], 
178:                          RDoc::Generator::CLASS_DIR)
179:       end
180: 
181:       return files, classes
182:     end

Generate:

[Source]

     # File generator.rb, line 167
167:     def self.build_indicies(toplevels, options)
168:       files = []
169:       classes = []
170: 
171:       toplevels.each do |toplevel|
172:         files << RDoc::Generator::File.new(toplevel, options,
173:                                            RDoc::Generator::FILE_DIR)
174:       end
175: 
176:       RDoc::TopLevel.all_classes_and_modules.each do |cls|
177:         build_class_list(classes, options, cls, files[0], 
178:                          RDoc::Generator::CLASS_DIR)
179:       end
180: 
181:       return files, classes
182:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 192
192:     def initialize(context, options)
193:       @context = context
194:       @options = options
195: 
196:       # HACK ugly
197:       @template = options.template_class
198:     end

[Source]

     # File generator.rb, line 192
192:     def initialize(context, options)
193:       @context = context
194:       @options = options
195: 
196:       # HACK ugly
197:       @template = options.template_class
198:     end

Public Instance methods

create table of contents if we contain sections

[Source]

     # File doc-tmp/rdoc/generator.rb, line 496
496:     def add_table_of_sections
497:       toc = []
498:       @context.sections.each do |section|
499:         if section.title
500:           toc << {
501:             'secname' => section.title,
502:             'href'    => section.sequence
503:           }
504:         end
505:       end
506: 
507:       @values['toc'] = toc unless toc.empty?
508:     end

create table of contents if we contain sections

[Source]

     # File generator.rb, line 496
496:     def add_table_of_sections
497:       toc = []
498:       @context.sections.each do |section|
499:         if section.title
500:           toc << {
501:             'secname' => section.title,
502:             'href'    => section.sequence
503:           }
504:         end
505:       end
506: 
507:       @values['toc'] = toc unless toc.empty?
508:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 454
454:     def aref_to(target)
455:       if @options.all_one_file
456:         "#" + target
457:       else
458:         url(target)
459:       end
460:     end

[Source]

     # File generator.rb, line 454
454:     def aref_to(target)
455:       if @options.all_one_file
456:         "#" + target
457:       else
458:         url(target)
459:       end
460:     end

Returns a reference to outselves to be used as an href= the form depends on whether we‘re all in one file or in multiple files

[Source]

     # File generator.rb, line 211
211:     def as_href(from_path)
212:       if @options.all_one_file
213:         "#" + path
214:       else
215:         RDoc::Generator.gen_url from_path, path
216:       end
217:     end

Returns a reference to outselves to be used as an href= the form depends on whether we‘re all in one file or in multiple files

[Source]

     # File doc-tmp/rdoc/generator.rb, line 211
211:     def as_href(from_path)
212:       if @options.all_one_file
213:         "#" + path
214:       else
215:         RDoc::Generator.gen_url from_path, path
216:       end
217:     end

Build a list of aliases for which we couldn‘t find a corresponding method

[Source]

     # File doc-tmp/rdoc/generator.rb, line 261
261:     def build_alias_summary_list(section)
262:       values = []
263:       @context.aliases.each do |al|
264:         next unless al.section == section
265:         res = {
266:           'old_name' => al.old_name,
267:           'new_name' => al.new_name,
268:         }
269:         if al.comment && !al.comment.empty?
270:           res['desc'] = markup(al.comment, true)
271:         end
272:         values << res
273:       end
274:       values
275:     end

Build a list of aliases for which we couldn‘t find a corresponding method

[Source]

     # File generator.rb, line 261
261:     def build_alias_summary_list(section)
262:       values = []
263:       @context.aliases.each do |al|
264:         next unless al.section == section
265:         res = {
266:           'old_name' => al.old_name,
267:           'new_name' => al.new_name,
268:         }
269:         if al.comment && !al.comment.empty?
270:           res['desc'] = markup(al.comment, true)
271:         end
272:         values << res
273:       end
274:       values
275:     end

Build the structured list of classes and modules contained in this context.

[Source]

     # File generator.rb, line 417
417:     def build_class_list(level, from, section, infile=nil)
418:       res = ""
419:       prefix = "&nbsp;&nbsp;::" * level;
420: 
421:       from.modules.sort.each do |mod|
422:         next unless mod.section == section
423:         next if infile && !mod.defined_in?(infile)
424:         if mod.document_self
425:           res <<
426:             prefix <<
427:             "Module " <<
428:             href(url(mod.viewer.path), "link", mod.full_name) <<
429:             "<br />\n" <<
430:             build_class_list(level + 1, mod, section, infile)
431:         end
432:       end
433: 
434:       from.classes.sort.each do |cls|
435:         next unless cls.section == section
436:         next if infile && !cls.defined_in?(infile)
437:         if cls.document_self
438:           res      <<
439:             prefix <<
440:             "Class " <<
441:             href(url(cls.viewer.path), "link", cls.full_name) <<
442:             "<br />\n" <<
443:             build_class_list(level + 1, cls, section, infile)
444:         end
445:       end
446: 
447:       res
448:     end

Build the structured list of classes and modules contained in this context.

[Source]

     # File doc-tmp/rdoc/generator.rb, line 417
417:     def build_class_list(level, from, section, infile=nil)
418:       res = ""
419:       prefix = "&nbsp;&nbsp;::" * level;
420: 
421:       from.modules.sort.each do |mod|
422:         next unless mod.section == section
423:         next if infile && !mod.defined_in?(infile)
424:         if mod.document_self
425:           res <<
426:             prefix <<
427:             "Module " <<
428:             href(url(mod.viewer.path), "link", mod.full_name) <<
429:             "<br />\n" <<
430:             build_class_list(level + 1, mod, section, infile)
431:         end
432:       end
433: 
434:       from.classes.sort.each do |cls|
435:         next unless cls.section == section
436:         next if infile && !cls.defined_in?(infile)
437:         if cls.document_self
438:           res      <<
439:             prefix <<
440:             "Class " <<
441:             href(url(cls.viewer.path), "link", cls.full_name) <<
442:             "<br />\n" <<
443:             build_class_list(level + 1, cls, section, infile)
444:         end
445:       end
446: 
447:       res
448:     end

Build a list of constants

[Source]

     # File doc-tmp/rdoc/generator.rb, line 280
280:     def build_constants_summary_list(section)
281:       values = []
282:       @context.constants.each do |co|
283:         next unless co.section == section
284:         res = {
285:           'name'  => co.name,
286:           'value' => CGI.escapeHTML(co.value)
287:         }
288:         res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty?
289:         values << res
290:       end
291:       values
292:     end

Build a list of constants

[Source]

     # File generator.rb, line 280
280:     def build_constants_summary_list(section)
281:       values = []
282:       @context.constants.each do |co|
283:         next unless co.section == section
284:         res = {
285:           'name'  => co.name,
286:           'value' => CGI.escapeHTML(co.value)
287:         }
288:         res['desc'] = markup(co.comment, true) if co.comment && !co.comment.empty?
289:         values << res
290:       end
291:       values
292:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 298
298:     def build_include_list(context)
299:       potentially_referenced_list(context.includes)
300:     end

[Source]

     # File generator.rb, line 298
298:     def build_include_list(context)
299:       potentially_referenced_list(context.includes)
300:     end

Build an array of arrays of method details. The outer array has up to six entries, public, private, and protected for both class methods, the other for instance methods. The inner arrays contain a hash for each method

[Source]

     # File doc-tmp/rdoc/generator.rb, line 351
351:     def build_method_detail_list(section)
352:       outer = []
353: 
354:       methods = @methods.sort
355:       for singleton in [true, false]
356:         for vis in [ :public, :protected, :private ]
357:           res = []
358:           methods.each do |m|
359:             if m.section == section and
360:                 m.document_self and
361:                 m.visibility == vis and
362:                 m.singleton == singleton
363:               row = {}
364:               if m.call_seq
365:                 row["callseq"] = m.call_seq.gsub(/->/, '&rarr;')
366:               else
367:                 row["name"]        = CGI.escapeHTML(m.name)
368:                 row["params"]      = m.params
369:               end
370:               desc = m.description.strip
371:               row["m_desc"]      = desc unless desc.empty?
372:               row["aref"]        = m.aref
373:               row["visibility"]  = m.visibility.to_s
374: 
375:               alias_names = []
376:               m.aliases.each do |other|
377:                 if other.viewer   # won't be if the alias is private
378:                   alias_names << {
379:                     'name' => other.name,
380:                     'aref'  => other.viewer.as_href(path)
381:                   }
382:                 end
383:               end
384:               unless alias_names.empty?
385:                 row["aka"] = alias_names
386:               end
387: 
388:               if @options.inline_source
389:                 code = m.source_code
390:                 row["sourcecode"] = code if code
391:               else
392:                 code = m.src_url
393:                 if code
394:                   row["codeurl"] = code
395:                   row["imgurl"]  = m.img_url
396:                 end
397:               end
398:               res << row
399:             end
400:           end
401:           if res.size > 0
402:             outer << {
403:               "type"     => vis.to_s.capitalize,
404:               "category" => singleton ? "Class" : "Instance",
405:               "methods"  => res
406:             }
407:           end
408:         end
409:       end
410:       outer
411:     end

Build an array of arrays of method details. The outer array has up to six entries, public, private, and protected for both class methods, the other for instance methods. The inner arrays contain a hash for each method

[Source]

     # File generator.rb, line 351
351:     def build_method_detail_list(section)
352:       outer = []
353: 
354:       methods = @methods.sort
355:       for singleton in [true, false]
356:         for vis in [ :public, :protected, :private ]
357:           res = []
358:           methods.each do |m|
359:             if m.section == section and
360:                 m.document_self and
361:                 m.visibility == vis and
362:                 m.singleton == singleton
363:               row = {}
364:               if m.call_seq
365:                 row["callseq"] = m.call_seq.gsub(/->/, '&rarr;')
366:               else
367:                 row["name"]        = CGI.escapeHTML(m.name)
368:                 row["params"]      = m.params
369:               end
370:               desc = m.description.strip
371:               row["m_desc"]      = desc unless desc.empty?
372:               row["aref"]        = m.aref
373:               row["visibility"]  = m.visibility.to_s
374: 
375:               alias_names = []
376:               m.aliases.each do |other|
377:                 if other.viewer   # won't be if the alias is private
378:                   alias_names << {
379:                     'name' => other.name,
380:                     'aref'  => other.viewer.as_href(path)
381:                   }
382:                 end
383:               end
384:               unless alias_names.empty?
385:                 row["aka"] = alias_names
386:               end
387: 
388:               if @options.inline_source
389:                 code = m.source_code
390:                 row["sourcecode"] = code if code
391:               else
392:                 code = m.src_url
393:                 if code
394:                   row["codeurl"] = code
395:                   row["imgurl"]  = m.img_url
396:                 end
397:               end
398:               res << row
399:             end
400:           end
401:           if res.size > 0
402:             outer << {
403:               "type"     => vis.to_s.capitalize,
404:               "category" => singleton ? "Class" : "Instance",
405:               "methods"  => res
406:             }
407:           end
408:         end
409:       end
410:       outer
411:     end

Build a summary list of all the methods in this context

[Source]

     # File doc-tmp/rdoc/generator.rb, line 244
244:     def build_method_summary_list(path_prefix="")
245:       collect_methods unless @methods
246:       meths = @methods.sort
247:       res = []
248:       meths.each do |meth|
249:         res << {
250:           "name" => CGI.escapeHTML(meth.name),
251:           "aref" => "#{path_prefix}\##{meth.aref}"
252:         }
253:       end
254:       res
255:     end

Build a summary list of all the methods in this context

[Source]

     # File generator.rb, line 244
244:     def build_method_summary_list(path_prefix="")
245:       collect_methods unless @methods
246:       meths = @methods.sort
247:       res = []
248:       meths.each do |meth|
249:         res << {
250:           "name" => CGI.escapeHTML(meth.name),
251:           "aref" => "#{path_prefix}\##{meth.aref}"
252:         }
253:       end
254:       res
255:     end

[Source]

     # File generator.rb, line 294
294:     def build_requires_list(context)
295:       potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
296:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 294
294:     def build_requires_list(context)
295:       potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
296:     end

Create a list of Method objects for each method in the corresponding context object. If the @options.show_all variable is set (corresponding to the —all option, we include all methods, otherwise just the public ones.

[Source]

     # File doc-tmp/rdoc/generator.rb, line 225
225:     def collect_methods
226:       list = @context.method_list
227: 
228:       unless @options.show_all then
229:         list = list.find_all do |m|
230:           m.visibility == :public or
231:             m.visibility == :protected or
232:             m.force_documentation
233:         end
234:       end
235: 
236:       @methods = list.collect do |m|
237:         RDoc::Generator::Method.new m, self, @options
238:       end
239:     end

Create a list of Method objects for each method in the corresponding context object. If the @options.show_all variable is set (corresponding to the —all option, we include all methods, otherwise just the public ones.

[Source]

     # File generator.rb, line 225
225:     def collect_methods
226:       list = @context.method_list
227: 
228:       unless @options.show_all then
229:         list = list.find_all do |m|
230:           m.visibility == :public or
231:             m.visibility == :protected or
232:             m.force_documentation
233:         end
234:       end
235: 
236:       @methods = list.collect do |m|
237:         RDoc::Generator::Method.new m, self, @options
238:       end
239:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 466
466:     def diagram_reference(diagram)
467:       res = diagram.gsub(/((?:src|href)=")(.*?)"/) {
468:         $1 + url($2) + '"'
469:       }
470:       res
471:     end

[Source]

     # File generator.rb, line 466
466:     def diagram_reference(diagram)
467:       res = diagram.gsub(/((?:src|href)=")(.*?)"/) {
468:         $1 + url($2) + '"'
469:       }
470:       res
471:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 462
462:     def document_self
463:       @context.document_self
464:     end

[Source]

     # File generator.rb, line 462
462:     def document_self
463:       @context.document_self
464:     end

Find a filenames in ourselves or our parent

[Source]

     # File generator.rb, line 485
485:     def find_file(file, method=nil)
486:       res = @context.find_file(file, method, @options.ignore_case)
487:       if res
488:         res = res.viewer
489:       end
490:       res
491:     end

Find a filenames in ourselves or our parent

[Source]

     # File doc-tmp/rdoc/generator.rb, line 485
485:     def find_file(file, method=nil)
486:       res = @context.find_file(file, method, @options.ignore_case)
487:       if res
488:         res = res.viewer
489:       end
490:       res
491:     end

Find a symbol in ourselves or our parent

[Source]

     # File doc-tmp/rdoc/generator.rb, line 476
476:     def find_symbol(symbol, method=nil)
477:       res = @context.find_symbol(symbol, method, @options.ignore_case)
478:       if res
479:         res = res.viewer
480:       end
481:       res
482:     end

Find a symbol in ourselves or our parent

[Source]

     # File generator.rb, line 476
476:     def find_symbol(symbol, method=nil)
477:       res = @context.find_symbol(symbol, method, @options.ignore_case)
478:       if res
479:         res = res.viewer
480:       end
481:       res
482:     end

convenience method to build a hyperlink

[Source]

     # File generator.rb, line 203
203:     def href(link, cls, name)
204:       %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
205:     end

convenience method to build a hyperlink

[Source]

     # File doc-tmp/rdoc/generator.rb, line 203
203:     def href(link, cls, name)
204:       %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
205:     end

Build a list from an array of Context items. Look up each in the AllReferences hash: if we find a corresponding entry, we generate a hyperlink to it, otherwise just output the name. However, some names potentially need massaging. For example, you may require a Ruby file without the .rb extension, but the file names we know about may have it. To deal with this, we pass in a block which performs the massaging, returning an array of alternative names to match

[Source]

     # File doc-tmp/rdoc/generator.rb, line 311
311:     def potentially_referenced_list(array)
312:       res = []
313:       array.each do |i|
314:         ref = AllReferences[i.name]
315: #         if !ref
316: #           container = @context.parent
317: #           while !ref && container
318: #             name = container.name + "::" + i.name
319: #             ref = AllReferences[name]
320: #             container = container.parent
321: #           end
322: #         end
323: 
324:         ref = @context.find_symbol(i.name, nil, @options.ignore_case)  || \
325:               @context.find_file(i.name)
326:         ref = ref.viewer if ref
327: 
328:         if !ref && block_given?
329:           possibles = yield(i.name)
330:           while !ref and !possibles.empty?
331:             ref = AllReferences[possibles.shift]
332:           end
333:         end
334:         h_name = CGI.escapeHTML(i.name)
335:         if ref and ref.document_self
336:           path = url(ref.path)
337:           res << { "name" => h_name, "aref" => path }
338:         else
339:           res << { "name" => h_name }
340:         end
341:       end
342:       res
343:     end

Build a list from an array of Context items. Look up each in the AllReferences hash: if we find a corresponding entry, we generate a hyperlink to it, otherwise just output the name. However, some names potentially need massaging. For example, you may require a Ruby file without the .rb extension, but the file names we know about may have it. To deal with this, we pass in a block which performs the massaging, returning an array of alternative names to match

[Source]

     # File generator.rb, line 311
311:     def potentially_referenced_list(array)
312:       res = []
313:       array.each do |i|
314:         ref = AllReferences[i.name]
315: #         if !ref
316: #           container = @context.parent
317: #           while !ref && container
318: #             name = container.name + "::" + i.name
319: #             ref = AllReferences[name]
320: #             container = container.parent
321: #           end
322: #         end
323: 
324:         ref = @context.find_symbol(i.name, nil, @options.ignore_case)  || \
325:               @context.find_file(i.name)
326:         ref = ref.viewer if ref
327: 
328:         if !ref && block_given?
329:           possibles = yield(i.name)
330:           while !ref and !possibles.empty?
331:             ref = AllReferences[possibles.shift]
332:           end
333:         end
334:         h_name = CGI.escapeHTML(i.name)
335:         if ref and ref.document_self
336:           path = url(ref.path)
337:           res << { "name" => h_name, "aref" => path }
338:         else
339:           res << { "name" => h_name }
340:         end
341:       end
342:       res
343:     end

[Source]

     # File generator.rb, line 450
450:     def url(target)
451:       RDoc::Generator.gen_url path, target
452:     end

[Source]

     # File doc-tmp/rdoc/generator.rb, line 450
450:     def url(target)
451:       RDoc::Generator.gen_url path, target
452:     end

[Validate]