summaryrefslogtreecommitdiff
path: root/ruby_1_8_6/lib/rdoc/code_objects.rb
diff options
context:
space:
mode:
Diffstat (limited to 'ruby_1_8_6/lib/rdoc/code_objects.rb')
-rw-r--r--ruby_1_8_6/lib/rdoc/code_objects.rb765
1 files changed, 765 insertions, 0 deletions
diff --git a/ruby_1_8_6/lib/rdoc/code_objects.rb b/ruby_1_8_6/lib/rdoc/code_objects.rb
new file mode 100644
index 0000000000..d6c4f1bdb9
--- /dev/null
+++ b/ruby_1_8_6/lib/rdoc/code_objects.rb
@@ -0,0 +1,765 @@
+# 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 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
+
+ def initialize
+ @document_self = true
+ @document_children = true
+ @force_documentation = false
+ @done_documenting = false
+ 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 CodeObject.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 :name, :method_list, :attributes, :aliases, :constants
+ attr_reader :requires, :includes, :in_files, :visibility
+
+ attr_reader :sections
+
+ class Section
+ attr_reader :title, :comment, :sequence
+
+ @@sequence = "SEC00000"
+
+ def initialize(title, comment)
+ @title = title
+ @@sequence.succ!
+ @sequence = @@sequence.dup
+ set_comment(comment)
+ end
+
+ private
+
+ # 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 =~ /^.*?:section:.*$/
+ 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
+
+ # Given an array +methods+ of method names, set the
+ # visibility of the corresponding AnyMethod object
+
+ def set_visibility_for(methods, vis, singleton=false)
+ count = 0
+ @method_list.each do |m|
+ if methods.include?(m.name) && m.singleton == singleton
+ m.visibility = vis
+ count += 1
+ end
+ end
+
+ return if count == methods.size || singleton
+
+ # perhaps we need to look at attributes
+
+ @attributes.each do |a|
+ if methods.include?(a.name)
+ a.visibility = vis
+ count += 1
+ end
+ 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
+ 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 self.kind_of? TopLevel
+ 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
+ else
+ cls = class_type.new(name, superclass)
+ puts "Adding class/module #{name} to #@name" if $DEBUG
+# 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 && !@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 the given 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 /^::(.*)/
+ result = toplevel.find_symbol($1)
+ when /::/
+ modules = symbol.split(/::/)
+ unless modules.empty?
+ module_name = modules.shift
+ result = find_module_named(module_name)
+ if result
+ modules.each do |module_name|
+ result = result.find_module_named(module_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 && method
+ if !result.respond_to?(:find_local_symbol)
+ p result.name
+ p method
+ fail
+ end
+ 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)
+ 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
+
+ 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 = {}
+
+ def TopLevel::reset
+ @@all_classes = {}
+ @@all_modules = {}
+ 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
+ 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
+ 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
+ collection[name] = cls unless @done_documenting
+ cls.parent = self
+ end
+ cls
+ end
+
+ def TopLevel.all_classes_and_modules
+ @@all_classes.values + @@all_modules.values
+ end
+
+ def TopLevel.find_class_named(name)
+ @@all_classes.each_value do |c|
+ res = c.find_class_named(name)
+ return res if res
+ end
+ nil
+ 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
+ end
+
+ # Singleton classes
+ class SingleClass < ClassModule
+ end
+
+ # Module
+ class NormalModule < ClassModule
+ 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 :aliases # list of other names for this method
+ attr_accessor :is_alias_for # or a method we're aliasing
+
+ 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 to_s
+ res = self.class.name + ": " + @name + " (" + @text + ")\n"
+ res << @comment.to_s
+ res
+ 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 add_alias(method)
+ @aliases << method
+ end
+ 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 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 to_s
+ "attr: #{self.name} #{self.rw}\n#{self.comment}"
+ end
+
+ def <=>(other)
+ self.name <=> other.name
+ end
+ end
+
+ # a required file
+
+ class Require < CodeObject
+ attr_accessor :name
+
+ def initialize(name, comment)
+ super()
+ @name = name.gsub(/'|"/, "") #'
+ self.comment = comment
+ end
+
+ end
+
+ # an included module
+ class Include < CodeObject
+ attr_accessor :name
+
+ def initialize(name, comment)
+ super()
+ @name = name
+ self.comment = comment
+ end
+
+ end
+
+end