deg-yard 0.8.7.1

data/lib/yard/handlers/c/base.rb

@@ -0,0 +1,110 @@
+module YARD
+  module Handlers
+    module C
+      class Base < Handlers::Base
+        include YARD::Parser::C
+        include HandlerMethods
+
+        # @return [Boolean] whether the handler handles this statement
+        def self.handles?(statement, processor)
+          processor.globals.cruby_processed_files ||= {}
+          processor.globals.cruby_processed_files[processor.file] = true
+
+          if statement.respond_to? :declaration
+            src = statement.declaration
+          else
+            src = statement.source
+          end
+
+          handlers.any? do |a_handler|
+            statement_class >= statement.class &&
+              case a_handler
+              when String
+                src == a_handler
+              when Regexp
+                src =~ a_handler
+              end
+          end
+        end
+
+        def self.statement_class(type = nil)
+          type ? @statement_class = type : (@statement_class || Statement)
+        end
+
+        # @group Registering objects
+
+        def register_docstring(object, docstring = nil, stmt = nil)
+          super(object, docstring, stmt) if docstring
+        end
+
+        def register_file_info(object, file = nil, line = nil, comments = nil)
+          super(object, file, line, comments) if file
+        end
+
+        def register_source(object, source = nil, type = nil)
+          super(object, source, type) if source
+        end
+
+        def register_visibility(object, visibility = nil)
+          super(object, visibility) if visibility
+        end
+
+        # @group Looking up Symbol and Var Values
+
+        def symbols
+          globals.cruby_symbols ||= {}
+        end
+
+        def override_comments
+          globals.cruby_override_comments ||= []
+        end
+
+        def namespace_for_variable(var)
+          return namespaces[var] if namespaces[var]
+          var = remove_var_prefix(var)
+          var.empty? ? nil : P(var)
+        end
+
+        def namespaces
+          globals.cruby_namespaces ||= {}
+        end
+
+        def processed_files
+          globals.cruby_processed_files ||= {}
+        end
+
+        # @group Parsing an Inner Block
+
+        def parse_block(opts = {})
+          return if !statement.block || statement.block.empty?
+          push_state(opts) do
+            parser.process(statement.block)
+          end
+        end
+
+        # @group Processing other files
+
+        def process_file(file, object)
+          file = File.cleanpath(file)
+          return if processed_files[file]
+          processed_files[file] = file
+          begin
+            log.debug "Processing embedded call to C source #{file}..."
+            globals.ordered_parser.files.delete(file) if globals.ordered_parser
+            parser.process(Parser::C::CParser.new(File.read(file), file).parse)
+          rescue Errno::ENOENT
+            log.warn "Missing source file `#{file}' when parsing #{object}"
+          end
+        end
+
+        # @endgroup
+
+        private
+
+        def remove_var_prefix(var)
+          var.gsub(/^rb_[mc]|^[a-z_]+/, '')
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/c/class_handler.rb

@@ -0,0 +1,26 @@
+class YARD::Handlers::C::ClassHandler < YARD::Handlers::C::Base
+  MATCH1 = /([\w\.]+)\s* = \s*(?:rb_define_class|boot_defclass)\s*
+            \(
+               \s*"([\w:]+)",
+               \s*(\w+|0)\s*
+            \)/mx
+
+  MATCH2 = /([\w\.]+)\s* = \s*rb_define_class_under\s*
+            \(
+               \s*(\w+),
+               \s*"(\w+)"(?:,
+               \s*([\w\*\s\(\)\.\->]+)\s*)?  # for SWIG
+            \s*\)/mx
+  handles MATCH1
+  handles MATCH2
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |var_name, class_name, parent|
+      handle_class(var_name, class_name, parent)
+    end
+    statement.source.scan(MATCH2) do |var_name, in_module, class_name, parent|
+      handle_class(var_name, class_name, parent, in_module)
+    end
+  end
+end

data/lib/yard/handlers/c/constant_handler.rb

@@ -0,0 +1,12 @@
+class YARD::Handlers::C::ConstantHandler < YARD::Handlers::C::Base
+  MATCH = %r{\brb_define_((?:readonly_)?variable|(?:global_)?const)
+                \s*\((?:\s*(\w+),)?\s*"(\w+)",\s*(.*?)\s*\)\s*;}xm
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |type, var_name, const_name, value|
+      handle_constants(type, var_name, const_name, value)
+    end
+  end
+end

data/lib/yard/handlers/c/handler_methods.rb

