yard 0.2.1 → 0.2.2

data/lib/yard/code_objects/class_object.rb

@@ -0,0 +1,89 @@
+module YARD::CodeObjects
+  class ClassObject < NamespaceObject
+    attr_accessor :superclass
+    
+    def initialize(namespace, name, *args, &block)
+      super
+
+      if is_exception?
+        self.superclass ||= :Exception 
+      else
+        self.superclass ||= :Object unless P(namespace, name) == P(:Object)
+      end
+    end
+    
+    def is_exception?
+      inheritance_tree.reverse.any? {|o| BUILTIN_EXCEPTIONS_HASH.has_key? o.path }
+    end
+    
+    def inheritance_tree(include_mods = false)
+      list = [self] + (include_mods ? mixins : [])
+      if superclass.is_a? Proxy
+        list << superclass unless superclass == P(:Object)
+      elsif superclass.respond_to? :inheritance_tree
+        list += superclass.inheritance_tree
+      end
+      list
+    end
+    
+    def meths(opts = {})
+      opts = SymbolHash[:inherited => true].update(opts)
+      super(opts) + (opts[:inherited] ? inherited_meths(opts) : [])
+    end
+    
+    def inherited_meths(opts = {})
+      inheritance_tree[1..-1].inject([]) do |list, superclass|
+        if superclass.is_a?(Proxy)
+          list
+        else
+          list += superclass.meths(opts).reject do |o|
+            child(:name => o.name, :scope => o.scope) ||
+              list.find {|o2| o2.name == o.name && o2.scope == o.scope }
+          end
+        end
+      end
+    end
+    
+    def constants(opts = {})
+      opts = SymbolHash[:inherited => true].update(opts)
+      super(opts) + (opts[:inherited] ? inherited_constants : [])
+    end
+    
+    def inherited_constants
+      inheritance_tree[1..-1].inject([]) do |list, superclass|
+        if superclass.is_a?(Proxy)
+          list
+        else
+          list += superclass.constants.reject do |o|
+            child(:name => o.name) || list.find {|o2| o2.name == o.name }
+          end
+        end
+      end
+    end
+    
+    ##
+    # Sets the superclass of the object
+    # 
+    # @param [Base, Proxy, String, Symbol, nil] object the superclass value
+    def superclass=(object)
+      case object
+      when Base, Proxy, NilClass
+        @superclass = object
+      when String, Symbol
+        @superclass = Proxy.new(namespace, object)
+      else
+        raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol" 
+      end
+
+      if name == @superclass.name && namespace != YARD::Registry.root
+        @superclass = Proxy.new(namespace.namespace, object)
+      end
+      
+      if @superclass == self
+        msg = "superclass #{@superclass.inspect} cannot be the same as the subclass #{self}"
+        @superclass = P(:Object)
+        raise ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/yard/code_objects/class_variable_object.rb

@@ -0,0 +1,4 @@
+module YARD::CodeObjects
+  class ClassVariableObject < Base
+  end
+end

data/lib/yard/code_objects/constant_object.rb

@@ -0,0 +1,4 @@
+module YARD::CodeObjects
+  class ConstantObject < Base
+  end
+end

data/lib/yard/code_objects/method_object.rb

@@ -0,0 +1,51 @@
+module YARD::CodeObjects
+  class MethodObject < Base
+    attr_accessor :visibility, :scope, :explicit
+    
+    def initialize(namespace, name, scope = :instance) 
+      self.visibility = :public
+      self.scope = scope
+
+      super
+    end
+    
+    def scope=(v) @scope = v.to_sym end
+    def visibility=(v) @visibility = v.to_sym end
+      
+    def is_attribute?
+      namespace.attributes[scope].has_key? name.to_s.gsub(/=$/, '')
+    end
+      
+    def is_alias?
+      namespace.aliases.has_key? self
+    end
+    
+    def is_explicit?
+      explicit ? true : false
+    end
+    
+    def aliases
+      list = []
+      namespace.aliases.each do |o, aname| 
+        list << o if aname == name && o.scope == scope 
+      end
+      list
+    end
+    
+    def path
+      if !namespace || namespace.path == "" 
+        sep + super
+      else
+        super
+      end
+    end
+    
+    def name(prefix = false)
+      prefix && sep == ISEP ? sep + super().to_s : super()
+    end
+    
+    protected
+    
+    def sep; scope == :class ? super : ISEP end
+  end
+end

data/lib/yard/code_objects/module_object.rb

