yard 0.2.2 → 0.2.3

data/lib/yard/code_objects/base.rb

@@ -17,59 +17,71 @@ module YARD
       alias_method :<<, :push
     end
     
-    NSEP = '::'
-    ISEP = '#'
+    NSEPQ = NSEP = '::'
+    ISEPQ = ISEP = '#'
+    CSEP = '.'
+    CSEPQ = Regexp.quote CSEP
     CONSTANTMATCH = /[A-Z]\w*/
-    NAMESPACEMATCH = /(?:(?:#{Regexp.quote NSEP})?#{CONSTANTMATCH})+/
-    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?]?|[-+~]\@|<<|>>|=~|===?|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
-    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|self)\s*(?:\.|#{Regexp.quote NSEP})\s*)?#{METHODNAMEMATCH}/
+    NAMESPACEMATCH = /(?:(?:#{NSEPQ})?#{CONSTANTMATCH})+/
+    METHODNAMEMATCH = /[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|[<>]=?|\*\*|[-\/+%^&*~`|]|\[\]=?/
+    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|self)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/
     
     BUILTIN_EXCEPTIONS = ["SecurityError", "Exception", "NoMethodError", "FloatDomainError", 
       "IOError", "TypeError", "NotImplementedError", "SystemExit", "Interrupt", "SyntaxError", 
       "RangeError", "NoMemoryError", "ArgumentError", "ThreadError", "EOFError", "RuntimeError", 
       "ZeroDivisionError", "StandardError", "LoadError", "NameError", "LocalJumpError", "SystemCallError", 
       "SignalException", "ScriptError", "SystemStackError", "RegexpError", "IndexError"]
+    # Note: MatchingData is a 1.8.x legacy class
     BUILTIN_CLASSES = ["TrueClass", "Array", "Dir", "Struct", "UnboundMethod", "Object", "Fixnum", "Float", 
-      "ThreadGroup", "MatchData", "Proc", "Binding", "Class", "Time", "Bignum", "NilClass", "Symbol", 
-      "Numeric", "String", "Data", "MatchingData", "Regexp", "Integer", "File", "IO", "Range", "FalseClass", 
+      "ThreadGroup", "MatchingData", "MatchData", "Proc", "Binding", "Class", "Time", "Bignum", "NilClass", "Symbol", 
+      "Numeric", "String", "Data", "MatchData", "Regexp", "Integer", "File", "IO", "Range", "FalseClass", 
       "Method", "Continuation", "Thread", "Hash", "Module"] + BUILTIN_EXCEPTIONS
     BUILTIN_MODULES = ["ObjectSpace", "Signal", "Marshal", "Kernel", "Process", "GC", "FileTest", "Enumerable", 
-      "Comparable", "Errno", "Precision", "Math", "DTracer"]
+      "Comparable", "Errno", "Precision", "Math"]
     BUILTIN_ALL = BUILTIN_CLASSES + BUILTIN_MODULES
     
     BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h,n| h.update(n => true) }
     
     class Base  
-      attr_reader :name
-      attr_accessor :namespace
-      attr_accessor :source, :signature, :file, :line, :docstring, :dynamic
+      attr_reader :name, :files
+      attr_accessor :namespace, :source, :signature, :docstring, :dynamic
       
       def dynamic?; @dynamic end
       
       class << self
         def new(namespace, name, *args, &block)
-          if name =~ /(?:#{NSEP}|#{ISEP})([^#{NSEP}#{ISEP}]+)$/
+          if name.to_s[0,2] == NSEP
+            name = name.to_s[2..-1]
+            namespace = Registry.root
+          elsif name =~ /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{NSEPQ}#{ISEPQ}#{CSEPQ}]+)$/
             return new(Proxy.new(namespace, $`), $1, *args, &block)
           end
           
           keyname = namespace && namespace.respond_to?(:path) ? namespace.path : ''
           if self == RootObject
             keyname = :root
+          elsif self == MethodObject
+            keyname += (args.first && args.first.to_sym == :class ? CSEP : ISEP) + name.to_s
           elsif keyname.empty?
             keyname = name.to_s
-          elsif self == MethodObject
-            keyname += (!args.first || args.first.to_sym == :instance ? ISEP : NSEP) + name.to_s
           else
             keyname += NSEP + name.to_s
           end
           
-          if self != RootObject && obj = Registry[keyname]
+          obj = Registry.objects[keyname]
+          obj = nil if obj && obj.class != self
+          
+          if self != RootObject && obj
             yield(obj) if block_given?
             obj
           else
             Registry.objects[keyname] = super(namespace, name, *args, &block)
           end
         end
+        
+        def ===(other)
+          self >= other.class ? true : false
+        end
       end
           
       def initialize(namespace, name, *args)
@@ -78,13 +90,50 @@ module YARD
           raise ArgumentError, "Invalid namespace object: #{namespace}"
         end
 
+        @files = []
+        @current_file_has_comments = false
         @name = name.to_sym
         @tags = []
-        @docstring = ""
+        @docstring = Docstring.new('', self)
         self.namespace = namespace
         yield(self) if block_given?
       end
       
+      # Associates a file with a code object, optionally adding the line where it was defined.
+      # By convention, '<STDIN>' should be used to associate code that comes form standard input.
+      # 
+      # @param [String] file the filename ('<STDIN>' for standard input)
+      # @param [Fixnum, nil] the line number where the object lies in the file
+      # @param [Boolean] whether or not the definition has comments associated. This
+      #   will allow {#file} to return the definition where the comments were made instead
+      #   of any empty definitions that might have been parsed before (module namespaces for instance).
+      def add_file(file, line = nil, has_comments = false)
+        raise(ArgumentError, "file cannot be nil or empty") if file.nil? || file == ''
+        obj = [file.to_s, line]
+        if has_comments && !@current_file_has_comments
+          @current_file_has_comments = true
+          @files.unshift(obj) 
+        else
+          @files << obj # back of the line
+        end
+      end
+      
+      # Returns the filename the object was first parsed at, taking
+      # definitions with docstrings first.
+      # 
+      # @return [String] a filename
+      def file
+        @files.first ? @files.first[0] : nil
+      end
+
+      # Returns the line the object was first parsed at (or nil)
+      # 
+      # @return [Fixnum] the line where the object was first defined.
+      # @return [nil] if there is no line associated with the object
+      def line
+        @files.first ? @files.first[1] : nil
+      end
+      
       def ==(other)
         if other.is_a?(Proxy)
           path == other.path
@@ -111,7 +160,7 @@ module YARD
       
       def method_missing(meth, *args, &block)
         if meth.to_s =~ /=$/
-          self[meth.to_s[0..-2]] = *args
+          self[meth.to_s[0..-2]] = args.first
         elsif instance_variable_get("@#{meth}")
           self[meth]
         else
@@ -126,7 +175,7 @@ module YARD
       #   the +Parser::Statement+ holding the source code or the raw source 
       #   as a +String+ for the definition of the code object only (not the block)
       def source=(statement)
-        if statement.is_a? Parser::Statement
+        if statement.is_a? Parser::Ruby::Legacy::Statement
           src = statement.tokens.to_s
           blk = statement.block ? statement.block.to_s : ""
           if src =~ /^def\s.*[^\)]$/ && blk[0,1] !~ /\r|\n/
@@ -136,6 +185,10 @@ module YARD
           @source = format_source(src + blk)
           self.line = statement.tokens.first.line_no
           self.signature = src
+        elsif statement.respond_to?(:source)
+          self.line = statement.line
+          self.signature = statement.first_line
+          @source = format_source(statement.source.strip)
         else
           @source = format_source(statement.to_s)
         end
@@ -145,24 +198,13 @@ module YARD
       # Attaches a docstring to a code oject by parsing the comments attached to the statement
       # and filling the {#tags} and {#docstring} methods with the parsed information.
       #
-      # @param [String, Array<String>] comments 
+      # @param [String, Array<String>, Docstring] comments 
       #   the comments attached to the code object to be parsed 
       #   into a docstring and meta tags.
       def docstring=(comments)
-        @short_docstring = nil
-        parse_comments(comments) if comments
+        @docstring = Docstring === comments ? comments : Docstring.new(comments, self)
       end
       
-      ##
-      # Gets the first line of a docstring to the period or the first paragraph.
-      # 
-      # @return [String] The first line or paragraph of the docstring; always ends with a period.
-      def short_docstring
-        @short_docstring ||= (docstring.split(/\.|\r?\n\r?\n/).first || '')
-        @short_docstring += '.' unless @short_docstring.empty?
-        @short_docstring
-      end
-
       ##
       # Default type is the lowercase class name without the "Object" suffix
       # 
@@ -170,7 +212,7 @@ module YARD
       # 
       # @return [Symbol] the type of code object this represents
       def type
-        self.class.name.split(/#{NSEP}/).last.gsub(/Object$/, '').downcase.to_sym
+        self.class.name.split(/#{NSEPQ}/).last.gsub(/Object$/, '').downcase.to_sym
       end
     
       def path
@@ -203,113 +245,14 @@ module YARD
       alias_method :parent, :namespace
       alias_method :parent=, :namespace=
 
-      ## 
-      # Convenience method to return the first tag
-      # object in the list of tag objects of that name
-      #
-      # Example:
-      #   doc = YARD::Documentation.new("@return zero when nil")
-      #   doc.tag("return").text  # => "zero when nil"
-      #
-      # @param [#to_s] name the tag name to return data for
-      # @return [Tags::Tag] the first tag in the list of {#tags}
-      def tag(name)
-        @tags.find {|tag| tag.tag_name.to_s == name.to_s }
-      end
-
-      ##
-      # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
-      #
-      # @param name the tag name to return data for, or nil for all tags
-      # @return [Array<Tags::Tag>] the list of tags by the specified tag name
-      def tags(name = nil)
-        return @tags if name.nil?
-        @tags.select {|tag| tag.tag_name.to_s == name.to_s }
-      end
-
-      ##
-      # Returns true if at least one tag by the name +name+ was declared
-      #
-      # @param [String] name the tag name to search for
-      # @return [Boolean] whether or not the tag +name+ was declared
-      def has_tag?(name)
-        @tags.any? {|tag| tag.tag_name.to_s == name.to_s }
-      end
+      def tag(name); @docstring.tag(name) end
+      def tags(name = nil); @docstring.tags(name) end
+      def has_tag?(name); @docstring.has_tag?(name) end
 
       protected
     
       def sep; NSEP end
 
-      private
-
-      ##
-      # Parses out comments split by newlines into a new code object
-      #
-      # @param [Array<String>, String] comments 
-      #   the newline delimited array of comments. If the comments
-      #   are passed as a String, they will be split by newlines. 
-      def parse_comments(comments)
-        return if comments.empty?
-        meta_match = /^@(\S+)\s*(.*)/
-        comments = comments.split(/\r?\n/) if comments.is_a? String
-        @tags, @docstring = [], ""
-
-        indent, last_indent = comments.first[/^\s*/].length, 0
-        orig_indent = 0
-        last_line = ""
-        tag_name, tag_klass, tag_buf, raw_buf = nil, nil, "", []
-
-        (comments+['']).each_with_index do |line, index|
-          indent = line[/^\s*/].length 
-          empty = (line =~ /^\s*$/ ? true : false)
-          done = comments.size == index
-
-          if tag_name && (((indent < orig_indent && !empty) || done) || 
-              (indent <= last_indent && line =~ meta_match))
-            tagfactory = Tags::Library.new
-            tag_method = "#{tag_name}_tag"
-            if tag_name && tagfactory.respond_to?(tag_method)
-              if tagfactory.method(tag_method).arity == 2
-                @tags << tagfactory.send(tag_method, tag_buf, raw_buf.join("\n"))
-              else
-                @tags << tagfactory.send(tag_method, tag_buf) 
-              end
-            else
-              log.warn "Unknown tag @#{tag_name} in documentation for `#{path}`"
-            end
-            tag_name, tag_buf, raw_buf = nil, '', []
-            orig_indent = 0
-          end
-
-          # Found a meta tag
-          if line =~ meta_match
-            orig_indent = indent
-            tag_name, tag_buf = $1, $2 
-            raw_buf = [tag_buf.dup]
-          elsif tag_name && indent >= orig_indent && !empty
-            # Extra data added to the tag on the next line
-            last_empty = last_line =~ /^[ \t]*$/ ? true : false
-            
-            if last_empty
-              tag_buf << "\n\n" 
-              raw_buf << ''
-            end
-            
-            tag_buf << line.gsub(/^[ \t]{#{indent}}/, last_empty ? '' : ' ')
-            raw_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
-          elsif !tag_name
-            # Regular docstring text
-            @docstring << line << "\n" 
-          end
-
-          last_indent = indent
-          last_line = line
-        end
-
-        # Remove trailing/leading whitespace / newlines
-        @docstring.gsub!(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
-      end      
-      
       # Formats source code by removing leading indentation
       def format_source(source)
         source.chomp!
@@ -318,4 +261,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/code_objects/class_object.rb

@@ -6,7 +6,7 @@ module YARD::CodeObjects
       super
 
       if is_exception?
-        self.superclass ||= :Exception 
+        self.superclass ||= :Exception unless P(namespace, name) == P(:Exception)
       else
         self.superclass ||= :Object unless P(namespace, name) == P(:Object)
       end
@@ -17,13 +17,14 @@ module YARD::CodeObjects
     end
     
     def inheritance_tree(include_mods = false)
-      list = [self] + (include_mods ? mixins : [])
-      if superclass.is_a? Proxy
+      list = (include_mods ? mixins(:instance) : [])
+      if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
         list << superclass unless superclass == P(:Object)
-      elsif superclass.respond_to? :inheritance_tree
-        list += superclass.inheritance_tree
       end
-      list
+      [self] + list.map do |m|
+        next m unless m.respond_to?(:inheritance_tree)
+        m.inheritance_tree(include_mods)
+      end.flatten
     end
     
     def meths(opts = {})
@@ -80,10 +81,10 @@ module YARD::CodeObjects
       end
       
       if @superclass == self
-        msg = "superclass #{@superclass.inspect} cannot be the same as the subclass #{self}"
+        msg = "superclass #{@superclass.inspect} cannot be the same as the declared class #{self.inspect}"
         @superclass = P(:Object)
         raise ArgumentError, msg
       end
     end
   end
-end
+end

data/lib/yard/code_objects/constant_object.rb

@@ -1,4 +1,5 @@
 module YARD::CodeObjects
   class ConstantObject < Base
+    attr_accessor :value
   end
 end

data/lib/yard/code_objects/extended_method_object.rb

@@ -0,0 +1,9 @@
+module YARD::CodeObjects
+  class ExtendedMethodObject
+    instance_methods.each {|m| undef_method(m) unless m =~ /^__/ || m.to_sym == :object_id }
+    
+    def scope; :class end
+    def initialize(obj) @del = obj end
+    def method_missing(sym, *args, &block) @del.__send__(sym, *args, &block) end
+  end
+end

data/lib/yard/code_objects/method_object.rb

@@ -1,15 +1,22 @@
 module YARD::CodeObjects
   class MethodObject < Base
-    attr_accessor :visibility, :scope, :explicit
+    attr_accessor :visibility, :scope, :explicit, :parameters
     
     def initialize(namespace, name, scope = :instance) 
       self.visibility = :public
       self.scope = scope
+      self.parameters = []
 
       super
     end
     
-    def scope=(v) @scope = v.to_sym end
+    def scope=(v) 
+      reregister = @scope ? true : false
+      YARD::Registry.delete(self) if reregister
+      @scope = v.to_sym 
+      YARD::Registry.register(self) if reregister
+    end
+    
     def visibility=(v) @visibility = v.to_sym end
       
     def is_attribute?
@@ -41,11 +48,17 @@ module YARD::CodeObjects
     end
     
     def name(prefix = false)
-      prefix && sep == ISEP ? sep + super().to_s : super()
+      ((prefix ? (sep == ISEP ? sep : "") : "") + super().to_s).to_sym
     end
     
     protected
     
-    def sep; scope == :class ? super : ISEP end
+    def sep
+      if scope == :class
+        namespace && namespace != YARD::Registry.root ? CSEP : NSEP
+      else
+        ISEP
+      end
+    end
   end
-end
+end

data/lib/yard/code_objects/module_object.rb

@@ -1,4 +1,11 @@
 module YARD::CodeObjects
   class ModuleObject < NamespaceObject
+    def inheritance_tree(include_mods = false)
+      return [self] unless include_mods
+      [self] + mixins(:instance).map do |m|
+        next m unless m.respond_to?(:inheritance_tree)
+        m.inheritance_tree(true)
+      end.flatten
+    end
   end
-end
+end

data/lib/yard/code_objects/namespace_object.rb

@@ -1,10 +1,12 @@
 module YARD::CodeObjects
   class NamespaceObject < Base
-    attr_reader :children, :cvars, :meths, :constants, :mixins, :attributes, :aliases
+    attr_reader :children, :cvars, :meths, :constants, :attributes, :aliases
+    attr_reader :class_mixins, :instance_mixins
     
     def initialize(namespace, name, *args, &block)
       @children = CodeObjectList.new(self)
-      @mixins = CodeObjectList.new(self)
+      @class_mixins = CodeObjectList.new(self)
+      @instance_mixins = CodeObjectList.new(self)
       @attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
       @aliases = {}
       super
@@ -25,7 +27,7 @@ module YARD::CodeObjects
         opts = SymbolHash[opts]
         children.find do |obj| 
           opts.each do |meth, value|
-            break false if obj[meth] != value
+            break false if !(value.is_a?(Array) ? value.include?(obj[meth]) : obj[meth] == value)
           end
         end
       end
@@ -51,16 +53,17 @@ module YARD::CodeObjects
     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 }
+      opts = SymbolHash[:scope => [:instance, :class]].update(opts)
+      [opts[:scope]].flatten.map do |scope|
+        mixins(scope).reverse.inject([]) do |list, mixin|
+          next list if mixin.is_a?(Proxy)
+          arr = mixin.meths(opts.merge(:scope => :instance)).reject do |o|
+            child(:name => o.name, :scope => scope) || list.find {|o2| o2.name == o.name }
           end
+          arr.map! {|o| ExtendedMethodObject.new(o) } if scope == :class
+          list + arr
         end
-      end
+      end.flatten
     end
     
     def constants(opts = {})
@@ -70,13 +73,13 @@ module YARD::CodeObjects
     end
     
     def included_constants
-      mixins.reverse.inject([]) do |list, mixin|
-        if mixin.is_a?(Proxy)
-          list
-        else
+      instance_mixins.reverse.inject([]) do |list, mixin|
+        if mixin.respond_to? :constants
           list += mixin.constants.reject do |o| 
             child(:name => o.name) || list.find {|o2| o2.name == o.name }
           end
+        else
+          list
         end
       end
     end
@@ -84,5 +87,11 @@ module YARD::CodeObjects
     def cvars 
       children.select {|o| o.is_a? ClassVariableObject }
     end
+
+    def mixins(*scopes)
+      return class_mixins if scopes == [:class]
+      return instance_mixins if scopes == [:instance]
+      class_mixins | instance_mixins
+    end
   end
-end
+end