@@ -0,0 +1,166 @@
+module YARD
+  module Handlers
+    module C
+      module HandlerMethods
+        include Parser::C
+        include CodeObjects
+
+        def handle_class(var_name, class_name, parent, in_module = nil)
+          parent = nil if parent == "0"
+          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          register ClassObject.new(namespace, class_name) do |obj|
+            if parent
+              parent_class = namespace_for_variable(parent)
+              if parent_class.is_a?(Proxy)
+                obj.superclass = "::#{parent_class.path}"
+                obj.superclass.type = :class
+              else
+                obj.superclass = parent_class
+              end
+            end
+            namespaces[var_name] = obj
+            register_file_info(obj, statement.file, statement.line)
+          end
+        end
+
+        def handle_module(var_name, module_name, in_module = nil)
+          namespace = in_module ? namespace_for_variable(in_module) : Registry.root
+          register ModuleObject.new(namespace, module_name) do |obj|
+            namespaces[var_name] = obj
+            register_file_info(obj, statement.file, statement.line)
+          end
+        end
+
+        def handle_method(scope, var_name, name, func_name, source_file = nil)
+          visibility = :public
+          case scope
+          when "singleton_method"; scope = :class
+          when "module_function"; scope = :module
+          when "private_method"; scope = :instance; visibility = :private
+          else; scope = :instance
+          end
+
+          namespace = namespace_for_variable(var_name)
+          return if namespace.nil? # XXX: raise UndocumentableError might be too noisy.
+          register MethodObject.new(namespace, name, scope) do |obj|
+            register_visibility(obj, visibility)
+            find_method_body(obj, func_name)
+            obj.add_tag(Tags::Tag.new(:return, '', 'Boolean')) if name =~ /\?$/
+          end
+        end
+
+        def handle_attribute(var_name, name, read, write)
+          values = {:read => read.to_i, :write => write.to_i}
+          {:read => name, :write => "#{name}="}.each do |type, meth_name|
+            next unless values[type] > 0
+            obj = handle_method(:instance, var_name, meth_name, nil)
+            obj.namespace.attributes[:instance][name] ||= SymbolHash[:read => nil, :write => nil]
+            obj.namespace.attributes[:instance][name][type] = obj
+          end
+        end
+
+        def handle_alias(var_name, new_name, old_name)
+          namespace = namespace_for_variable(var_name)
+          return if namespace.nil?
+          new_meth, old_meth = new_name.to_sym, old_name.to_sym
+          old_obj = namespace.child(:name => old_meth, :scope => :instance)
+          new_obj = register MethodObject.new(namespace, new_meth, :instance) do |o|
+            register_visibility(o, visibility)
+            register_file_info(o, statement.file, statement.line)
+          end
+
+          if old_obj
+            new_obj.signature = old_obj.signature
+            new_obj.source = old_obj.source
+            new_obj.docstring = old_obj.docstring
+            new_obj.docstring.object = new_obj
+          else
+            new_obj.signature = "def #{new_meth}" # this is all we know.
+          end
+
+          namespace.aliases[new_obj] = old_meth
+        end
+
+        def handle_constants(type, var_name, const_name, value)
+          return unless type == 'const'
+          namespace = namespace_for_variable(var_name)
+          register ConstantObject.new(namespace, const_name) do |obj|
+            obj.source_type = :c
+            obj.value = value
+            register_file_info(obj, statement.file, statement.line)
+            find_constant_docstring(obj)
+          end
+        end
+
+        private
+
+        def find_constant_docstring(object)
+          comment = nil
+
+          # look inside overrides for declaration value
+          override_comments.each do |name, override_comment|
+            next unless override_comment.file == statement.file
+            just_const_name = name.gsub(/\A.+::/, '')
+            if object.path == name || object.name.to_s == just_const_name
+              comment = override_comment.source
+              stmt = override_comment
+              break
+            end
+          end
+
+          # use any comments on this statement as a last resort
+          if comment.nil? && statement.comments && statement.comments.source =~ /\S/
+            comment = statement.comments.source
+            stmt = statement.comments
+          end
+
+          # In the case of rb_define_const, the definition and comment are in
+          # "/* definition: comment */" form.  The literal ':' and '\' characters
+          # can be escaped with a backslash.
+          if comment
+            comment.scan(/\A\s*(.*?[^\s\\]):\s*(.+)/m) do |new_value, new_comment|
+              object.value = new_value.gsub(/\\:/, ':')
+              comment = new_comment
+            end
+            register_docstring(object, comment, stmt)
+          end
+        end
+
+        def find_method_body(object, symbol)
+          file, in_file = statement.file, false
+          if statement.comments && statement.comments.source =~ /\A\s*in (\S+)\Z/
+            file, in_file = $1, true
+            process_file(file, object)
+          end
+
+          if src_stmt = symbols[symbol]
+            register_file_info(object, src_stmt.file, src_stmt.line, true)
+            register_source(object, src_stmt)
+            unless src_stmt.comments.nil? || src_stmt.comments.source.empty?
+              register_docstring(object, src_stmt.comments.source, src_stmt)
+              return # found docstring
+            end
+          end
+
+          # found source (possibly) but no docstring
+          # so look in overrides
+          override_comments.each do |name, override_comment|
+            next unless override_comment.file == file
+            name = name.gsub(/::([^:]+?)\Z/, '.\1')
+            just_method_name = name.gsub(/\A.+(#|::|\.)/, '')
+            just_method_name = 'initialize' if just_method_name == 'new'
+            if object.path == name || object.name.to_s == just_method_name
+              register_docstring(object, override_comment.source, override_comment)
+              return
+            end
+          end
+
+          # use any comments on this statement as a last resort
+          if !in_file && statement.comments && statement.comments.source =~ /\S/
+            register_docstring(object, statement.comments.source, statement)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/c/init_handler.rb

@@ -0,0 +1,18 @@
+# Handles the Init_Libname() method
+class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
+  MATCH = %r{\A\s*(?:static\s+)?void\s+(?:[Ii]nit_)?(\w+)\s*}
+  handles MATCH
+  statement_class ToplevelStatement
+
+  process do
+    parse_block
+    if decl = statement.declaration[MATCH, 1]
+      ns = namespace_for_variable(decl)
+      if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
+        if statement.comments
+          register_docstring(ns, statement.comments.source, statement)
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/c/method_handler.rb

@@ -0,0 +1,35 @@
+class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
+  MATCH1 = %r{rb_define_
+                 (
+                    singleton_method |
+                    method           |
+                    module_function  |
+                    private_method
+                 )
+                 \s*\(\s*([\w\.]+),
+                   \s*"([^"]+)",
+                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
+                   \s*(-?\w+)\s*\)}xm
+  MATCH2 = %r{rb_define_global_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
+                \s*(-?\w+)\s*\)}xm
+  handles MATCH1
+  handles MATCH2
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |type, var_name, name, func_name, param_count|
+      break if var_name == "ruby_top_self"
+      break if var_name == "nstr"
+      break if var_name == "envtbl"
+
+      var_name = "rb_cObject" if var_name == "rb_mKernel"
+      handle_method(type, var_name, name, func_name)
+    end
+
+    statement.source.scan(MATCH2) do |name, func_name, param_count|
+      handle_method("method", "rb_mKernel", name, func_name)
+    end
+  end
+end