@@ -0,0 +1,4 @@
+module YARD::CodeObjects
+  class ModuleObject < NamespaceObject
+  end
+end

data/lib/yard/code_objects/namespace_object.rb

@@ -0,0 +1,88 @@
+module YARD::CodeObjects
+  class NamespaceObject < Base
+    attr_reader :children, :cvars, :meths, :constants, :mixins, :attributes, :aliases
+    
+    def initialize(namespace, name, *args, &block)
+      @children = CodeObjectList.new(self)
+      @mixins = CodeObjectList.new(self)
+      @attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
+      @aliases = {}
+      super
+    end
+    
+    def class_attributes
+      attributes[:class]
+    end
+    
+    def instance_attributes 
+      attributes[:instance]
+    end
+    
+    def child(opts = {})
+      if !opts.is_a?(Hash)
+        children.find {|o| o.name == opts.to_sym }
+      else
+        opts = SymbolHash[opts]
+        children.find do |obj| 
+          opts.each do |meth, value|
+            break false if obj[meth] != value
+          end
+        end
+      end
+    end
+    
+    def meths(opts = {})
+      opts = SymbolHash[
+        :visibility => [:public, :private, :protected],
+        :scope => [:class, :instance],
+        :included => true
+      ].update(opts)
+      
+      opts[:visibility] = [opts[:visibility]].flatten
+      opts[:scope] = [opts[:scope]].flatten
+
+      ourmeths = children.select do |o| 
+        o.is_a?(MethodObject) && 
+          opts[:visibility].include?(o.visibility) &&
+          opts[:scope].include?(o.scope)
+      end
+      
+      ourmeths + (opts[:included] ? included_meths(opts) : [])
+    end
+    
+    def included_meths(opts = {})
+      mixins.reverse.inject([]) do |list, mixin|
+        if mixin.is_a?(Proxy)
+          list
+        else
+          list += mixin.meths(opts).reject do |o| 
+            child(:name => o.name, :scope => o.scope) || 
+              list.find {|o2| o2.name == o.name && o2.scope == o.scope }
+          end
+        end
+      end
+    end
+    
+    def constants(opts = {})
+      opts = SymbolHash[:included => true].update(opts)
+      consts = children.select {|o| o.is_a? ConstantObject }
+      consts + (opts[:included] ? included_constants : [])
+    end
+    
+    def included_constants
+      mixins.reverse.inject([]) do |list, mixin|
+        if mixin.is_a?(Proxy)
+          list
+        else
+          list += mixin.constants.reject do |o| 
+            child(:name => o.name) || list.find {|o2| o2.name == o.name }
+          end
+        end
+      end
+    end
+    
+    def cvars 
+      children.select {|o| o.is_a? ClassVariableObject }
+    end
+  end
+end

data/lib/yard/code_objects/proxy.rb

