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
# 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
# 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:
# 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:
# 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
# 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
# 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
create table of contents if we contain sections
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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.
# File generator.rb, line 417 417: def build_class_list(level, from, section, infile=nil) 418: res = "" 419: prefix = " ::" * 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.
# File doc-tmp/rdoc/generator.rb, line 417 417: def build_class_list(level, from, section, infile=nil) 418: res = "" 419: prefix = " ::" * 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
# 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
# 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
# File doc-tmp/rdoc/generator.rb, line 298 298: def build_include_list(context) 299: potentially_referenced_list(context.includes) 300: end
# 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
# 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(/->/, '→') 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
# 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(/->/, '→') 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
# 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
# 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
# File generator.rb, line 294 294: def build_requires_list(context) 295: potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] } 296: end
# 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.
# 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.
# 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
# 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
# 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
# File doc-tmp/rdoc/generator.rb, line 462 462: def document_self 463: @context.document_self 464: end
Find a filenames in ourselves or our parent
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# File generator.rb, line 450 450: def url(target) 451: RDoc::Generator.gen_url path, target 452: end