yard 0.6.8 → 0.7.0

data/lib/yard/parser/ruby/ast_node.rb

@@ -3,15 +3,15 @@ module YARD
     module Ruby
       # Builds and s-expression by creating {AstNode} objects with
       # the type provided by the first argument.
-      # 
+      #
       # @example An implicit list of keywords
       #   ast = s(s(:kw, "if"), s(:kw, "else"))
       #   ast.type # => :list
       # @example A method call
       #   s(:command, s(:var_ref, "mymethod"))
-      # 
+      #
       # @overload s(*nodes, opts = {})
-      #   @param [Array<AstNode>] nodes a list of nodes. 
+      #   @param [Array<AstNode>] nodes a list of nodes.
       #   @param [Hash] opts any extra options (docstring, file, source) to
       #     set on the object
       #   @return [AstNode] an implicit node where node.type == +:list+
@@ -26,16 +26,16 @@ module YARD
         opts = Hash === args.last ? args.pop : {}
         AstNode.node_class_for(type).new(type, args, opts)
       end
-      
+
       # An AST node is characterized by a type and a list of children. It
       # is most easily represented by the s-expression {#s} such as:
       #   # AST for "if true; 5 end":
       #   s(s(:if, s(:var_ref, s(:kw, "true")), s(s(:int, "5")), nil))
-      # 
+      #
       # The node type is not considered part of the list, only its children.
       # So +ast[0]+ does not refer to the type, but rather the first child
       # (or object). Items that are not +AstNode+ objects can be part of the
-      # list, like Strings or Symbols representing names. To return only 
+      # list, like Strings or Symbols representing names. To return only
       # the AstNode children of the node, use {#children}.
       class AstNode < Array
         attr_accessor :docstring_hash_flag
@@ -45,10 +45,10 @@ module YARD
         alias comments_range docstring_range
         alias comments_hash_flag docstring_hash_flag
         alias to_s source
-        
+
         # @return [Symbol] the node's unique symbolic type
         attr_accessor :type
-        
+
         # @return [AstNode, nil] the node's parent or nil if it is a root node.
         attr_accessor :parent
 
@@ -58,7 +58,7 @@ module YARD
           reset_line_info unless @source_range
           @source_range
         end
-        
+
         # @return [Range] the line range in {#full_source} represented
         #   by the node
         def line_range
@@ -84,9 +84,9 @@ module YARD
           return parent.full_source[source_range] if parent
           full_source
         end
-        
+
         # List of all known keywords
-        # @return [Hash] 
+        # @return [Hash]
         KEYWORDS = { :class => true, :alias => true, :lambda => true, :do_block => true,
           :def => true, :defs => true, :begin => true, :rescue => true, :rescue_mod => true,
           :if => true, :if_mod => true, :else => true, :elsif => true, :case => true,
@@ -94,12 +94,12 @@ module YARD
           :return => true, :throw => true, :catch => true, :until => true, :until_mod => true,
           :while => true, :while_mod => true, :yield => true, :yield0 => true, :zsuper => true,
           :unless => true, :unless_mod => true, :for => true, :super => true, :return0 => true }
-        
+
         # @group Creating an AstNode
 
         # Finds the node subclass that should be instantiated for a specific
         # node type
-        # 
+        #
         # @param [Symbol] type the node type to find a subclass for
         # @return [Class] a subclass of AstNode to instantiate the node with.
         def self.node_class_for(type)
@@ -122,9 +122,9 @@ module YARD
             end
           end
         end
-        
+
         # Creates a new AST node
-        # 
+        #
         # @param [Symbol] type the type of node being created
         # @param [Array<AstNode>] arr the child nodes
         # @param [Hash] opts any extra line options
@@ -145,33 +145,33 @@ module YARD
           @fallback_source = opts[:listchar]
           @token = true if opts[:token]
         end
-        
-        # @return [Boolean] whether the node is equal to another by checking 
+
+        # @return [Boolean] whether the node is equal to another by checking
         #   the list and type
         # @private
         def ==(ast)
           super && type == ast.type
         end
-        
+
         # @group Traversing a Node
-    
+
         # Searches through the node and all descendants and returns the
         # first node with a type matching any of +node_types+, otherwise
         # returns the original node (self).
-        # 
+        #
         # @example Returns the first method definition in a block of code
         #   ast = YARD.parse_string("if true; def x; end end").ast
         #   ast.jump(:def)