data/lib/yard/handlers/c/mixin_handler.rb

@@ -0,0 +1,13 @@
+class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
+  MATCH = /rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |klass_var, mixin_var|
+      namespace = namespace_for_variable(klass_var)
+      ensure_loaded!(namespace)
+      namespace.mixins(:instance) << namespace_for_variable(mixin_var)
+    end
+  end
+end

data/lib/yard/handlers/c/module_handler.rb

@@ -0,0 +1,16 @@
+class YARD::Handlers::C::ModuleHandler < YARD::Handlers::C::Base
+  MATCH1 = /([\w\.]+)\s* = \s*rb_define_module\s*\(\s*"([\w:]+)"\s*\)/mx
+  MATCH2 = /([\w\.]+)\s* = \s*rb_define_module_under\s*\(\s*(\w+),\s*"(\w+)"\s*\)/mx
+  handles MATCH1
+  handles MATCH2
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH1) do |var_name, module_name|
+      handle_module(var_name, module_name)
+    end
+    statement.source.scan(MATCH2) do |var_name, in_module, module_name|
+      handle_module(var_name, module_name, in_module)
+    end
+  end
+end

data/lib/yard/handlers/c/override_comment_handler.rb

@@ -0,0 +1,30 @@
+# Parses comments
+class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
+  handles %r{.}
+  statement_class Comment
+
+  process do
+    return if statement.overrides.empty?
+    statement.overrides.each do |type, name|
+      override_comments << [name, statement]
+      obj = nil
+      case type
+      when :class
+        name, superclass = *name.split(/\s*<\s*/)
+        obj = YARD::CodeObjects::ClassObject.new(:root, name)
+        obj.superclass = "::#{superclass}" if superclass
+      when :module
+        obj = YARD::CodeObjects::ModuleObject.new(:root, name)
+      end
+      register(obj)
+    end
+  end
+
+  def register_docstring(object, docstring = statement.source, stmt = statement)
+    super
+  end
+
+  def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
+    super
+  end
+end

