yard 0.7.5 → 0.8.0

data/lib/yard/parser/c/c_parser.rb

@@ -0,0 +1,225 @@
+module YARD
+  module Parser
+    module C
+      class CParser < Base
+        def initialize(source, file = '(stdin)')
+          @file = file
+          @namespaces = {}
+          @content = source
+          @index = 0
+          @line = 1
+          @state = nil
+          @newline = true
+          @statements = []
+          @last_comment = nil
+          @last_statement = nil
+        end
+
+        def parse
+          parse_toplevel
+          enumerator
+        end
+
+        def enumerator
+          @statements
+        end
+
+        def tokenize
+          raise NotImplementedError, "no tokenization support for C/C++ files"
+        end
+
+        private
+
+        def parse_toplevel
+          advance_loop do
+            case char
+            when /['"]/; consume_quote(char)
+            when '#'; consume_directive
+            when '/'; consume_comment
+            when /\s/; consume_whitespace
+            else consume_toplevel_statement
+            end
+          end
+        end
+
+        def consume_quote(type = '"')
+          advance
+          advance_loop do
+            case char
+            when "\n"; advance; nextline
+            when '\\'; advance(2)
+            when type; advance; return
+            else advance
+            end
+          end
+        end
+
+        def consume_directive
+          return unless @newline
+          @last_comment = nil
+          @last_statement = nil
+          advance_loop do
+            if char == '\\' && nextchar =~ /[\r\n]/
+              advance_loop { advance; break(nextline) if char == "\n" }
+            elsif char == "\n"
+              return
+            end
+            advance
+          end
+        end
+
+        def consume_toplevel_statement
+          @newline = false
+          start = @index
+          line = @line
+          decl = consume_until(/[{;]/)
+          return nil if decl =~ /\A\s*\Z/
+          statement = ToplevelStatement.new(nil, @file, line)
+          @statements << statement
+          attach_comment(statement)
+          stmts = nil
+          if prevchar == '{'
+            stmts = consume_body_statements
+            consume_until(';') if decl =~ /\A(typedef|enum|class|struct|union)\b/
+          end
+          statement.source = @content[start..@index]
+          statement.block = stmts
+          statement.declaration = decl
+        end
+
+        def consume_body_statements
+          stmts = []
+          brace_level = 1
+          while true
+            strip_non_statement_data
+            start, line = @index, @line
+            consume_until(/[{};]/)
+            brace_level += 1 if prevchar == '{'
+            brace_level -= 1 if prevchar == '}'
+
+            break if prevchar.empty? || (brace_level <= 0 && prevchar == '}')
+            end_chr = @index
+            end_chr -= 1 if prevchar == '}'
+            src = @content[start...@index]
+            if src && src !~ /\A\s*\Z|\A\}\Z/
+              stmt = BodyStatement.new(src, @file, line)
+              attach_comment(stmt)
+              stmts << stmt
+            end
+          end
+          stmts
+        end
+
+        def strip_non_statement_data
+          start = @index
+          begin
+            start = @index
+            case char
+            when /\s/; consume_whitespace
+            when '#';  consume_directive
+            when '/';  consume_comment
+            end
+          end until start == @index
+        end
+
+        def consume_whitespace
+          advance_loop { nextline if char == "\n"; break if char =~ /\S/; advance }
+        end
+
+        def consume_comment(add_comment = true)
+          return(advance) unless nextchar == '*' || nextchar == '/'
+          line = @line
+          type = nextchar == '*' ? :multi : :line
+          advance(2)
+          comment = ""
+          advance_loop do
+            comment << char
+            if type == :multi
+              nextline if char == "\n"
+              if char(2) == '*/'
+                if add_comment
+                  comment << '/'
+                  stmt = Comment.new(comment, @file, line)
+                  stmt.type = type
+                  attach_comment(stmt)
+                  @statements << stmt
+                end
+                return advance(2)
+              end
+            elsif char == "\n"
+              if add_comment
+                stmt = Comment.new(comment[0...-1], @file, line)
+                stmt.type = type
+                attach_comment(stmt)
+                @statements << stmt
+              end
+              return
+            end
+            advance
+          end
+        end
+
+        def consume_until(end_char, bracket_level = 0, brace_level = 0, add_comment = true)
+          end_char = /#{end_char}/ if end_char.is_a?(String)
+          start = @index
+          advance_loop do
+            chr = char
+            case chr
+            when /\s/; consume_whitespace
+            when /['"]/; consume_quote(char)
+            when '#'; consume_directive
+            when '/'; consume_comment(add_comment)
+            when '{'; advance; brace_level += 1
+            when '}'; advance; brace_level -= 1
+            when '('; advance; bracket_level += 1
+            when ')'; advance; bracket_level -= 1
+            else advance
+            end
+            @newline = false if chr !~ /\s/
+
+            if chr =~ end_char && (chr == '{' || chr == '(')
+              break
+            elsif chr =~ end_char && bracket_level <= 0 && brace_level <= 0
+              break
+            end
+          end
+          return @content[start...@index]
+        end
+
+        def attach_comment(statement)
+          if Comment === statement
+            if @last_statement && @last_statement.line == statement.line
+              @last_statement.comments = statement
+              statement.statement = @last_statement
+            end
+            @last_comment = statement
+            @last_statement = nil
+          else
+            if @last_comment
+              statement.comments = @last_comment
+              @last_comment.statement = statement
+            end
+            @last_statement = statement
+            @last_comment = nil
+          end
+        end
+
+        def advance(num = 1) @index += num end
+        def back(num = 1) @index -= num end
+
+        def advance_loop(&block)
+          while @index <= @content.size; yield end
+        end
+
+        def nextline
+          @line += 1
+          @newline = true
+        end
+
+        def char(num = 1) @content[@index, num] end
+        def prevchar(num = 1) @content[@index - 1, num] end
+        def nextchar(num = 1) @content[@index + 1, num] end
+      end
+    end
+  end
+end

data/lib/yard/parser/c/comment_parser.rb

@@ -0,0 +1,131 @@
+module YARD
+  module Parser
+    module C
+      module CommentParser
+        protected
+
+        def parse_comments(comments)
+          @overrides = []
+          spaces = nil
+          comments = remove_private_comments(comments)
+          comments = comments.split(/\r?\n/).map do |line|
+            line.gsub!(%r{^\s*/?\*/?}, '')
+            line.gsub!(%r{\*/\s*$}, '')
+            if line =~ /^\s*$/
+              next if spaces.nil?
+              next ""
+            end
+            spaces = (line[/^(\s+)/, 1] || "").size if spaces.nil?
+            line.gsub(/^\s{0,#{spaces}}/, '').rstrip
+          end.compact
+
+          comments = parse_overrides(comments)
+          comments = parse_callseq(comments)
+          comments.join("\n")
+        end
+
+        private
+
+        def parse_overrides(comments)
+          comments.map do |line|
+            type, name = *line.scan(/^\s*Document-(class|module|method|const):\s*(\S.*)\s*$/).first
+            if type
+              @overrides << [type.to_sym, name]
+              nil
+            else
+              line
+            end
+          end.compact
+        end
+
+        def parse_callseq(comments)
+          return comments unless comments[0] =~ /\Acall-seq:\s*(\S.+)?/
+          if $1
+            comments[0] = " #{$1}"
+          else
+            comments.shift
+          end
+          overloads = []
+          seen_data = false
+          while comments.first =~ /^\s+(\S.+)/ || comments.first =~ /^\s*$/
+            line = comments.shift.strip
+            break if line.empty? && seen_data
+            next if line.empty?
+            seen_data = true
+            line.sub!(/^\w+[\.#]/, '')
+            signature, types = *line.split(/ [-=]> /)
+            types = parse_types(types)
+            if signature.sub!(/\[?\s*(\{(?:\s*\|(.+?)\|)?.*\})\s*\]?\s*$/, '') && $1
+              blk, blkparams = $1, $2
+            else
+              blk, blkparams = nil, nil
+            end
+            case signature
+            when /^(\w+)\s*=\s+(\w+)/
+              signature = "#{$1}=(#{$2})"
+            when /^\w+\s+\S/
+              signature = signature.split(/\s+/)
+              signature = "#{signature[1]}#{signature[2] ? '(' + signature[2..-1].join(' ') + ')' : ''}"
+            when /^\w+\[(.+?)\]\s*(=)?/
+              signature = "[]#{$2}(#{$1})"
+            when /^\w+\s+(#{CodeObjects::METHODMATCH})\s+(\w+)/
+              signature = "#{$1}(#{$2})"
+            end
+            break unless signature =~ /^#{CodeObjects::METHODNAMEMATCH}/
+            signature = signature.rstrip
+            overloads << "@overload #{signature}"
+            overloads << "  @yield [#{blkparams}]" if blk
+            overloads << "  @return [#{types.join(', ')}]" unless types.empty?
+          end
+
+          comments + [""] + overloads
+        end
+
+        def parse_types(types)
+          if types =~ /true or false/
+            ["Boolean"]
+          else
+            (types||"").split(/,| or /).map do |t|
+              case t.strip.gsub(/^an?_/, '')
+              when "class"; "Class"
+              when "obj", "object", "anObject"; "Object"
+              when "arr", "array", "anArray", /^\[/; "Array"
+              when /^char\s*\*/, "char", "str", "string", "new_str"; "String"
+              when "enum", "anEnumerator"; "Enumerator"
+              when "exc", "exception"; "Exception"
+              when "proc", "proc_obj", "prc"; "Proc"
+              when "binding"; "Binding"
+              when "hsh", "hash", "aHash"; "Hash"
+              when "ios", "io"; "IO"
+              when "file"; "File"
+              when "float"; "Float"
+              when "time", "new_time"; "Time"
+              when "dir", "aDir"; "Dir"
+              when "regexp", "new_regexp"; "Regexp"
+              when "matchdata"; "MatchData"
+              when "encoding"; "Encoding"
+              when "fixnum", "fix"; "Fixnum"
+              when /^(?:un)?signed$/, /^(?:(?:un)?signed\s*)?(?:short|int|long|long\s+long)$/, "integer", "Integer"; "Integer"
+              when "num", "numeric", "Numeric", "number"; "Numeric"
+              when "aBignum"; "Bignum"
+              when "nil"; "nil"
+              when "true"; "true"
+              when "false"; "false"
+              when "bool", "boolean", "Boolean"; "Boolean"
+              when "self"; "self"
+              when /^[-+]?\d/; t
+              when /[A-Z][_a-z0-9]+/; t
+              end
+            end.compact
+          end
+        end
+
+        def remove_private_comments(comment)
+           comment = comment.gsub(/\/?\*--\n(.*?)\/?\*\+\+/m, '')
+           comment = comment.sub(/\/?\*--\n.*/m, '')
+           comment
+        end
+      end
+    end
+  end
+end

data/lib/yard/parser/c/statement.rb

@@ -0,0 +1,63 @@
+module YARD
+  module Parser
+    module C
+      class Statement
+        attr_accessor :source
+        attr_accessor :line
+        attr_accessor :file
+
+        # @deprecated Groups are now defined by directives
+        # @see Tags::GroupDirective
+        attr_accessor :group
+
+        attr_accessor :comments_hash_flag
+
+        def initialize(source, file = nil, line = nil)
+          @source = source
+          @file = file
+          @line = line
+        end
+
+        def line_range
+          line...(line + source.count("\n"))
+        end
+
+        def comments_range
+          comments.line_range
+        end
+
+        def first_line
+          source.split(/\n/).first
+        end
+
+        def show
+          "\t#{line}: #{first_line}"
+        end
+      end
+
+      class BodyStatement < Statement
+        attr_accessor :comments
+      end
+
+      class ToplevelStatement < Statement
+        attr_accessor :block
+        attr_accessor :declaration
+        attr_accessor :comments
+      end
+
+      class Comment < Statement
+        include CommentParser
+
+        attr_accessor :type
+        attr_accessor :overrides
+        attr_accessor :statement
+
+        def initialize(source, file = nil, line = nil)
+          super(parse_comments(source), file, line)
+        end
+
+        def comments; self end
+      end
+    end
+  end
+end

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

@@ -39,7 +39,12 @@ module YARD
       # the AstNode children of the node, use {#children}.
       class AstNode < Array
         attr_accessor :docstring_hash_flag
-        attr_accessor :docstring, :docstring_range, :source, :group
+        attr_accessor :docstring, :docstring_range, :source
+
+        # @deprecated Groups are now defined by directives
+        # @see Tags::GroupDirective
+        attr_accessor :group
+
         attr_writer :source_range, :line_range, :file, :full_source
         alias comments docstring
         alias comments_range docstring_range
@@ -110,6 +115,14 @@ module YARD
             MethodCallNode
           when :if, :elsif, :if_mod, :unless, :unless_mod
             ConditionalNode
+          when :for, :while, :while_mod, :until, :until_mod
+            LoopNode
+          when :def, :defs
+            MethodDefinitionNode
+          when :class, :sclass
+            ClassNode
+          when :module
+            ModuleNode
           else
             if type.to_s =~ /_ref\Z/
               ReferenceNode
@@ -226,11 +239,26 @@ module YARD
           false
         end
 
+        # @return [Boolean] whether the node is a method definition
+        def def?
+          false
+        end
+
         # @return [Boolean] whether the node is a if/elsif/else condition
         def condition?
           false
         end
 
+        # @return [Boolean] whether the node is a loop
+        def loop?
+          false
+        end
+
+        # @return [Boolean] whether the node has a block
+        def block?
+          respond_to?(:block) || condition?
+        end
+
         # @group Getting Line Information
 
         # @return [Boolean] whether the node has a {#line_range} set
@@ -296,6 +324,13 @@ module YARD
           's(' + typeinfo + map(&:inspect).join(", ") + ')'
         end
 
+        # @group Managing node state
+
+        # Resets node state in tree
+        def unfreeze
+          @children = nil
+        end
+
         # @endgroup
 
         private
@@ -367,6 +402,9 @@ module YARD
         end
 
         def block_param; parameters.last end
+        def block
+          last.type == :do_block || last.type == :brace_block ? last : nil
+        end
 
         private
 
@@ -379,6 +417,31 @@ module YARD
         end
       end
 
+      class MethodDefinitionNode < AstNode
+        def kw?; true end
+        def def?; true end
+        def namespace; first if index_adjust > 0 end
+
+        def method_name(name_only = false)
+          name = self[index_adjust]
+          name_only ? name.jump(:ident).first.to_sym : name
+        end
+
+        def parameters(include_block_param = true)
+          params = self[1 + index_adjust]
+          params = params[0] if params.type == :paren
+          include_block_param ? params : params[0...-1]
+        end
+
+        alias block last
+
+        private
+
+        def index_adjust
+          type == :defs ? 2 : 0
+        end
+      end
+
       class ConditionalNode < KeywordNode
         def condition?; true end
         def condition; first end
@@ -394,6 +457,33 @@ module YARD
 
         def cmod?; type =~ /_mod$/ end
       end
+
+      class ClassNode < KeywordNode
+        def class_name; first end
+        def superclass; type == :sclass ? nil : self[1] end
+        def block; last end
+      end
+
+      class ModuleNode < KeywordNode
+        def module_name; first end
+        def block; last end
+      end
+
+      class LoopNode < KeywordNode
+        def loop?; true end
+        def condition; type == :for ? s(self[0], self[1]) : first end
+        def block; last end
+      end
+
+      # Represents a lone comment block in source
+      class CommentNode < AstNode
+        def docstring; first end
+        def docstring=(value) end
+        alias comments docstring
+
+        def source; "" end
+        def first_line; "" end
+      end
     end
   end
 end