shoesgem 0.1424.0

data/shoes/ruby/lib/rdoc/code_objects.rb

@@ -0,0 +1,1061 @@
+# 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
+
+    def parent_file_name
+      @parent ? @parent.file_base_name : '(unknown)'
+    end
+
+    def parent_name
+      @parent ? @parent.name : '(unknown)'
+    end
+
+    # 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
+
+    ##
+    # return the classes Hash (only to be used internally)
+
+    def classes_hash
+      @classes
+    end
+    protected :classes_hash
+
+    ##
+    # return the modules Hash (only to be used internally)
+
+    def modules_hash
+      @modules
+    end
+    protected :modules_hash
+
+    ##
+    # 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)
+      klass = add_class_or_module @classes, class_type, name, superclass
+
+      #
+      # If the parser encounters Container::Item before encountering
+      # Container, then it assumes that Container is a module.  This
+      # may not be the case, so remove Container from the module list
+      # if present and transfer any contained classes and modules to
+      # the new class.
+      #
+      mod = @modules.delete(name)
+
+      if mod then
+        klass.classes_hash.update(mod.classes_hash)
+        klass.modules_hash.update(mod.modules_hash)
+        klass.method_list.concat(mod.method_list)
+      end
+
+      return klass
+    end
+
+    def add_module(class_type, name)
+      add_class_or_module(@modules, class_type, name, nil)
+    end
+
+    def add_method(a_method)
+      a_method.visibility = @visibility
+      add_to(@method_list, a_method)
+
+      unmatched_alias_list = @unmatched_alias_lists[a_method.name]
+      if unmatched_alias_list then
+        unmatched_alias_list.each do |unmatched_alias|
+          add_alias_impl unmatched_alias, a_method
+          @aliases.delete unmatched_alias
+        end
+
+        @unmatched_alias_lists.delete a_method.name
+      end
+    end
+
+    def add_attribute(an_attribute)
+      add_to(@attributes, an_attribute)
+    end
+
+    def add_alias_impl(an_alias, 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)
+    end
+    
+    def add_alias(an_alias)
+      meth = find_instance_method_named(an_alias.old_name)
+
+      if meth then
+        add_alias_impl(an_alias, meth)
+      else
+        add_to(@aliases, an_alias)
+        unmatched_alias_list = @unmatched_alias_lists[an_alias.old_name] ||= []
+        unmatched_alias_list.push(an_alias)
+      end
+
+      an_alias
+    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 then
+        cls.superclass = superclass unless cls.module?
+        puts "Reusing class/module #{name}" if $DEBUG_RDOC
+      else
+        cls = class_type.new(name, superclass)
+#        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   = []
+
+      # This Hash maps a method name to a list of unmatched
+      # aliases (aliases of a method not yet encountered).
+      @unmatched_alias_lists = {}
+    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)
+      # First check the enclosed modules, then check the module itself,
+      # then check the enclosing modules (this mirrors the check done by
+      # the Ruby parser)
+      res = @modules[name] || @classes[name]
+      return res if res
+      return self if self.name == name
+      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 then
+        cls.superclass = superclass unless cls.module?
+        puts "Reusing class/module #{cls.full_name}" if $DEBUG_RDOC
+      else
+        if class_type == NormalModule then
+          all = @@all_modules
+        else
+          all = @@all_classes
+        end
+
+        cls = all[name]
+
+        if !cls then
+          cls = class_type.new name, superclass
+          all[name] = cls unless @done_documenting
+        else
+          # If the class has been encountered already, check that its
+          # superclass has been set (it may not have been, depending on
+          # the context in which it was encountered).
+          if class_type == NormalClass
+            if !cls.superclass then
+              cls.superclass = superclass
+            end
+          end
+        end
+
+        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
+
+    def inspect
+      "#<%s:0x%x %p modules: %p classes: %p>" % [
+        self.class, object_id,
+        file_base_name,
+        @modules.map { |n,m| m },
+        @classes.map { |n,c| c }
+      ]
+    end
+
+  end
+
+  ##
+  # ClassModule is the base class for objects representing either a class or a
+  # module.
+
+  class ClassModule < Context
+
+    attr_accessor :diagram
+
+    def initialize(name, superclass = nil)
+      @name       = name
+      @diagram    = nil
+      @superclass = superclass
+      @comment    = ""
+      super()
+    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
+
+    ##
+    # 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
+
+    ##
+    # Does this object represent a module?
+
+    def module?
+      false
+    end
+
+    ##
+    # Get the superclass of this class.  Attempts to retrieve the superclass'
+    # real name by following module nesting.
+
+    def superclass
+      raise NoMethodError, "#{full_name} is a module" if module?
+
+      scope = self
+
+      begin
+        superclass = scope.classes.find { |c| c.name == @superclass }
+
+        return superclass.full_name if superclass
+        scope = scope.parent
+      end until scope.nil? or TopLevel === scope
+
+      @superclass
+    end
+
+    ##
+    # Set the superclass of this class
+
+    def superclass=(superclass)
+      raise NoMethodError, "#{full_name} is a module" if module?
+
+      if @superclass.nil? or @superclass == 'Object' then
+        @superclass = superclass 
+      end
+    end
+
+    def to_s
+      "#{self.class}: #{@name} #{@comment} #{super}"
+    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 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
+      params = params.gsub(/\s*\#.*/, '')
+      params = params.tr("\n", " ").squeeze(" ")
+      params = "(#{params})" unless p[0] == ?(
+
+      if block = block_params then # yes, =
+        # If this method has explicit block parameters, remove any explicit
+        # &block
+        params.sub!(/,?\s*&\w+/)
+
+        block.gsub!(/\s*\#.*/, '')
+        block = block.tr("\n", " ").squeeze(" ")
+        if block[0] == ?(
+          block.sub!(/^\(/, '').sub!(/\)/, '')
+        end
+        params << " { |#{block}| ... }"
+      end
+
+      params
+    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_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