data/lib/yard/handlers/c/path_handler.rb

@@ -0,0 +1,10 @@
+class YARD::Handlers::C::PathHandler < YARD::Handlers::C::Base
+  MATCH = /([\w\.]+)\s* = \s*rb_path2class\s*\(\s*"([\w:]+)"\)/mx
+  handles MATCH
+
+  process do
+    statement.source.scan(MATCH) do |var_name, path|
+      namespaces[var_name] = P(path)
+    end
+  end
+end

data/lib/yard/handlers/c/struct_handler.rb

@@ -0,0 +1,12 @@
+class YARD::Handlers::C::StructHandler < YARD::Handlers::C::Base
+  MATCH = /([\w\.]+)\s*=\s*(?:rb_struct_define_without_accessor)\s*
+           \(\s*"([\w:]+)"\s*,\s*(\w+)\s*/mx
+  handles MATCH
+  statement_class BodyStatement
+
+  process do
+    statement.source.scan(MATCH) do |var_name, class_name, parent|
+      handle_class(var_name, class_name, parent)
+    end
+  end
+end

data/lib/yard/handlers/c/symbol_handler.rb

@@ -0,0 +1,7 @@
+# Keeps track of function bodies for symbol lookup during Ruby method declarations
+class YARD::Handlers::C::SymbolHandler < YARD::Handlers::C::Base
+  MATCH = %r{\A\s*(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+(\w+)\s*\(}
+  handles MATCH
+  statement_class ToplevelStatement
+  process { symbols[statement.source[MATCH, 1]] = statement }
+end

data/lib/yard/handlers/processor.rb

@@ -0,0 +1,201 @@
+require 'ostruct'
+
+module YARD
+  module Handlers
+    # Iterates over all statements in a file and delegates them to the
+    # {Handlers::Base} objects that are registered to handle the statement.
+    #
+    # This class is passed to each handler and keeps overall processing state.
+    # For example, if the {#visibility} is set in a handler, all following
+    # statements will have access to this state. This allows "public",
+    # "protected" and "private" statements to be handled in classes and modules.
+    # In addition, the {#namespace} can be set during parsing to control
+    # where objects are being created from. You can also access extra stateful
+    # properties that any handler can set during the duration of the post
+    # processing of a file from {#extra_state}. If you need to access state
+    # across different files, look at {#globals}.
+    #
+    # @see Handlers::Base
+    class Processor
+
+      class << self
+        # Registers a new namespace for handlers of the given type.
+        # @since 0.6.0
+        def register_handler_namespace(type, ns)
+          namespace_for_handler[type] = ns
+        end
+
+        # @return [Hash] a list of registered parser type extensions
+        # @private
+        # @since 0.6.0
+        attr_reader :namespace_for_handler
+        undef namespace_for_handler
+        def namespace_for_handler; @@parser_type_extensions ||= {} end
+      end
+
+      register_handler_namespace :ruby, Ruby
+      register_handler_namespace :ruby18, Ruby::Legacy
+      register_handler_namespace :c, C
+
+      # @return [String] the filename
+      attr_accessor :file
+
+      # @return [CodeObjects::NamespaceObject] the current namespace
+      attr_accessor :namespace
+
+      # @return [Symbol] the current visibility (public, private, protected)
+      attr_accessor :visibility
+
+      # @return [Symbol] the current scope (class, instance)
+      attr_accessor :scope
+
+      # @return [CodeObjects::Base, nil] unlike the namespace, the owner
+      #   is a non-namespace object that should be stored between statements.
+      #   For instance, when parsing a method body, the {CodeObjects::MethodObject}
+      #   is set as the owner, in case any extra method information is processed.
+      attr_accessor :owner
+
+      # @return [Symbol] the parser type (:ruby, :ruby18, :c)
+      attr_accessor :parser_type
+
+      # Handlers can share state for the entire post processing stage through
+      # this attribute. Note that post processing stage spans multiple files.
+      # To share state only within a single file, use {#extra_state}
+      #
+      # @example Sharing state among two handlers
+      #   class Handler1 < YARD::Handlers::Ruby::Base
+      #     handles :class
+      #     process { globals.foo = :bar }
+      #   end
+      #
+      #   class Handler2 < YARD::Handlers::Ruby::Base
+      #     handles :method
+      #     process { puts globals.foo }
+      #   end
+      # @return [OpenStruct] global shared state for post-processing stage
+      # @see #extra_state
+      attr_accessor :globals
+
+      # Share state across different handlers inside of a file.
+      # This attribute is similar to {#visibility}, {#scope}, {#namespace}
+      # and {#owner}, in that they all maintain state across all handlers
+      # for the entire source file. Use this attribute to store any data
+      # your handler might need to save during the parsing of a file. If
+      # you need to save state across files, see {#globals}.
+      #
+      # @return [OpenStruct] an open structure that can store arbitrary data
+      # @see #globals
+      attr_accessor :extra_state
+
+      # Creates a new Processor for a +file+.
+      # @param [SourceParser] parser the parser used to initialize the processor
+      def initialize(parser)
+        @file = parser.file || "(stdin)"
+        @namespace = YARD::Registry.root
+        @visibility = :public
+        @scope = :instance
+        @owner = @namespace
+        @parser_type = parser.parser_type
+        @handlers_loaded = {}
+        @globals = parser.globals || OpenStruct.new
+        @extra_state = OpenStruct.new
+        load_handlers
+      end
+
+      # Processes a list of statements by finding handlers to process each
+      # one.
+      #
+      # @param [Array] statements a list of statements
+      # @return [void]
+      def process(statements)
+        statements.each_with_index do |stmt, index|
+          find_handlers(stmt).each do |handler|
+            begin
+              handler.new(self, stmt).process
+            rescue HandlerAborted => abort
+              log.debug "#{handler.to_s} cancelled from #{caller.last}"
+              log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
+            rescue NamespaceMissingError => missingerr
+              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized."
+              log.warn "If this class/method is part of your source tree, this will affect your documentation results."
+              log.warn "You can correct this issue by loading the source file for this object before `#{file}'"
+              log.warn
+            rescue Parser::UndocumentableError => undocerr
+              log.warn "in #{handler.to_s}: Undocumentable #{undocerr.message}"
+              log.warn "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
+            rescue => e
+              log.error "Unhandled exception in #{handler.to_s}:"
+              log.error "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
+              log.backtrace(e)
+            end
+          end
+        end
+      end
+
+      # Continue parsing the remainder of the files in the +globals.ordered_parser+
+      # object. After the remainder of files are parsed, processing will continue
+      # on the current file.
+      #
+      # @return [void]
+      # @see Parser::OrderedParser
+      def parse_remaining_files
+        if globals.ordered_parser
+          globals.ordered_parser.parse
+          log.debug("Re-processing #{@file}...")
+        end
+      end
+
+      # Searches for all handlers in {Base.subclasses} that match the +statement+
+      #
+      # @param statement the statement object to match.
+      # @return [Array<Base>] a list of handlers to process the statement with.
+      def find_handlers(statement)
+        Base.subclasses.find_all do |handler|
+          handler_base_class > handler &&
+          (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
+          handles?(handler, statement)
+        end
+      end
+
+      private
+
+      def handles?(handler, statement)
+        return false unless handler.matches_file?(file)
+        if handler.method(:handles?).arity == 1
+          handler.handles?(statement)
+        elsif [-1, 2].include?(handler.method(:handles?).arity)
+          handler.handles?(statement, self)
+        end
+      end
+
+      # Returns the handler base class
+      # @return [Base] the base class
+      def handler_base_class
+        handler_base_namespace.const_get(:Base)
+      end
+
+      # The module holding the handlers to be loaded
+      #
+      # @return [Module] the module containing the handlers depending on
+      #   {#parser_type}.
+      def handler_base_namespace
+        self.class.namespace_for_handler[parser_type]
+      end
+
+      # Loads handlers from {#handler_base_namespace}. This ensures that
+      # Ruby1.9 handlers are never loaded into 1.8; also lowers the amount
+      # of modules that are loaded
+      # @return [void]
+      def load_handlers
+        return if @handlers_loaded[parser_type]
+        handler_base_namespace.constants.each do |c|
+          const = handler_base_namespace.const_get(c)
+          unless Handlers::Base.subclasses.include?(const)
+            Handlers::Base.subclasses << const
+          end
+        end
+        @handlers_loaded[parser_type] = true
+      end
+    end
+  end
+end