Module | RDoc |
In: |
code_objects.rb
diagram.rb rdoc.rb usage.rb parsers/parse_c.rb parsers/parse_f95.rb parsers/parse_rb.rb parsers/parse_simple.rb parsers/parserfactory.rb |
Extract code elements from a source file, returning a TopLevel object containing the constituent file elements.
This file is based on rtags
DOT_DOC_FILENAME | = | ".document" | Name of the dotfile that contains the description of files to be processed in the current directory | |
KNOWN_CLASSES | = | { "rb_cObject" => "Object", "rb_cArray" => "Array", "rb_cBignum" => "Bignum", "rb_cClass" => "Class", "rb_cDir" => "Dir", "rb_cData" => "Data", "rb_cFalseClass" => "FalseClass", "rb_cFile" => "File", "rb_cFixnum" => "Fixnum", "rb_cFloat" => "Float", "rb_cHash" => "Hash", "rb_cInteger" => "Integer", "rb_cIO" => "IO", "rb_cModule" => "Module", "rb_cNilClass" => "NilClass", "rb_cNumeric" => "Numeric", "rb_cProc" => "Proc", "rb_cRange" => "Range", "rb_cRegexp" => "Regexp", "rb_cString" => "String", "rb_cSymbol" => "Symbol", "rb_cThread" => "Thread", "rb_cTime" => "Time", "rb_cTrueClass" => "TrueClass", "rb_cStruct" => "Struct", "rb_eException" => "Exception", "rb_eStandardError" => "StandardError", "rb_eSystemExit" => "SystemExit", "rb_eInterrupt" => "Interrupt", "rb_eSignal" => "Signal", "rb_eFatal" => "Fatal", "rb_eArgError" => "ArgError", "rb_eEOFError" => "EOFError", "rb_eIndexError" => "IndexError", "rb_eRangeError" => "RangeError", "rb_eIOError" => "IOError", "rb_eRuntimeError" => "RuntimeError", "rb_eSecurityError" => "SecurityError", "rb_eSystemCallError" => "SystemCallError", "rb_eTypeError" => "TypeError", "rb_eZeroDivError" => "ZeroDivError", "rb_eNotImpError" => "NotImpError", "rb_eNoMemError" => "NoMemError", "rb_eFloatDomainError" => "FloatDomainError", "rb_eScriptError" => "ScriptError", "rb_eNameError" => "NameError", "rb_eSyntaxError" => "SyntaxError", "rb_eLoadError" => "LoadError", "rb_mKernel" => "Kernel", "rb_mComparable" => "Comparable", "rb_mEnumerable" => "Enumerable", "rb_mPrecision" => "Precision", "rb_mErrno" => "Errno", "rb_mFileTest" => "FileTest", "rb_mGC" => "GC", "rb_mMath" => "Math", "rb_mProcess" => "Process" | ||
GENERAL_MODIFIERS | = | [ 'nodoc' ].freeze | ||
CLASS_MODIFIERS | = | GENERAL_MODIFIERS | ||
ATTR_MODIFIERS | = | GENERAL_MODIFIERS | ||
CONSTANT_MODIFIERS | = | GENERAL_MODIFIERS | ||
METHOD_MODIFIERS | = | GENERAL_MODIFIERS + [ 'arg', 'args', 'yield', 'yields', 'notnew', 'not-new', 'not_new', 'doc' ] |
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.
# 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
# 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
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
# 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
Report the fact that no doc comment count be found
# File 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)
# 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
# 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