-        #   # => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil, 
+        #   # => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil,
         #   #      nil), s(s(:void_stmt, )))
         # @example Returns first 'def' or 'class' statement
         #   ast = YARD.parse_string("class X; def y; end end")
         #   ast.jump(:def, :class).first
-        #   # => 
+        #   # =>
         # @example If the node types are not present in the AST
         #   ast = YARD.parse("def x; end")
         #   ast.jump(:def)
-        # 
+        #
         # @param [Array<Symbol>] node_types a set of node types to match
         # @return [AstNode] the matching node, if one was found
         # @return [self] if no node was found
@@ -186,10 +186,10 @@ module YARD
         end
 
         # Traverses the object and yields each node (including descendants) in order.
-        # 
+        #
         # @yield each descendant node in order
         # @yieldparam [AstNode] self, or a child/descendant node
-        # @return [void] 
+        # @return [void]
         def traverse
           nodes = [self]
           nodes.each.with_index do |node, index|
@@ -197,64 +197,64 @@ module YARD
             nodes.insert index+1, *node.children
           end
         end
-        
+
         # @group Node Meta Types
 
         # @return [Boolean] whether the node is a token
         def token?
           @token
         end
-        
-        # @return [Boolean] whether the node is a reference (variable, 
+
+        # @return [Boolean] whether the node is a reference (variable,
         #   constant name)
         def ref?
           false
         end
-        
+
         # @return [Boolean] whether the node is a literal value
         def literal?
           false
         end
-        
+
         # @return [Boolean] whether the node is a keyword
         def kw?
           false
         end
-        
+
         # @return [Boolean] whether the node is a method call
         def call?
           false
         end
-        
+
         # @return [Boolean] whether the node is a if/elsif/else condition
         def condition?
           false
         end
 
         # @group Getting Line Information
-        
+
         # @return [Boolean] whether the node has a {#line_range} set
         def has_line?
           @line_range ? true : false
         end
-        
+
         # @return [Fixnum] the starting line number of the node
         def line
           line_range && line_range.first
         end
-        
+
         # @return [String] the first line of source represented by the node.
         def first_line
           full_source.split(/\r?\n/)[line - 1].strip
         end
 
         # @group Printing a Node
-        
+
         # @return [String] the first line of source the node represents
         def show
           "\t#{line}: #{first_line}"
         end
-        
+
         # @return [nil] pretty prints the node
         def pretty_print(q)
           objs = self.dup + [:__last__]
@@ -271,37 +271,37 @@ module YARD
           objs.pop if options.size == 0
 
           q.group(3, 's(', ')') do
-            q.seplist(objs, nil, :each) do |v| 
+            q.seplist(objs, nil, :each) do |v|
               if v == :__last__
                 q.seplist(options, nil, :each) do |arr|
                   k, v2 = *arr
-                  q.group(3) do 
+                  q.group(3) do
                     q.text k
                     q.group(3) do
                       q.text ': '
-                      q.pp v2 
+                      q.pp v2
                     end
                   end
                 end
               else
-                q.pp v 
+                q.pp v
               end
             end
           end
         end
 
         # @return [String] inspects the object
-        def inspect 
+        def inspect
           typeinfo = type && type != :list ? ':' + type.to_s + ', ' : ''
           's(' + typeinfo + map(&:inspect).join(", ") + ')'
         end
 
         # @endgroup
-        
+
         private
 
         # Resets line information
-        # @return [void] 
+        # @return [void]
         def reset_line_info
           if size == 0
             self.line_range = @fallback_line
@@ -319,27 +319,27 @@ module YARD
           end
         end
       end
-      
+
       class ReferenceNode < AstNode
         def ref?; true end
-        
+
         def path
           Array.new flatten
         end
-        
+
         def namespace
           Array.new flatten[0...-1]
         end
       end
-      
+
       class LiteralNode < AstNode
         def literal?; true end
       end
-      
+
       class KeywordNode < AstNode
         def kw?; true end
       end
-      
+
       class ParameterNode < AstNode
         def required_params; self[0] end
         def required_end_params; self[3] end
@@ -347,7 +347,7 @@ module YARD
         def splat_param; self[2] ? self[2][0] : nil end
         def block_param; self[4] ? self[4][0] : nil end
       end
-      
+
       class MethodCallNode < AstNode
         def call?; true end
         def namespace; first if index_adjust > 0 end
@@ -359,37 +359,38 @@ module YARD
 
         def parameters(include_block_param = true)
           params = self[1 + index_adjust]