@@ -0,0 +1,183 @@
+module YARD
+  module CodeObjects
+    class ProxyMethodError < NoMethodError; end
+
+    class Proxy    
+      def self.===(other) other.is_a?(self) end
+
+      attr_reader :namespace, :name
+      alias_method :parent, :namespace
+
+      # @raise ArgumentError if namespace is not a NamespaceObject
+      def initialize(namespace, name)
+        namespace = Registry.root if !namespace || namespace == :root
+        
+        if name =~ /^#{NSEP}/
+          namespace = Registry.root
+          name = name[2..-1]
+        end
+        
+        if name =~ /(?:#{NSEP}|#{ISEP})([^#{NSEP}#{ISEP}]+)$/
+          @orignamespace, @origname = namespace, name
+          @imethod = true if name.include? ISEP
+          namespace = $`.empty? ? Registry.root : Proxy.new(namespace, $`)
+          name = $1
+        end 
+
+        @name = name.to_sym
+        @namespace = namespace
+        
+        unless @namespace.is_a?(NamespaceObject) or @namespace.is_a?(Proxy)
+          raise ArgumentError, "Invalid namespace object: #{namespace}"
+        end
+        
+        # If the name begins with "::" (like "::String")
+        # this is definitely a root level object, so
+        # remove the namespace and attach it to the root
+        if @name =~ /^#{NSEP}/
+          @name.gsub!(/^#{NSEP}/, '')
+          @namespace = Registry.root
+        end
+      end
+      
+      def inspect
+        if obj = to_obj
+          obj.inspect
+        else
+          "P(#{path})"
+        end
+      end
+      
+      def path
+        if obj = to_obj
+          obj.path
+        else
+          if @namespace == Registry.root
+            (@imethod ? ISEP : "") + name.to_s
+          else
+            @origname || name.to_s
+          end
+        end
+      end
+      alias to_s path
+    
+      def is_a?(klass)
+        if obj = to_obj
+          obj.is_a?(klass)
+        else
+          self.class <= klass
+        end
+      end
+      
+      def ===(other)
+        if obj = to_obj
+          obj === other
+        else
+          self.class <= other.class
+        end
+      end
+      
+      def <=>(other)
+        if other.respond_to? :path
+          path <=> other.path
+        else
+          false
+        end
+      end
+      
+      def ==(other)
+        if other.respond_to? :path
+          path == other.path
+        else
+          false
+        end
+      end
+      
+      def class
+        if obj = to_obj
+          obj.class
+        else
+          Proxy
+        end
+      end
+      
+      def type
+        if obj = to_obj
+          obj.type
+        else
+          Registry.proxy_types[path] || :proxy
+        end
+      end
+      def type=(type) Registry.proxy_types[path] = type.to_sym end
+      
+      def instance_of?(klass)
+        self.class == klass
+      end
+      
+      def kind_of?(klass)
+        self.class <= klass
+      end
+
+      def object_id
+        if obj = to_obj
+          obj.object_id
+        else
+          nil
+        end
+      end
+      
+      def respond_to?(meth)
+        if obj = to_obj
+          obj.respond_to?(meth)
+        else
+          super
+        end
+      end
+
+      # Dispatches the method to the resolved object
+      # 
+      # @raise NoMethodError if the proxy cannot find the real object
+      def method_missing(meth, *args, &block)
+        if obj = to_obj
+          obj.__send__(meth, *args, &block)
+        else
+          log.warn "Load Order / Name Resolution Problem on #{path}:"
+          log.warn "-"
+          log.warn "Something is trying to access the object #{path} before it has been recognized."
+          log.warn "This error usually means that you need to modify the order in which you parse files"
+          log.warn "so that #{path} is parsed before methods or other objects attempt to access it."
+          log.warn "-"
+          log.warn "YARD will recover from this error and continue to parse but you *may* have problems"
+          log.warn "with your generated documentation. You should probably fix this."
+          log.warn "-"
+          begin 
+            super
+          rescue NoMethodError
+            raise ProxyMethodError, "Proxy cannot call method ##{meth} on object '#{path}'"
+          end
+        end
+      end
+    
+      private
+    
+      # Attempts to find the object that this unresolved object
+      # references by checking if any objects by this name are
+      # registered all the way up the namespace tree.
+      # 
+      # @return [Base, nil] the registered code object or nil
+      def to_obj
+        @obj ||= Registry.resolve(@namespace, @name)
+      end
+    end
+  end
+end
+
+# Shortcut for creating a YARD::CodeObjects::Proxy 
+# via a path
+# 
+# @see YARD::CodeObjects::Proxy
+# @see YARD::Registry::resolve
+def P(namespace, name = nil)
+  namespace, name = nil, namespace if name.nil?
+  YARD::Registry.resolve(namespace, name, true)
+end

data/lib/yard/code_objects/root_object.rb

@@ -0,0 +1,8 @@
+module YARD
+  module CodeObjects
+    class RootObject < ModuleObject
+      def path; "" end
+      def inspect; "#<yardoc root>" end
+    end
+  end
+end

data/lib/yard/core_ext/file.rb

@@ -0,0 +1,26 @@
+class File
+  RELATIVE_PARENTDIR = '..'
+  
+  # Turns a path +to+ into a relative path from starting
+  # point +from+. The argument +from+ is assumed to be
+  # a filename. To treat it as a directory, make sure it
+  # ends in {File::SEPARATOR} ('/' on UNIX filesystems).
+  # 
+  # @param [String] from the starting filename 
+  #   (or directory with +from_isdir+ set to +true+).
+  # 
+  # @param [String] to the final path that should be made relative.
+  # 
+  # @return [String] the relative path from +from+ to +to+.
+  # 
+  def self.relative_path(from, to)
+    from = expand_path(from).split(SEPARATOR)
+    to = expand_path(to).split(SEPARATOR)
+    from.length.times do 
+      break if from[0] != to[0] 
+      from.shift; to.shift
+    end
+    fname = from.pop
+    join *(from.map { RELATIVE_PARENTDIR } + to)
+  end
+end