lib/ruby-1.9.1-rc1/lib/rdoc/parser/c.rb

   1 require 'rdoc/parser'
   2 require 'rdoc/parser/ruby'
   3 require 'rdoc/known_classes'
   4
   5 ##
   6 # We attempt to parse C extension files. Basically we look for
   7 # the standard patterns that you find in extensions: <tt>rb_define_class,
   8 # rb_define_method</tt> and so on. We also try to find the corresponding
   9 # C source for the methods and extract comments, but if we fail
  10 # we don't worry too much.
  11 #
  12 # The comments associated with a Ruby method are extracted from the C
  13 # comment block associated with the routine that _implements_ that
  14 # method, that is to say the method whose name is given in the
  15 # <tt>rb_define_method</tt> call. For example, you might write:
  16 #
  17 #  /*
  18 #   * Returns a new array that is a one-dimensional flattening of this
  19 #   * array (recursively). That is, for every element that is an array,
  20 #   * extract its elements into the new array.
  21 #   *
  22 #   *    s = [ 1, 2, 3 ]           #=> [1, 2, 3]
  23 #   *    t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
  24 #   *    a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
  25 #   *    a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  26 #   */
  27 #   static VALUE
  28 #   rb_ary_flatten(ary)
  29 #       VALUE ary;
  30 #   {
  31 #       ary = rb_obj_dup(ary);
  32 #       rb_ary_flatten_bang(ary);
  33 #       return ary;
  34 #   }
  35 #
  36 #   ...
  37 #
  38 #   void
  39 #   Init_Array()
  40 #   {
  41 #     ...
  42 #     rb_define_method(rb_cArray, "flatten", rb_ary_flatten, 0);
  43 #
  44 # Here RDoc will determine from the rb_define_method line that there's a
  45 # method called "flatten" in class Array, and will look for the implementation
  46 # in the method rb_ary_flatten. It will then use the comment from that
  47 # method in the HTML output. This method must be in the same source file
  48 # as the rb_define_method.
  49 #
  50 # C classes can be diagrammed (see /tc/dl/ruby/ruby/error.c), and RDoc
  51 # integrates C and Ruby source into one tree
  52 #
  53 # The comment blocks may include special directives:
  54 #
  55 # [Document-class: <i>name</i>]
  56 #   This comment block is documentation for the given class. Use this
  57 #   when the <tt>Init_xxx</tt> method is not named after the class.
  58 #
  59 # [Document-method: <i>name</i>]
  60 #   This comment documents the named method. Use when RDoc cannot
  61 #   automatically find the method from it's declaration
  62 #
  63 # [call-seq:  <i>text up to an empty line</i>]
  64 #   Because C source doesn't give descripive names to Ruby-level parameters,
  65 #   you need to document the calling sequence explicitly
  66 #
  67 # In addition, RDoc assumes by default that the C method implementing a
  68 # Ruby function is in the same source file as the rb_define_method call.
  69 # If this isn't the case, add the comment:
  70 #
  71 #    rb_define_method(....);  // in: filename
  72 #
  73 # As an example, we might have an extension that defines multiple classes
  74 # in its Init_xxx method. We could document them using
  75 #
  76 #   /*
  77 #    * Document-class:  MyClass
  78 #    *
  79 #    * Encapsulate the writing and reading of the configuration
  80 #    * file. ...
  81 #    */
  82 #
  83 #   /*
  84 #    * Document-method: read_value
  85 #    *
  86 #    * call-seq:
  87 #    *   cfg.read_value(key)            -> value
  88 #    *   cfg.read_value(key} { |key| }  -> value
  89 #    *
  90 #    * Return the value corresponding to +key+ from the configuration.
  91 #    * In the second form, if the key isn't found, invoke the
  92 #    * block and return its value.
  93 #    */
  94
  95 class RDoc::Parser::C < RDoc::Parser
  96
  97   parse_files_matching(/\.(?:([CcHh])\1?|c([+xp])\2|y)\z/)
  98
  99   @@enclosure_classes = {}
 100   @@known_bodies = {}
 101
 102   ##
 103   # Prepare to parse a C file
 104
 105   def initialize(top_level, file_name, content, options, stats)
 106     super
 107
 108     @known_classes = RDoc::KNOWN_CLASSES.dup
 109     @content = handle_tab_width handle_ifdefs_in(@content)
 110     @classes = Hash.new
 111     @file_dir = File.dirname(@file_name)
 112   end
 113
 114   def do_aliases
 115     @content.scan(%r{rb_define_alias\s*\(\s*(\w+),\s*"([^"]+)",\s*"([^"]+)"\s*\)}m) do
 116       |var_name, new_name, old_name|
 117       class_name = @known_classes[var_name] || var_name
 118       class_obj  = find_class(var_name, class_name)
 119
 120       as = class_obj.add_alias RDoc::Alias.new("", old_name, new_name, "")
 121
 122       @stats.add_alias as
 123     end
 124   end
 125
 126   def do_classes
 127     @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do
 128       |var_name, class_name|
 129       handle_class_module(var_name, "module", class_name, nil, nil)
 130     end
 131
 132     # The '.' lets us handle SWIG-generated files
 133     @content.scan(/([\w\.]+)\s* = \s*rb_define_class\s*
 134               \(
 135                  \s*"(\w+)",
 136                  \s*(\w+)\s*
 137               \)/mx) do |var_name, class_name, parent|
 138       handle_class_module(var_name, "class", class_name, parent, nil)
 139     end
 140
 141     @content.scan(/(\w+)\s*=\s*boot_defclass\s*\(\s*"(\w+?)",\s*(\w+?)\s*\)/) do
 142       |var_name, class_name, parent|
 143       parent = nil if parent == "0"
 144       handle_class_module(var_name, "class", class_name, parent, nil)
 145     end
 146
 147     @content.scan(/(\w+)\s* = \s*rb_define_module_under\s*
 148               \(
 149                  \s*(\w+),
 150                  \s*"(\w+)"
 151               \s*\)/mx) do |var_name, in_module, class_name|
 152       handle_class_module(var_name, "module", class_name, nil, in_module)
 153     end
 154
 155     @content.scan(/([\w\.]+)\s* = \s*rb_define_class_under\s*
 156               \(
 157                  \s*(\w+),
 158                  \s*"(\w+)",
 159                  \s*([\w\*\s\(\)\.\->]+)\s*  # for SWIG
 160               \s*\)/mx) do |var_name, in_module, class_name, parent|
 161       handle_class_module(var_name, "class", class_name, parent, in_module)
 162     end
 163   end
 164
 165   def do_constants
 166     @content.scan(%r{\Wrb_define_
 167                    (
 168                       variable |
 169                       readonly_variable |
 170                       const |
 171                       global_const |
 172                     )
 173                \s*\(
 174                  (?:\s*(\w+),)?
 175                  \s*"(\w+)",
 176                  \s*(.*?)\s*\)\s*;
 177                  }xm) do |type, var_name, const_name, definition|
 178       var_name = "rb_cObject" if !var_name or var_name == "rb_mKernel"
 179       handle_constants(type, var_name, const_name, definition)
 180     end
 181   end
 182
 183   ##
 184   # Look for includes of the form:
 185   #
 186   #   rb_include_module(rb_cArray, rb_mEnumerable);
 187
 188   def do_includes
 189     @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
 190       if cls = @classes[c]
 191         m = @known_classes[m] || m
 192         cls.add_include RDoc::Include.new(m, "")
 193       end
 194     end
 195   end
 196
 197   def do_methods
 198     @content.scan(%r{rb_define_
 199                    (
 200                       singleton_method |
 201                       method           |
 202                       module_function  |
 203                       private_method
 204                    )
 205                    \s*\(\s*([\w\.]+),
 206                      \s*"([^"]+)",
 207                      \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
 208                      \s*(-?\w+)\s*\)
 209                    (?:;\s*/[*/]\s+in\s+(\w+?\.[cy]))?
 210                  }xm) do
 211       |type, var_name, meth_name, meth_body, param_count, source_file|
 212
 213       # Ignore top-object and weird struct.c dynamic stuff
 214       next if var_name == "ruby_top_self"
 215       next if var_name == "nstr"
 216       next if var_name == "envtbl"
 217       next if var_name == "argf"   # it'd be nice to handle this one
 218
 219       var_name = "rb_cObject" if var_name == "rb_mKernel"
 220       handle_method(type, var_name, meth_name,
 221                     meth_body, param_count, source_file)
 222     end
 223
 224     @content.scan(%r{rb_define_attr\(
 225                              \s*([\w\.]+),
 226                              \s*"([^"]+)",
 227                              \s*(\d+),
 228                              \s*(\d+)\s*\);
 229                 }xm) do |var_name, attr_name, attr_reader, attr_writer|
 230       #var_name = "rb_cObject" if var_name == "rb_mKernel"
 231       handle_attr(var_name, attr_name,
 232                   attr_reader.to_i != 0,
 233                   attr_writer.to_i != 0)
 234     end
 235
 236     @content.scan(%r{rb_define_global_function\s*\(
 237                              \s*"([^"]+)",
 238                              \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
 239                              \s*(-?\w+)\s*\)
 240                 (?:;\s*/[*/]\s+in\s+(\w+?\.[cy]))?
 241                 }xm) do |meth_name, meth_body, param_count, source_file|
 242       handle_method("method", "rb_mKernel", meth_name,
 243                     meth_body, param_count, source_file)
 244     end
 245
 246     @content.scan(/define_filetest_function\s*\(
 247                              \s*"([^"]+)",
 248                              \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
 249                              \s*(-?\w+)\s*\)/xm) do
 250       |meth_name, meth_body, param_count|
 251
 252       handle_method("method", "rb_mFileTest", meth_name, meth_body, param_count)
 253       handle_method("singleton_method", "rb_cFile", meth_name, meth_body, param_count)
 254     end
 255   end
 256
 257   def find_attr_comment(attr_name)
 258     if @content =~ %r{((?>/\*.*?\*/\s+))
 259                    rb_define_attr\((?:\s*(\w+),)?\s*"#{attr_name}"\s*,.*?\)\s*;}xmi
 260       $1
 261     elsif @content =~ %r{Document-attr:\s#{attr_name}\s*?\n((?>.*?\*/))}m
 262       $1
 263     else
 264       ''
 265     end
 266   end
 267
 268   ##
 269   # Find the C code corresponding to a Ruby method
 270
 271   def find_body(class_name, meth_name, meth_obj, body, quiet = false)
 272     case body
 273     when %r"((?>/\*.*?\*/\s*))(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{meth_name}
 274             \s*(\([^)]*\))([^;]|$)"xm
 275       comment, params = $1, $2
 276       body_text = $&
 277
 278       remove_private_comments(comment) if comment
 279
 280       # see if we can find the whole body
 281
 282       re = Regexp.escape(body_text) + '[^(]*^\{.*?^\}'
 283       body_text = $& if /#{re}/m =~ body
 284
 285       # The comment block may have been overridden with a 'Document-method'
 286       # block. This happens in the interpreter when multiple methods are
 287       # vectored through to the same C method but those methods are logically
 288       # distinct (for example Kernel.hash and Kernel.object_id share the same
 289       # implementation
 290
 291       override_comment = find_override_comment(class_name, meth_obj.name)
 292       comment = override_comment if override_comment
 293
 294       find_modifiers(comment, meth_obj) if comment
 295
 296 #        meth_obj.params = params
 297       meth_obj.start_collecting_tokens
 298       meth_obj.add_token(RDoc::RubyToken::Token.new(1,1).set_text(body_text))
 299       meth_obj.comment = mangle_comment(comment)
 300     when %r{((?>/\*.*?\*/\s*))^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
 301       comment = $1
 302       find_body(class_name, $2, meth_obj, body, true)
 303       find_modifiers(comment, meth_obj)
 304       meth_obj.comment = mangle_comment(comment) + meth_obj.comment
 305     when %r{^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
 306       unless find_body(class_name, $1, meth_obj, body, true)
 307         warn "No definition for #{meth_name}" unless @options.quiet
 308         return false
 309       end
 310     else
 311
 312       # No body, but might still have an override comment
 313       comment = find_override_comment(class_name, meth_obj.name)
 314
 315       if comment
 316         find_modifiers(comment, meth_obj)
 317         meth_obj.comment = mangle_comment(comment)
 318       else
 319         warn "No definition for #{meth_name}" unless @options.quiet
 320         return false
 321       end
 322     end
 323     true
 324   end
 325
 326   def find_class(raw_name, name)
 327     unless @classes[raw_name]
 328       if raw_name =~ /^rb_m/
 329         container = @top_level.add_module RDoc::NormalModule, name
 330       else
 331         container = @top_level.add_class RDoc::NormalClass, name, nil
 332       end
 333
 334       container.record_location @top_level
 335       @classes[raw_name] = container
 336     end
 337     @classes[raw_name]
 338   end
 339
 340   ##
 341   # Look for class or module documentation above Init_+class_name+(void),
 342   # in a Document-class +class_name+ (or module) comment or above an
 343   # rb_define_class (or module).  If a comment is supplied above a matching
 344   # Init_ and a rb_define_class the Init_ comment is used.
 345   #
 346   #   /*
 347   #    * This is a comment for Foo
 348   #    */
 349   #   Init_Foo(void) {
 350   #       VALUE cFoo = rb_define_class("Foo", rb_cObject);
 351   #   }
 352   #
 353   #   /*
 354   #    * Document-class: Foo
 355   #    * This is a comment for Foo
 356   #    */
 357   #   Init_foo(void) {
 358   #       VALUE cFoo = rb_define_class("Foo", rb_cObject);
 359   #   }
 360   #
 361   #   /*
 362   #    * This is a comment for Foo
 363   #    */
 364   #   VALUE cFoo = rb_define_class("Foo", rb_cObject);
 365
 366   def find_class_comment(class_name, class_meth)
 367     comment = nil
 368     if @content =~ %r{((?>/\*.*?\*/\s+))
 369                    (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then
 370       comment = $1
 371     elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
 372       comment = $1
 373     else
 374       if @content =~ /rb_define_(class|module)/m then
 375         class_name = class_name.split("::").last
 376         comments = []
 377         @content.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index do |chunk, index|
 378           comments[index] = chunk
 379           if chunk =~ /rb_define_(class|module).*?"(#{class_name})"/m then
 380             comment = comments[index-1]
 381             break
 382           end
 383         end
 384       end
 385     end
 386     class_meth.comment = mangle_comment(comment) if comment
 387   end
 388
 389   ##
 390   # Finds a comment matching +type+ and +const_name+ either above the
 391   # comment or in the matching Document- section.
 392
 393   def find_const_comment(type, const_name)
 394     if @content =~ %r{((?>^\s*/\*.*?\*/\s+))
 395                    rb_define_#{type}\((?:\s*(\w+),)?\s*"#{const_name}"\s*,.*?\)\s*;}xmi
 396       $1
 397     elsif @content =~ %r{Document-(?:const|global|variable):\s#{const_name}\s*?\n((?>.*?\*/))}m
 398       $1
 399     else
 400       ''
 401     end
 402   end
 403
 404   ##
 405   # If the comment block contains a section that looks like:
 406   #
 407   #    call-seq:
 408   #        Array.new
 409   #        Array.new(10)
 410   #
 411   # use it for the parameters.
 412
 413   def find_modifiers(comment, meth_obj)
 414     if comment.sub!(/:nodoc:\s*^\s*\*?\s*$/m, '') or
 415        comment.sub!(/\A\/\*\s*:nodoc:\s*\*\/\Z/, '')
 416       meth_obj.document_self = false
 417     end
 418     if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '') or
 419        comment.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '')
 420       seq = $1
 421       seq.gsub!(/^\s*\*\s*/, '')
 422       meth_obj.call_seq = seq
 423     end
 424   end
 425
 426   def find_override_comment(class_name, meth_name)
 427     name = Regexp.escape(meth_name)
 428     if @content =~ %r{Document-method:\s+#{class_name}(?:\.|::|#)#{name}\s*?\n((?>.*?\*/))}m then
 429       $1
 430     elsif @content =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m then
 431       $1
 432     end
 433   end
 434
 435   def handle_attr(var_name, attr_name, reader, writer)
 436     rw = ''
 437     if reader
 438       #@stats.num_methods += 1
 439       rw << 'R'
 440     end
 441     if writer
 442       #@stats.num_methods += 1
 443       rw << 'W'
 444     end
 445
 446     class_name = @known_classes[var_name]
 447
 448     return unless class_name
 449
 450     class_obj  = find_class(var_name, class_name)
 451
 452     if class_obj
 453       comment = find_attr_comment(attr_name)
 454       unless comment.empty?
 455         comment = mangle_comment(comment)
 456       end
 457       att = RDoc::Attr.new '', attr_name, rw, comment
 458       class_obj.add_attribute(att)
 459     end
 460   end
 461
 462   def handle_class_module(var_name, class_mod, class_name, parent, in_module)
 463     parent_name = @known_classes[parent] || parent
 464
 465     if in_module
 466       enclosure = @classes[in_module] || @@enclosure_classes[in_module]
 467       unless enclosure
 468         if enclosure = @known_classes[in_module]
 469           handle_class_module(in_module, (/^rb_m/ =~ in_module ? "module" : "class"),
 470                               enclosure, nil, nil)
 471           enclosure = @classes[in_module]
 472         end
 473       end
 474       unless enclosure
 475         warn("Enclosing class/module '#{in_module}' for " +
 476               "#{class_mod} #{class_name} not known")
 477         return
 478       end
 479     else
 480       enclosure = @top_level
 481     end
 482
 483     if class_mod == "class" then
 484       full_name = enclosure.full_name.to_s + "::#{class_name}"
 485       if @content =~ %r{Document-class:\s+#{full_name}\s*<\s+([:,\w]+)} then
 486         parent_name = $1
 487       end
 488       cm = enclosure.add_class RDoc::NormalClass, class_name, parent_name
 489       @stats.add_class cm
 490     else
 491       cm = enclosure.add_module RDoc::NormalModule, class_name
 492       @stats.add_module cm
 493     end
 494
 495     cm.record_location(enclosure.toplevel)
 496
 497     find_class_comment(cm.full_name, cm)
 498     @classes[var_name] = cm
 499     @@enclosure_classes[var_name] = cm
 500     @known_classes[var_name] = cm.full_name
 501   end
 502
 503   ##
 504   # Adds constant comments.  By providing some_value: at the start ofthe
 505   # comment you can override the C value of the comment to give a friendly
 506   # definition.
 507   #
 508   #   /* 300: The perfect score in bowling */
 509   #   rb_define_const(cFoo, "PERFECT", INT2FIX(300);
 510   #
 511   # Will override +INT2FIX(300)+ with the value +300+ in the output RDoc.
 512   # Values may include quotes and escaped colons (\:).
 513
 514   def handle_constants(type, var_name, const_name, definition)
 515     #@stats.num_constants += 1
 516     class_name = @known_classes[var_name]
 517
 518     return unless class_name
 519
 520     class_obj  = find_class(var_name, class_name)
 521
 522     unless class_obj
 523       warn("Enclosing class/module '#{const_name}' for not known")
 524       return
 525     end
 526
 527     comment = find_const_comment(type, const_name)
 528
 529     # In the case of rb_define_const, the definition and comment are in
 530     # "/* definition: comment */" form.  The literal ':' and '\' characters
 531     # can be escaped with a backslash.
 532     if type.downcase == 'const' then
 533        elements = mangle_comment(comment).split(':')
 534        if elements.nil? or elements.empty? then
 535           con = RDoc::Constant.new(const_name, definition,
 536                                    mangle_comment(comment))
 537        else
 538           new_definition = elements[0..-2].join(':')
 539           if new_definition.empty? then # Default to literal C definition
 540              new_definition = definition
 541           else
 542              new_definition.gsub!("\:", ":")
 543              new_definition.gsub!("\\", '\\')
 544           end
 545           new_definition.sub!(/\A(\s+)/, '')
 546           new_comment = $1.nil? ? elements.last : "#{$1}#{elements.last.lstrip}"
 547           con = RDoc::Constant.new(const_name, new_definition,
 548                                    mangle_comment(new_comment))
 549        end
 550     else
 551        con = RDoc::Constant.new const_name, definition, mangle_comment(comment)
 552     end
 553
 554     class_obj.add_constant(con)
 555   end
 556
 557   ##
 558   # Removes #ifdefs that would otherwise confuse us
 559
 560   def handle_ifdefs_in(body)
 561     body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m, '\1')
 562   end
 563
 564   def handle_method(type, var_name, meth_name, meth_body, param_count,
 565                     source_file = nil)
 566     class_name = @known_classes[var_name]
 567
 568     return unless class_name
 569
 570     class_obj = find_class var_name, class_name
 571
 572     if class_obj then
 573       if meth_name == "initialize" then
 574         meth_name = "new"
 575         type = "singleton_method"
 576       end
 577
 578       meth_obj = RDoc::AnyMethod.new '', meth_name
 579       meth_obj.singleton = %w[singleton_method module_function].include? type
 580
 581       p_count = (Integer(param_count) rescue -1)
 582
 583       if p_count < 0
 584         meth_obj.params = "(...)"
 585       elsif p_count == 0
 586         meth_obj.params = "()"
 587       else
 588         meth_obj.params = "(" + (1..p_count).map{|i| "p#{i}"}.join(", ") + ")"
 589       end
 590
 591       if source_file then
 592         file_name = File.join(@file_dir, source_file)
 593         body = (@@known_bodies[source_file] ||= File.read(file_name))
 594       else
 595         body = @content
 596       end
 597
 598       if find_body(class_name, meth_body, meth_obj, body) and meth_obj.document_self then
 599         class_obj.add_method meth_obj
 600         @stats.add_method meth_obj
 601       end
 602     end
 603   end
 604
 605   def handle_tab_width(body)
 606     if /\t/ =~ body
 607       tab_width = @options.tab_width
 608       body.split(/\n/).map do |line|
 609         1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
 610         line
 611       end .join("\n")
 612     else
 613       body
 614     end
 615   end
 616
 617   ##
 618   # Remove the /*'s and leading asterisks from C comments
 619
 620   def mangle_comment(comment)
 621     comment.sub!(%r{/\*+}) { " " * $&.length }
 622     comment.sub!(%r{\*+/}) { " " * $&.length }
 623     comment.gsub!(/^[ \t]*\*/m) { " " * $&.length }
 624     comment
 625   end
 626
 627   ##
 628   # Removes lines that are commented out that might otherwise get picked up
 629   # when scanning for classes and methods
 630
 631   def remove_commented_out_lines
 632     @content.gsub!(%r{//.*rb_define_}, '//')
 633   end
 634
 635   def remove_private_comments(comment)
 636      comment.gsub!(/\/?\*--\n(.*?)\/?\*\+\+/m, '')
 637      comment.sub!(/\/?\*--\n.*/m, '')
 638   end
 639
 640   ##
 641   # Extract the classes/modules and methods from a C file and return the
 642   # corresponding top-level object
 643
 644   def scan
 645     remove_commented_out_lines
 646     do_classes
 647     do_constants
 648     do_methods
 649     do_includes
 650     do_aliases
 651     @top_level
 652   end
 653
 654   def warn(msg)
 655     $stderr.puts
 656     $stderr.puts msg
 657     $stderr.flush
 658   end
 659
 660 end
 661