yard 0.2.2 → 0.2.3

data/lib/yard/handlers/ruby/extend_handler.rb

@@ -0,0 +1,19 @@
+# `extend` works just like `include` except that it always
+# mixes the module in in class scope,
+# and that it can handle `extend self`.
+class YARD::Handlers::Ruby::ExtendHandler < YARD::Handlers::Ruby::MixinHandler
+  namespace_only
+  handles method_call(:extend)
+
+  def scope; :class end
+
+  private
+
+  def process_mixin(mixin)
+    if mixin == s(:var_ref, s(:kw, "self"))
+      namespace.mixins(scope) << namespace
+    else
+      super
+    end
+  end
+end

data/lib/yard/handlers/{alias_handler.rb → ruby/legacy/alias_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::AliasHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aalias(_method)?(\s|\()/
   
   def process
@@ -8,15 +8,14 @@ class YARD::Handlers::AliasHandler < YARD::Handlers::Base
     else
       names = tokval_list(statement.tokens[2..-1], :attr)
     end
-    raise YARD::Handlers::UndocumentableError, statement.tokens.first.text if names.size != 2
+    raise YARD::Parser::UndocumentableError, statement.tokens.first.text if names.size != 2
     
     new_meth, old_meth = names[0].to_sym, names[1].to_sym
     old_obj = namespace.child(:name => old_meth, :scope => scope)
     new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
       o.visibility = visibility
       o.scope = scope
-      o.line = statement.tokens.first.line_no
-      o.file = parser.file
+      o.add_file(parser.file, statement.tokens.first.line_no)
       o.docstring = statement.comments
 
       if old_obj

data/lib/yard/handlers/{attribute_handler.rb → ruby/legacy/attribute_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::AttributeHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Aattr(?:_(?:reader|writer|accessor))?(?:\s|\()/
   
   def process
@@ -7,7 +7,7 @@ class YARD::Handlers::AttributeHandler < YARD::Handlers::Base
       symbols     = tokval_list statement.tokens[2..-1], :attr, TkTRUE, TkFALSE
       read, write = true, false
     rescue SyntaxError
-      raise YARD::Handlers::UndocumentableError, attr_type
+      raise YARD::Parser::UndocumentableError, attr_type
     end
     
     # Change read/write based on attr_reader/writer/accessor

data/lib/yard/handlers/ruby/legacy/base.rb

@@ -0,0 +1,198 @@
+module YARD
+  module Handlers
+    module Ruby::Legacy
+      class Base < Handlers::Base
+        # For tokens like TkDEF, TkCLASS, etc.
+        include YARD::Parser::Ruby::Legacy::RubyToken
+        
+        def self.handles?(stmt)
+          handlers.any? do |a_handler|
+            case a_handler
+            when String
+              stmt.tokens.first.text == a_handler
+            when Regexp
+              stmt.tokens.to_s =~ a_handler
+            else
+              a_handler == stmt.tokens.first.class 
+            end
+          end
+        end
+
+        protected
+
+        def parse_block(opts = {})
+          push_state(opts) do
+            if statement.block
+              blk = Parser::Ruby::Legacy::StatementList.new(statement.block)
+              parser.process(blk)
+            end
+          end
+        end
+      
+        # The string value of a token. For example, the return value for the symbol :sym 
+        # would be :sym. The return value for a string "foo #{bar}" would be the literal 
+        # "foo #{bar}" without any interpolation. The return value of the identifier
+        # 'test' would be the same value: 'test'. Here is a list of common types and
+        # their return values:
+        # 
+        # @example 
+        #   tokval(TokenList.new('"foo"').first) => "foo"
+        #   tokval(TokenList.new(':foo').first) => :foo
+        #   tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => "CONSTANT"
+        #   tokval(TokenList.new('identifier').first, RubyToken::TkId) => "identifier"
+        #   tokval(TokenList.new('3.25').first) => 3.25
+        #   tokval(TokenList.new('/xyz/i').first) => /xyz/i
+        # 
+        # @param [Token] token The token of the class
+        # 
+        # @param [Array<Class<Token>>, Symbol] accepted_types
+        #   The allowed token types that this token can be. Defaults to [{TkVal}].
+        #   A list of types would be, for example, [{TkSTRING}, {TkSYMBOL}], to return
+        #   the token's value if it is either of those types. If +TkVal+ is accepted, 
+        #   +TkNode+ is also accepted.
+        # 
+        #   Certain symbol keys are allowed to specify multiple types in one fell swoop.
+        #   These symbols are:
+        #     :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+
+        #     :attr         => +TkSYMBOL+ and +TkSTRING+
+        #     :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.
+        #     :number       => +TkFLOAT+, +TkINTEGER+
+        # 
+        # @return [Object] if the token is one of the accepted types, in its real value form.
+        #   It should be noted that identifiers and constants are kept in String form.
+        # @return [nil] if the token is not any of the specified accepted types
+        def tokval(token, *accepted_types)
+          accepted_types = [TkVal] if accepted_types.empty?
+          accepted_types.push(TkNode) if accepted_types.include? TkVal
+
+          if accepted_types.include?(:attr)
+            accepted_types.push(TkSTRING, TkSYMBOL)
+          end
+
+          if accepted_types.include?(:string)
+            accepted_types.push(TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING)
+          end
+
+          if accepted_types.include?(:identifier)
+            accepted_types.push(TkIDENTIFIER, TkFID, TkGVAR)
+          end
+
+          if accepted_types.include?(:number)
+            accepted_types.push(TkFLOAT, TkINTEGER)
+          end
+
+          return unless accepted_types.any? {|t| t === token }
+
+          case token
+          when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING 
+            token.text[1..-2]
+          when TkSYMBOL
+            token.text[1..-1].to_sym
+          when TkFLOAT
+            token.text.to_f
+          when TkINTEGER
+            token.text.to_i
+          when TkREGEXP
+            token.text =~ /\A\/(.+)\/([^\/])\Z/
+            Regexp.new($1, $2)
+          when TkTRUE
+            true
+          when TkFALSE
+            false
+          when TkNIL
+            nil
+          else
+            token.text
+          end
+        end
+
+        # Returns a list of symbols or string values from a statement. 
+        # The list must be a valid comma delimited list, and values 
+        # will only be returned to the end of the list only.
+        # 
+        # Example:
+        #   attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
+        #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c'] 
+        # 
+        # The tokval list of a {TokenList} of the above
+        # code would be the {#tokval} value of :a, 'b',
+        # :c and :d.
+        # 
+        # It should also be noted that this function stops immediately at
+        # any ruby keyword encountered:
+        #   "attr_accessor :a, :b, :c if x == 5"  => ['a', 'b', 'c']
+        # 
+        # @param [TokenList] tokenlist The list of tokens to process.
+        # @param [Array<Class<Token>>] accepted_types passed to {#tokval}
+        # @return [Array<String>] the list of tokvalues in the list.
+        # @return [Array<EMPTY>] if there are no symbols or Strings in the list 
+        # @see #tokval
+        def tokval_list(tokenlist, *accepted_types)
+          return [] unless tokenlist
+          out = [[]]
+          parencount, beforeparen = 0, 0
+          needcomma = false
+          seen_comma = true
+          tokenlist.each do |token|
+            tokval = accepted_types == [:all] ? token.text : tokval(token, *accepted_types)
+            parencond = !out.last.empty? && tokval != nil
+            #puts "#{seen_comma.inspect} #{parencount} #{token.class.class_name} #{out.inspect}"
+            case token
+            when TkCOMMA
+              if parencount == 0
+                out << [] unless out.last.empty?
+                needcomma = false
+                seen_comma = true
+              else
+                out.last << token.text if parencond
+              end
+            when TkLPAREN
+              if seen_comma
+                beforeparen += 1
+              else
+                parencount += 1
+                out.last << token.text if parencond
+              end
+            when TkRPAREN
+              if beforeparen > 0
+                beforeparen -= 1
+              else
+                out.last << token.text if parencount > 0 && tokval != nil
+                parencount -= 1
+              end
+            when TkLBRACE, TkLBRACK, TkDO
+              parencount += 1 
+              out.last << token.text if tokval != nil
+            when TkRBRACE, TkRBRACK, TkEND
+              out.last << token.text if tokval != nil
+              parencount -= 1
+            else
+              break if TkKW === token && ![TkTRUE, TkFALSE, TkSUPER, TkSELF, TkNIL].include?(token.class)
+
+              seen_comma = false unless TkWhitespace === token
+              if parencount == 0
+                next if needcomma 
+                next if TkWhitespace === token
+                if tokval != nil
+                  out.last << tokval
+                else
+                  out.last.clear
+                  needcomma = true
+                end 
+              elsif parencond
+                needcomma = true
+                out.last << token.text
+              end
+            end
+
+            if beforeparen == 0 && parencount < 0
+              break
+            end
+          end
+          # Flatten any single element lists
+          out.map {|e| e.empty? ? nil : (e.size == 1 ? e.pop : e.flatten.join) }.compact
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/{class_handler.rb → ruby/legacy/class_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::ClassHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkCLASS
   
   def process
@@ -14,19 +14,31 @@ class YARD::Handlers::ClassHandler < YARD::Handlers::Base
       parse_block(:namespace => klass)
        
       if undocsuper
-        raise YARD::Handlers::UndocumentableError, 'superclass (class was added without superclass)'
+        raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
       end
     elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:]+)/
       classname = $1
+      proxy = Proxy.new(namespace, classname)
+      
+      # Allow constants to reference class names
+      if ConstantObject === proxy
+        if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
+          proxy = Proxy.new(namespace, proxy.value)
+        else
+          raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
+        end
+      end
+      
       if classname == "self"
         parse_block(:namespace => namespace, :scope => :class)
-      elsif classname[0,1] =~ /[A-Z]/
-        parse_block(:namespace => P(namespace, classname), :scope => :class)
+      elsif classname[0,1] =~ /[A-Z]/ 
+        register ClassObject.new(namespace, classname) if Proxy === proxy
+        parse_block(:namespace => proxy, :scope => :class)
       else
-        raise YARD::Handlers::UndocumentableError, "class '#{classname}'"
+        raise YARD::Parser::UndocumentableError, "class '#{classname}'"
       end
     else
-      raise YARD::Handlers::UndocumentableError, "class: #{statement.tokens}"
+      raise YARD::Parser::UndocumentableError, "class: #{statement.tokens}"
     end
   end
   

data/lib/yard/handlers/{class_variable_handler.rb → ruby/legacy/class_variable_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::ClassVariableHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
   HANDLER_MATCH = /\A@@\S*\s*=\s*/m
   handles HANDLER_MATCH
   

data/lib/yard/handlers/{constant_handler.rb → ruby/legacy/constant_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::ConstantHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Legacy::Base
   HANDLER_MATCH = /\A[A-Z]\w*\s*=[^=]\s*/m
   handles HANDLER_MATCH
   
@@ -8,6 +8,6 @@ class YARD::Handlers::ConstantHandler < YARD::Handlers::Base
     return unless owner.is_a? NamespaceObject
     
     name, value = *statement.tokens.to_s.gsub(/\r?\n/, '').split(/\s*=\s*/, 2)
-    register ConstantObject.new(namespace, name) {|o| o.source = statement }
+    register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
   end
 end

data/lib/yard/handlers/{exception_handler.rb → ruby/legacy/exception_handler.rb}

@@ -1,12 +1,12 @@
-class YARD::Handlers::ExceptionHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Araise(\s|\()/
   
   def process
     return unless owner.is_a?(MethodObject) # Only methods yield
-    return if owner.has_tag? :raise
+    return if owner.has_tag?(:raise)
 
     if klass = statement.tokens.to_s[/^raise[\(\s]*(#{NAMESPACEMATCH})(?:\)|,|\s|(?:\s*(?:\.|\:\:)\s*)?new|$)/, 1]
-      owner.tags << YARD::Tags::Tag.new(:raise, '', klass)
+      owner.docstring.add_tag YARD::Tags::Tag.new(:raise, '', klass)
     end
   end
 end

data/lib/yard/handlers/ruby/legacy/extend_handler.rb

@@ -0,0 +1,18 @@
+# `extend` works just like `include` except that it always
+# mixes the module in in class scope,
+# and that it can handle `extend self`.
+class YARD::Handlers::Ruby::Legacy::ExtendHandler < YARD::Handlers::Ruby::Legacy::MixinHandler
+  handles /\Aextend(\s|\()/
+
+  def scope; :class end
+
+  private
+
+  def process_mixin(mixin)
+    if mixin == "self"
+      namespace.mixins(scope) << namespace
+    else
+      super
+    end
+  end
+end

data/lib/yard/handlers/ruby/legacy/method_handler.rb

@@ -0,0 +1,31 @@
+class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles TkDEF
+    
+  def process
+    nobj = namespace
+    mscope = scope
+
+    if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
+      meth, args = $1, $2
+      meth.gsub!(/\s+/,'')
+      args = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(args), :all)
+      args.map! {|a| k, v = *a.split('=', 2); [k.strip, (v ? v.strip : nil)] } if args
+    else
+      raise YARD::Parser::UndocumentableError, "method: invalid name"
+    end
+    
+    # Class method if prefixed by self(::|.) or Module(::|.)
+    if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
+      mscope, meth = :class, $1
+      nobj = P(namespace, $`) unless $` == "self"
+    end
+    
+    obj = register MethodObject.new(nobj, meth, mscope) do |o| 
+      o.visibility = visibility 
+      o.source = statement
+      o.explicit = true
+      o.parameters = args
+    end
+    parse_block(:owner => obj) # mainly for yield/exceptions
+  end
+end

data/lib/yard/handlers/ruby/legacy/mixin_handler.rb

@@ -0,0 +1,28 @@
+class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles /\Ainclude(\s|\()/
+  
+  def process
+    statement.tokens[1..-1].to_s.split(/\s*,\s*/).each do |mixin|
+      process_mixin(mixin.strip)
+    end
+  end
+
+  private
+
+  def process_mixin(mixin)
+    unless mixmatch = mixin[/\A(#{NAMESPACEMATCH})/, 1]
+      raise YARD::Parser::UndocumentableError, "mixin #{mixin} for class #{namespace.path}"
+    end
+
+    obj = Proxy.new(namespace, mixmatch)
+    
+    case obj
+    when Proxy
+      obj.type = :module
+    when ConstantObject # If a constant is included, use its value as the real object
+      obj = Proxy.new(namespace, obj.value)
+    end
+
+    namespace.mixins(scope) << obj
+  end
+end

data/lib/yard/handlers/{module_handler.rb → ruby/legacy/module_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::ModuleHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkMODULE
   
   def process

data/lib/yard/handlers/{visibility_handler.rb → ruby/legacy/visibility_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::VisibilityHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\A(protected|private|public)(\s|\(|$)/
   
   def process

data/lib/yard/handlers/{yield_handler.rb → ruby/legacy/yield_handler.rb}

@@ -1,4 +1,4 @@
-class YARD::Handlers::YieldHandler < YARD::Handlers::Base
+class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkYIELD
   
   def process
@@ -7,16 +7,16 @@ class YARD::Handlers::YieldHandler < YARD::Handlers::Base
     return if owner.has_tag? :yieldparam    # Same thing.
 
     yieldtag = YARD::Tags::Tag.new(:yield, "", [])
-    owner.tags << yieldtag
+    owner.docstring.add_tag(yieldtag)
     tokval_list(statement.tokens[2..-1], Token).each do |item|
       item = item.inspect unless item.is_a?(String)
       if item == "self"
         yieldtag.types << '_self'
-        owner.tags << YARD::Tags::Tag.new(:yieldparam, 
+        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
           "the object that the method was called on", owner.namespace.path, '_self')
       elsif item == "super"
         yieldtag.types << '_super'
-        owner.tags << YARD::Tags::Tag.new(:yieldparam, 
+        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
           "the result of the method from the superclass", nil, '_super')
       else
         yieldtag.types << item