-          return nil unless params
+          return [] unless params
           params = call_has_paren? ? params.first : params
+          return [] unless params
           include_block_param ? params : params[0...-1]
         end
-        
+
         def block_param; parameters.last end
-        
+
         private
-        
+
         def index_adjust
           [:call, :command_call].include?(type) ? 2 : 0
         end
-        
-        def call_has_paren? 
+
+        def call_has_paren?
           [:fcall, :call].include?(type)
         end
       end
-      
+
       class ConditionalNode < KeywordNode
         def condition?; true end
         def condition; first end
         def then_block; self[1] end
-        
+
         def else_block
           if self[2] && !cmod?
             self[2].type == :elsif ? self[2] : self[2][0]
           end
         end
-        
+
         private
-        
+
         def cmod?; type =~ /_mod$/ end
       end
     end

data/lib/yard/parser/ruby/legacy/ruby_lex.rb

@@ -12,20 +12,20 @@ module YARD
       EXPR_FNAME = :EXPR_FNAME
       EXPR_DOT   = :EXPR_DOT
       EXPR_CLASS = :EXPR_CLASS
-      
+
       # Represents a token in the Ruby lexer
       class Token
         # @return [Integer] the line number in the file/stream the token is
         #   located.
         attr_reader :line_no
-        
+
         # @return [Integer] the character number in the file/stream the token
         #   is located.
         attr_reader :char_no
-        
+
         # @return [String] the token text value
         attr_reader :text
-        
+
         # @return [Symbol] the lexical state at the token
         attr_accessor :lex_state
 
@@ -42,7 +42,7 @@ module YARD
         end
 
         # Chainable way to sets the text attribute
-        # 
+        #
         # @param [String] text the new text
         # @return [Token] this token object
         def set_text(text)
@@ -50,12 +50,12 @@ module YARD
           self
         end
       end
-      
+
       # Represents a block
       class TkBlockContents < Token
         def text; '...' end
       end
-      
+
       # Represents an end statement
       class TkStatementEnd < Token
         def text; '' end
@@ -64,7 +64,7 @@ module YARD
       class TkNode < Token
         attr :node
       end
-      
+
       # Represents whitespace
       class TkWhitespace < Token
       end
@@ -131,8 +131,8 @@ module YARD
           if (tk = source[token]).nil?
             IRB.fail TkReading2TokenNoKey, token
           end
-          tk = Token(tk[0], value) 
-        else 
+          tk = Token(tk[0], value)
+        else
           if token
             tk = if (token.ancestors & [TkId, TkVal, TkOPASGN, TkUnknownChar]).empty?
                    token.new(@prev_line_no, @prev_char_no)
@@ -236,14 +236,14 @@ module YARD
         [:TkASSOC,      TkOp,   "=>"],
         [:TkQUESTION,   TkOp,   "?"],  #?
         [:TkCOLON,      TkOp,   ":"],        #:
-    
+
 #        [:TkfLPAREN],         # func( #
 #        [:TkfLBRACK],         # func[ #
 #        [:TkfLBRACE],         # func{ #
         [:TkSTAR],            # *arg
         [:TkAMPER],           # &arg #
 #        [:TkSYMBOL,     TkId],          # :SYMBOL
-        [:TkSYMBEG,     TkId], 
+        [:TkSYMBEG,     TkId],
         [:TkGT,         TkOp,   ">"],
         [:TkLT,         TkOp,   "<"],
         [:TkPLUS,       TkOp,   "+"],
@@ -295,7 +295,7 @@ module YARD
         token_c =  Class.new super_token
         RubyToken.const_set token_n, token_c
         # token_c.inspect
- 
+
         if reading
           if TkReading2Token[reading]
             IRB.fail TkReading2TokenDuplicateError, token_n, reading
@@ -358,9 +358,9 @@ module YARD
       #
       # @private
       class BufferedReader
-    
+
         attr_reader :line_num
-    
+
         def initialize(content)
           if /\t/ =~ content
             tab_width = 2
@@ -379,34 +379,34 @@ module YARD
           @last_newline = 0
           @newline_pending = false
         end
-    
+
         def column
           @offset - @last_newline
         end
-    
+
         def getc
           return nil if @offset >= @size
           ch = @content[@offset, 1]
-      
+
           @offset += 1
           @hwm = @offset if @hwm < @offset
-      
+
           if @newline_pending
             @line_num += 1
             @last_newline = @offset - 1
             @newline_pending = false
           end
