D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
opt
/
alt
/
ruby18
/
lib64
/
ruby
/
1.8
/
rdoc
/
Filename :
code_objects.rb
back
Copy
# 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