summaryrefslogtreecommitdiff
path: root/lib/rdoc/code_objects.rb
blob: 58adc5a3517ca235d4a8db0f3744544906c54c77 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
# We represent the various high-level code constructs that appear
# in Ruby programs: classes, modules, methods, and so on.

require 'rdoc/tokenstream'

module RDoc

  ##
  # We contain the common stuff for contexts (which are containers) and other
  # elements (methods, attributes and so on)

  class CodeObject

    attr_accessor :parent

    # We are the model of the code, but we know that at some point
    # we will be worked on by viewers. By implementing the Viewable
    # protocol, viewers can associated themselves with these objects.

    attr_accessor :viewer

    # are we done documenting (ie, did we come across a :enddoc:)?

    attr_accessor :done_documenting

    # Which section are we in

    attr_accessor :section

    # do we document ourselves?

    attr_reader :document_self

    def initialize
      @document_self = true
      @document_children = true
      @force_documentation = false
      @done_documenting = false
    end

    def document_self=(val)
      @document_self = val
      if !val
	remove_methods_etc
      end
    end

    # set and cleared by :startdoc: and :enddoc:, this is used to toggle
    # the capturing of documentation
    def start_doc
      @document_self = true
      @document_children = true
    end

    def stop_doc
      @document_self = false
      @document_children = false
    end

    # do we document ourselves and our children

    attr_reader :document_children

    def document_children=(val)
      @document_children = val
      if !val
	remove_classes_and_modules
      end
    end

    # Do we _force_ documentation, even is we wouldn't normally show the entity
    attr_accessor :force_documentation

    # Default callbacks to nothing, but this is overridden for classes
    # and modules
    def remove_classes_and_modules
    end

    def remove_methods_etc
    end

    # Access the code object's comment
    attr_reader :comment

    # Update the comment, but don't overwrite a real comment with an empty one
    def comment=(comment)
      @comment = comment unless comment.empty?
    end

    # There's a wee trick we pull. Comment blocks can have directives that
    # override the stuff we extract during the parse. So, we have a special
    # class method, attr_overridable, that lets code objects list
    # those directives. Wehn a comment is assigned, we then extract
    # out any matching directives and update our object

    def self.attr_overridable(name, *aliases)
      @overridables ||= {}

      attr_accessor name

      aliases.unshift name
      aliases.each do |directive_name|
        @overridables[directive_name.to_s] = name
      end
    end

  end

  ##
  # A Context is something that can hold modules, classes, methods,
  # attributes, aliases, requires, and includes. Classes, modules, and files
  # are all Contexts.

  class Context < CodeObject

    attr_reader :aliases
    attr_reader :attributes
    attr_reader :constants
    attr_reader :current_section
    attr_reader :in_files
    attr_reader :includes
    attr_reader :method_list
    attr_reader :name
    attr_reader :requires
    attr_reader :sections
    attr_reader :visibility

    class Section
      attr_reader :title, :comment, :sequence

      @@sequence = "SEC00000"

      def initialize(title, comment)
        @title = title
        @@sequence.succ!
        @sequence = @@sequence.dup
        @comment = nil
        set_comment(comment)
      end

      def ==(other)
        self.class === other and @sequence == other.sequence
      end

      def inspect
        "#<%s:0x%x %s %p>" % [
          self.class, object_id,
          @sequence, title
        ]
      end

      ##
      # Set the comment for this section from the original comment block If
      # the first line contains :section:, strip it and use the rest.
      # Otherwise remove lines up to the line containing :section:, and look
      # for those lines again at the end and remove them. This lets us write
      #
      #   # ---------------------
      #   # :SECTION: The title
      #   # The body
      #   # ---------------------

      def set_comment(comment)
        return unless comment

        if comment =~ /^#[ \t]*:section:.*\n/
          start = $`
          rest = $'

          if start.empty?
            @comment = rest
          else
            @comment = rest.sub(/#{start.chomp}\Z/, '')
          end
        else
          @comment = comment
        end
        @comment = nil if @comment.empty?
      end

    end

    def initialize
      super

      @in_files = []

      @name    ||= "unknown"
      @comment ||= ""
      @parent  = nil
      @visibility = :public

      @current_section = Section.new(nil, nil)
      @sections = [ @current_section ]

      initialize_methods_etc
      initialize_classes_and_modules
    end

    ##
    # map the class hash to an array externally

    def classes
      @classes.values
    end

    ##
    # map the module hash to an array externally

    def modules
      @modules.values
    end

    ##
    # Change the default visibility for new methods

    def ongoing_visibility=(vis)
      @visibility = vis
    end

    ##
    # Yields Method and Attr entries matching the list of names in +methods+.
    # Attributes are only returned when +singleton+ is false.

    def methods_matching(methods, singleton = false)
      count = 0

      @method_list.each do |m|
        if methods.include? m.name and m.singleton == singleton then
          yield m
          count += 1
        end
      end

      return if count == methods.size || singleton

      # perhaps we need to look at attributes

      @attributes.each do |a|
        yield a if methods.include? a.name
      end
    end

    ##
    # Given an array +methods+ of method names, set the visibility of the
    # corresponding AnyMethod object

    def set_visibility_for(methods, vis, singleton = false)
      methods_matching methods, singleton do |m|
        m.visibility = vis
      end
    end

    ##
    # Record the file that we happen to find it in

    def record_location(toplevel)
      @in_files << toplevel unless @in_files.include?(toplevel)
    end

    # Return true if at least part of this thing was defined in +file+
    def defined_in?(file)
      @in_files.include?(file)
    end

    def add_class(class_type, name, superclass)
      add_class_or_module(@classes, class_type, name, superclass)
    end

    def add_module(class_type, name)
      add_class_or_module(@modules, class_type, name, nil)
    end

    def add_method(a_method)
      puts "Adding #@visibility method #{a_method.name} to #@name" if $DEBUG_RDOC
      a_method.visibility = @visibility
      add_to(@method_list, a_method)
    end

    def add_attribute(an_attribute)
      add_to(@attributes, an_attribute)
    end

    def add_alias(an_alias)
      meth = find_instance_method_named(an_alias.old_name)
      if meth
        new_meth = AnyMethod.new(an_alias.text, an_alias.new_name)
        new_meth.is_alias_for = meth
        new_meth.singleton    = meth.singleton
        new_meth.params       = meth.params
        new_meth.comment = "Alias for \##{meth.name}"
        meth.add_alias(new_meth)
        add_method(new_meth)
      else
        add_to(@aliases, an_alias)
      end
    end

    def add_include(an_include)
      add_to(@includes, an_include)
    end

    def add_constant(const)
      add_to(@constants, const)
    end

    # Requires always get added to the top-level (file) context
    def add_require(a_require)
      if TopLevel === self then
        add_to @requires, a_require
      else
        parent.add_require a_require
      end
    end

    def add_class_or_module(collection, class_type, name, superclass=nil)
      cls = collection[name]
      if cls
        puts "Reusing class/module #{name}" if $DEBUG_RDOC
      else
        cls = class_type.new(name, superclass)
        puts "Adding class/module #{name} to #@name" if $DEBUG_RDOC
#        collection[name] = cls if @document_self  && !@done_documenting
        collection[name] = cls if !@done_documenting
        cls.parent = self
        cls.section = @current_section
      end
      cls
    end

    def add_to(array, thing)
      array << thing if @document_self and not @done_documenting
      thing.parent = self
      thing.section = @current_section
    end

    # If a class's documentation is turned off after we've started
    # collecting methods etc., we need to remove the ones
    # we have

    def remove_methods_etc
      initialize_methods_etc
    end

    def initialize_methods_etc
      @method_list = []
      @attributes  = []
      @aliases     = []
      @requires    = []
      @includes    = []
      @constants   = []
    end

    # and remove classes and modules when we see a :nodoc: all
    def remove_classes_and_modules
      initialize_classes_and_modules
    end

    def initialize_classes_and_modules
      @classes     = {}
      @modules     = {}
    end

    # Find a named module
    def find_module_named(name)
      return self if self.name == name
      res = @modules[name] || @classes[name]
      return res if res
      find_enclosing_module_named(name)
    end

    # find a module at a higher scope
    def find_enclosing_module_named(name)
      parent && parent.find_module_named(name)
    end

    # Iterate over all the classes and modules in
    # this object

    def each_classmodule
      @modules.each_value {|m| yield m}
      @classes.each_value {|c| yield c}
    end

    def each_method
      @method_list.each {|m| yield m}
    end

    def each_attribute 
      @attributes.each {|a| yield a}
    end

    def each_constant
      @constants.each {|c| yield c}
    end

    # Return the toplevel that owns us

    def toplevel
      return @toplevel if defined? @toplevel
      @toplevel = self
      @toplevel = @toplevel.parent until TopLevel === @toplevel
      @toplevel
    end

    # allow us to sort modules by name
    def <=>(other)
      name <=> other.name
    end

    ##
    # Look up +symbol+.  If +method+ is non-nil, then we assume the symbol
    # references a module that contains that method.

    def find_symbol(symbol, method = nil)
      result = nil

      case symbol
      when /^::(.*)/ then
        result = toplevel.find_symbol($1)
      when /::/ then
        modules = symbol.split(/::/)

        unless modules.empty? then
          module_name = modules.shift
          result = find_module_named(module_name)
          if result then
            modules.each do |name|
              result = result.find_module_named(name)
              break unless result
            end
          end
        end

      else
        # if a method is specified, then we're definitely looking for
        # a module, otherwise it could be any symbol
        if method
          result = find_module_named(symbol)
        else
          result = find_local_symbol(symbol)
          if result.nil?
            if symbol =~ /^[A-Z]/
              result = parent
              while result && result.name != symbol
                result = result.parent
              end
            end
          end
        end
      end

      if result and method then
        fail unless result.respond_to? :find_local_symbol
        result = result.find_local_symbol(method)
      end

      result
    end

    def find_local_symbol(symbol)
      res = find_method_named(symbol) ||
            find_constant_named(symbol) ||
            find_attribute_named(symbol) ||
            find_module_named(symbol) ||
            find_file_named(symbol)
    end

    # Handle sections

    def set_current_section(title, comment)
      @current_section = Section.new(title, comment)
      @sections << @current_section
    end

    private

    # Find a named method, or return nil
    def find_method_named(name)
      @method_list.find {|meth| meth.name == name}
    end

    # Find a named instance method, or return nil
    def find_instance_method_named(name)
      @method_list.find {|meth| meth.name == name && !meth.singleton}
    end

    # Find a named constant, or return nil
    def find_constant_named(name)
      @constants.find {|m| m.name == name}
    end

    # Find a named attribute, or return nil
    def find_attribute_named(name)
      @attributes.find {|m| m.name == name}
    end

    ##
    # Find a named file, or return nil

    def find_file_named(name)
      toplevel.class.find_file_named(name)
    end

  end

  ##
  # A TopLevel context is a source file

  class TopLevel < Context
    attr_accessor :file_stat
    attr_accessor :file_relative_name
    attr_accessor :file_absolute_name
    attr_accessor :diagram

    @@all_classes = {}
    @@all_modules = {}
    @@all_files   = {}

    def self.reset
      @@all_classes = {}
      @@all_modules = {}
      @@all_files   = {}
    end

    def initialize(file_name)
      super()
      @name = "TopLevel"
      @file_relative_name    = file_name
      @file_absolute_name    = file_name
      @file_stat             = File.stat(file_name)
      @diagram               = nil
      @@all_files[file_name] = self
    end

    def file_base_name
      File.basename @file_absolute_name
    end

    def full_name
      nil
    end

    ##
    # Adding a class or module to a TopLevel is special, as we only want one
    # copy of a particular top-level class. For example, if both file A and
    # file B implement class C, we only want one ClassModule object for C.
    # This code arranges to share classes and modules between files.

    def add_class_or_module(collection, class_type, name, superclass)
      cls = collection[name]

      if cls
        puts "Reusing class/module #{name}" #if $DEBUG_RDOC
      else
        if class_type == NormalModule
          all = @@all_modules
        else
          all = @@all_classes
        end

        cls = all[name]

        if !cls
          cls = class_type.new(name, superclass)
          all[name] = cls unless @done_documenting
        end

        puts "Adding class/module #{name} to #{@name}" if $DEBUG_RDOC

        collection[name] = cls unless @done_documenting

        cls.parent = self
      end

      cls
    end

    def self.all_classes_and_modules
      @@all_classes.values + @@all_modules.values
    end

    def self.find_class_named(name)
     @@all_classes.each_value do |c|
        res = c.find_class_named(name) 
        return res if res
      end
      nil
    end

    def self.find_file_named(name)
      @@all_files[name]
    end

    def find_local_symbol(symbol)
      find_class_or_module_named(symbol) || super
    end

    def find_class_or_module_named(symbol)
      @@all_classes.each_value {|c| return c if c.name == symbol}
      @@all_modules.each_value {|m| return m if m.name == symbol}
      nil
    end

    ##
    # Find a named module

    def find_module_named(name)
      find_class_or_module_named(name) || find_enclosing_module_named(name)
    end

  end

  ##
  # ClassModule is the base class for objects representing either a class or a
  # module.

  class ClassModule < Context

    attr_reader   :superclass
    attr_accessor :diagram

    def initialize(name, superclass = nil)
      @name       = name
      @diagram    = nil
      @superclass = superclass
      @comment    = ""
      super()
    end

    # Return the fully qualified name of this class or module
    def full_name
      if @parent && @parent.full_name
        @parent.full_name + "::" + @name
      else
        @name
      end
    end

    def http_url(prefix)
      path = full_name.split("::")
      File.join(prefix, *path) + ".html"
    end

    # Return +true+ if this object represents a module
    def is_module?
      false
    end

    # to_s is simply for debugging
    def to_s
      res = self.class.name + ": " + @name 
      res << @comment.to_s
      res << super
      res
    end

    def find_class_named(name)
      return self if full_name == name
      @classes.each_value {|c| return c if c.find_class_named(name) }
      nil
    end
  end

  ##
  # Anonymous classes

  class AnonClass < ClassModule
  end

  ##
  # Normal classes

  class NormalClass < ClassModule

    def inspect
      superclass = @superclass ? " < #{@superclass}" : nil
      "<%s:0x%x class %s%s includes: %p attributes: %p methods: %p aliases: %p>" % [
        self.class, object_id,
        @name, superclass, @includes, @attributes, @method_list, @aliases
      ]
    end

  end

  ##
  # Singleton classes

  class SingleClass < ClassModule
  end

  ##
  # Module

  class NormalModule < ClassModule

    def comment=(comment)
      return if comment.empty?
      comment = @comment << "# ---\n" << comment unless @comment.empty?

      super
    end

    def inspect
      "#<%s:0x%x module %s includes: %p attributes: %p methods: %p aliases: %p>" % [
        self.class, object_id,
        @name, @includes, @attributes, @method_list, @aliases
      ]
    end

    def is_module?
      true
    end

  end

  ##
  # AnyMethod is the base class for objects representing methods

  class AnyMethod < CodeObject

    attr_accessor :name
    attr_accessor :visibility
    attr_accessor :block_params
    attr_accessor :dont_rename_initialize
    attr_accessor :singleton
    attr_reader :text

    # list of other names for this method
    attr_reader   :aliases

    # method we're aliasing
    attr_accessor :is_alias_for

    attr_overridable :params, :param, :parameters, :parameter

    attr_accessor :call_seq

    include TokenStream

    def initialize(text, name)
      super()
      @text = text
      @name = name
      @token_stream  = nil
      @visibility    = :public
      @dont_rename_initialize = false
      @block_params  = nil
      @aliases       = []
      @is_alias_for  = nil
      @comment = ""
      @call_seq = nil
    end

    def <=>(other)
      @name <=> other.name
    end

    def add_alias(method)
      @aliases << method
    end

    def inspect
      alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
      "#<%s:0x%x %s%s%s (%s)%s>" % [
        self.class, object_id,
        @parent.name,
        singleton ? '::' : '#',
        name,
        visibility,
        alias_for,
      ]
    end

    def param_seq
      p = params.gsub(/\s*\#.*/, '')
      p = p.tr("\n", " ").squeeze(" ")
      p = "(" + p + ")" unless p[0] == ?(

      if (block = block_params)
        # If this method has explicit block parameters, remove any
        # explicit &block
$stderr.puts p
        p.sub!(/,?\s*&\w+/)
$stderr.puts p

        block.gsub!(/\s*\#.*/, '')
        block = block.tr("\n", " ").squeeze(" ")
        if block[0] == ?(
          block.sub!(/^\(/, '').sub!(/\)/, '')
        end
        p << " {|#{block}| ...}"
      end
      p
    end

    def to_s
      res = self.class.name + ": " + @name + " (" + @text + ")\n"
      res << @comment.to_s
      res
    end

  end

  ##
  # GhostMethod represents a method referenced only by a comment

  class GhostMethod < AnyMethod
  end

  ##
  # MetaMethod represents a meta-programmed method

  class MetaMethod < AnyMethod
  end

  ##
  # Represent an alias, which is an old_name/ new_name pair associated with a
  # particular context

  class Alias < CodeObject

    attr_accessor :text, :old_name, :new_name, :comment

    def initialize(text, old_name, new_name, comment)
      super()
      @text = text
      @old_name = old_name
      @new_name = new_name
      self.comment = comment
    end

    def inspect
      "#<%s:0x%x %s.alias_method %s, %s>" % [
        self.class, object_id,
        parent.name, @old_name, @new_name,
      ]
    end

    def to_s
      "alias: #{self.old_name} ->  #{self.new_name}\n#{self.comment}"
    end

  end

  ##
  # Represent a constant

  class Constant < CodeObject
    attr_accessor :name, :value

    def initialize(name, value, comment)
      super()
      @name = name
      @value = value
      self.comment = comment
    end
  end

  ##
  # Represent attributes

  class Attr < CodeObject
    attr_accessor :text, :name, :rw, :visibility

    def initialize(text, name, rw, comment)
      super()
      @text = text
      @name = name
      @rw = rw
      @visibility = :public
      self.comment = comment
    end

    def <=>(other)
      self.name <=> other.name
    end

    def inspect
      attr = case rw
             when 'RW' then :attr_accessor
             when 'R'  then :attr_reader
             when 'W'  then :attr_writer
             else
               " (#{rw})"
             end

      "#<%s:0x%x %s.%s :%s>" % [
        self.class, object_id,
        @parent.name, attr, @name,
      ]
    end

    def to_s
      "attr: #{self.name} #{self.rw}\n#{self.comment}"
    end

  end

  ##
  # A required file

  class Require < CodeObject
    attr_accessor :name

    def initialize(name, comment)
      super()
      @name = name.gsub(/'|"/, "") #'
      self.comment = comment
    end

    def inspect
      "#<%s:0x%x require '%s' in %s>" % [
        self.class,
        object_id,
        @name,
        @parent.file_base_name,
      ]
    end

  end

  ##
  # An included module

  class Include < CodeObject

    attr_accessor :name

    def initialize(name, comment)
      super()
      @name = name
      self.comment = comment

    end

    def inspect
      "#<%s:0x%x %s.include %s>" % [
        self.class,
        object_id,
        @parent.name,
        @name,
      ]
    end

  end

end