-      
+
           if ch == "\n"
             @newline_pending = true
           end
           ch
         end
-    
+
         def getc_already_read
           getc
         end
-    
+
         def ungetc(ch)
           raise "unget past beginning of file" if @offset <= 0
           @offset -= 1
@@ -414,13 +414,13 @@ module YARD
             @newline_pending = false
           end
         end
-    
+
         def get_read
           res = @content[@read_back_offset...@offset]
           @read_back_offset = @offset
           res
         end
-    
+
         def peek(at)
           pos = @offset + at
           if pos >= @size
@@ -429,11 +429,11 @@ module YARD
             @content[pos, 1]
           end
         end
-    
+
         def peek_equal(str)
           @content[@offset, str.length] == str
         end
-    
+
         def divert_read_from(reserve)
           @content[@offset, 0] = reserve
           @size      = @content.size
@@ -446,10 +446,10 @@ module YARD
       def_exception(:AlreadyDefinedToken, "Already defined token(%s)")
       def_exception(:TkReading2TokenNoKey, "key nothing(key='%s')")
       def_exception(:TkSymbol2TokenNoKey, "key nothing(key='%s')")
-      def_exception(:TkReading2TokenDuplicateError, 
+      def_exception(:TkReading2TokenDuplicateError,
         "key duplicate(token_n='%s', key='%s')")
       def_exception(:SyntaxError, "%s")
-  
+
       include RubyToken
       include IRB
 
@@ -473,7 +473,7 @@ module YARD
         @quoted = nil
         @lex_state = EXPR_BEG
         @space_seen = false
-    
+
         @continue = false
         @line = ""
 
@@ -569,7 +569,7 @@ module YARD
           tk
         end
       end
-  
+
       ENINDENT_CLAUSE = [
         "case", "class", "def", "do", "for", "if",
         "module", "unless", "until", "while", "begin" #, "when"
@@ -586,7 +586,7 @@ module YARD
         "w" => "]",
         "W" => "]"
       }
-  
+
       PERCENT_PAREN = {
         "{" => "}",
         "[" => "]",
@@ -670,10 +670,10 @@ module YARD
           Token(TkNL).set_text("\n")
         end
 
-        @OP.def_rules("*", "**",  
+        @OP.def_rules("*", "**",
           "!", "!=", "!~",
-          "=", "==", "===", 
-          "=~", "<=>",  
+          "=", "==", "===",
+          "=~", "<=>",
           "<", "<=",
           ">", ">=", ">>") do |op, io|
           @lex_state = EXPR_BEG
@@ -682,7 +682,7 @@ module YARD
 
         @OP.def_rules("<<") do |op, io|
           tk = nil
-          if @lex_state != EXPR_END && @lex_state != EXPR_CLASS && 
+          if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
              (@lex_state != EXPR_ARG || @space_seen)
             c = peek(0)
             tk = identify_here_document if /[-\w_\"\'\`]/ =~ c
@@ -732,8 +732,8 @@ module YARD
           @lex_state = EXPR_BEG
           Token(op).set_text(op)
         end
-    
-        @OP.def_rules("+=", "-=", "*=", "**=", 
+
+        @OP.def_rules("+=", "-=", "*=", "**=",
           "&=", "|=", "^=", "<<=", ">>=", "||=", "&&=") do |op, io|
           @lex_state = EXPR_BEG
           op =~ /^(.*)=$/
@@ -784,7 +784,7 @@ module YARD
 
         lex_int2
       end
-  
+
       def lex_int2
         @OP.def_rules("]", "}", ")") do
           |op, io|
@@ -793,7 +793,7 @@ module YARD
           Token(op).set_text(op)
         end
 
-        @OP.def_rule(":") do 
+        @OP.def_rule(":") do
           if (@colonblock_seen && @lex_state != EXPR_BEG) || peek(0) =~ /\s/
             @lex_state = EXPR_BEG
             tk = Token(TkCOLON)
@@ -825,7 +825,7 @@ module YARD
             Token(TkOPASGN, :/).set_text("/=") #")
           elsif @lex_state == EXPR_ARG and @space_seen and peek(0) !~ /\s/
             identify_string(op)
-          else 
+          else
             @lex_state = EXPR_BEG
             Token("/").set_text(op)
           end
@@ -840,7 +840,7 @@ module YARD
         #   @lex_state = EXPR_BEG
         #   Token(TkOPASGN, :^)
         # end
-    
+
         @OP.def_rules(",", ";") do |op, io|
           @colonblock_seen = false
           @lex_state = EXPR_BEG
@@ -856,7 +856,7 @@ module YARD
           @lex_state = EXPR_BEG
           Token("~").set_text("~@")
         end
-    
+
         @OP.def_rule("(") do
           @indent += 1
           # if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
@@ -907,15 +907,15 @@ module YARD
         end
 
         @OP.def_rule('\\') do   #'
-          if getc == "\n" 
+          if getc == "\n"
             @space_seen = true
             @continue = true
             Token(TkSPACE).set_text("\\\n")
-          else 
+          else
             ungetc
             Token("\\").set_text("\\")  #"
-          end 
-        end 
+          end
+        end
 
         @OP.def_rule('%') do
           |op, io|
@@ -945,7 +945,7 @@ module YARD
           end
         end
 
-        # @OP.def_rule("def", proc{|op, io| /\s/ =~ io.peek(0)}) do 
+        # @OP.def_rule("def", proc{|op, io| /\s/ =~ io.peek(0)}) do
         #   |op, io|
         #   @indent += 1
         #   @lex_state = EXPR_FNAME
@@ -969,10 +969,10 @@ module YARD
           printf "MATCH: end %s: %s\n", op, io.inspect if RubyLex.debug?
           t
         end
-    
+
         p @OP if RubyLex.debug?
       end
-  
+
       def identify_gvar
         @lex_state = EXPR_END
         str = "$"
@@ -981,15 +981,15 @@ module YARD
              when /[~_*$?!@\/\\;,=:<>".]/   #"
                str << ch
                Token(TkGVAR, str)
-           
+
              when "-"
                str << "-" << getc
                Token(TkGVAR, str)
-           
+
              when "&", "`", "'", "+"
                str << ch
                Token(TkBACK_REF, str)
-           
+
              when /[1-9]/
                str << ch
                while (ch = getc) =~ /[0-9]/
@@ -1001,13 +1001,13 @@ module YARD
                ungetc
                ungetc
                return identify_identifier
-             else 
+             else
                ungetc
-               Token("$")     
+               Token("$")
              end
         tk.set_text(str)
       end
-  
+
       def identify_identifier
         token = ""
         token.concat getc if peek(0) =~ /[$@]/
@@ -1018,7 +1018,7 @@ module YARD
           token.concat ch
         end
         ungetc
-    
+
         if ch == "!" or ch == "?"
           token.concat getc
         end
@@ -1033,7 +1033,7 @@ module YARD
           @lex_state = EXPR_END
           return Token(TkIVAR, token).set_text(token)
         end
-    
+
         if @lex_state != EXPR_DOT
           print token, "\n" if RubyLex.debug?
 
@@ -1051,8 +1051,8 @@ module YARD
               if @lex_state != EXPR_FNAME
                 if ENINDENT_CLAUSE.include?(token)
                   @indent += 1
-            
-                  if ACCEPTS_COLON.include?(token)  
+
+                  if ACCEPTS_COLON.include?(token)
                     @colonblock_seen = true
                   else
                     @colonblock_seen = false
@@ -1138,7 +1138,7 @@ module YARD
         @lex_state = EXPR_END
         Token(Ltype2Token[lt], str).set_text(str.dump)
       end
-  
+
       def identify_quotation(initial_char)
         ch = getc
         if lt = PERCENT_LTYPE[ch]
@@ -1219,7 +1219,7 @@ module YARD
         end
         Token(type).set_text(str)
       end
-  
+
       def identify_string(ltype, quoted = ltype, opener=nil, initial_char = nil)
         @ltype = ltype
         @quoted = quoted
@@ -1231,9 +1231,9 @@ module YARD
 
         nest = 0
         begin
-          while ch = getc 
+          while ch = getc
             str << ch
-            if @quoted == ch 
+            if @quoted == ch
               if nest == 0
                 break
               else
@@ -1294,7 +1294,7 @@ module YARD
             if ch == "\n"
               ch = " "
             else
-              comment << "\\" 
+              comment << "\\"
             end
           else
             if ch == "\n"
@@ -1307,7 +1307,7 @@ module YARD
         end
         return Token(TkCOMMENT).set_text(comment)
       end
-  
+
       def read_escape
         res = ""
         case ch = getc
@@ -1324,7 +1324,7 @@ module YARD
           end
           res << ch
         end
-      
+
         when "x"
           res << ch
           2.times do