kinetic_sdk 5.0.19 → 5.0.20

data/gems/yard-0.9.25/lib/yard/handlers/c/base.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+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
+
+          src = statement.respond_to?(:declaration) ?
+            statement.declaration : statement.source
+
+          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)
+          if type
+            @statement_class = type
+          else
+            (defined?(@statement_class) && @statement_class) || Statement
+          end
+        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]
+
+          # The global variables for Ruby's core error classes does not
+          # represent their Ruby name. So we need to look up these names.
+          name = ERROR_CLASS_NAMES[var]
+          return P(name) if name
+
+          # Otherwise the name is inferred from the C variable name.
+          var = remove_var_prefix(var)
+          var.empty? ? nil : P(var)
+        end
+
+        def ensure_variable_defined!(var, max_retries = 1)
+          retries = 0
+          object = nil
+
+          loop do
+            object = namespace_for_variable(var)
+            break unless object.is_a?(Proxy)
+
+            raise NamespaceMissingError, object if retries > max_retries
+            log.debug "Missing namespace variable #{var} in file `#{parser.file}', moving it to the back of the line."
+            parser.parse_remaining_files
+            retries += 1
+          end
+
+          object
+        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
+
+        # Generated by update_error_map.rb (Copy+past results)
+        ERROR_CLASS_NAMES = {
+          'rb_eArgError' => 'ArgumentError',
+          'rb_eEncodingError' => 'EncodingError',
+          'rb_eException' => 'Exception',
+          'rb_eFatal' => 'fatal',
+          'rb_eFrozenError' => 'FrozenError',
+          'rb_eIndexError' => 'IndexError',
+          'rb_eInterrupt' => 'Interrupt',
+          'rb_eKeyError' => 'KeyError',
+          'rb_eLoadError' => 'LoadError',
+          'rb_eNameError' => 'NameError',
+          'rb_eNoMatchingPatternError' => 'NoMatchingPatternError',
+          'rb_eNoMemError' => 'NoMemoryError',
+          'rb_eNoMethodError' => 'NoMethodError',
+          'rb_eNotImpError' => 'NotImplementedError',
+          'rb_eRangeError' => 'RangeError',
+          'rb_eRuntimeError' => 'RuntimeError',
+          'rb_eScriptError' => 'ScriptError',
+          'rb_eSecurityError' => 'SecurityError',
+          'rb_eSignal' => 'SignalException',
+          'rb_eStandardError' => 'StandardError',
+          'rb_eSyntaxError' => 'SyntaxError',
+          'rb_eSystemCallError' => 'SystemCallError',
+          'rb_eSystemExit' => 'SystemExit',
+          'rb_eTypeError' => 'TypeError',
+        }
+
+        def remove_var_prefix(var)
+          var.gsub(/^rb_[mc]|^[a-z_]+/, '')
+        end
+      end
+    end
+  end
+end

data/gems/yard-0.9.25/lib/yard/handlers/c/class_handler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+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.strip, in_module)
+    end
+  end
+end

data/gems/yard-0.9.25/lib/yard/handlers/c/constant_handler.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+class YARD::Handlers::C::ConstantHandler < YARD::Handlers::C::Base
+  MATCH = /\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/gems/yard-0.9.25/lib/yard/handlers/c/handler_methods.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+module YARD
+  module Handlers
+    module C
+      module HandlerMethods
+        include Parser::C
+        include CodeObjects
+        include Common::MethodHandler
+
+        def handle_class(var_name, class_name, parent, in_module = nil)
+          parent = nil if parent == "0"
+          namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
+          if namespace.nil?
+            raise Parser::UndocumentableError,
+              "class #{class_name}. Cannot find definition for parent namespace."
+          end
+
+          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 ? ensure_variable_defined!(in_module) : Registry.root
+          if namespace.nil?
+            raise Parser::UndocumentableError,
+              "module #{module_name}. Cannot find definition for parent namespace."
+          end
+
+          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)
+
+          # Is this method being defined on a core Ruby class or module?
+          if namespace.is_a?(Proxy)
+            if var_name =~ /^rb_c(\w+)/ && YARD::CodeObjects::BUILTIN_CLASSES.include?($1)
+              namespace = namespaces[var_name] = YARD::CodeObjects::ClassObject.new(:root, $1)
+            elsif var_name =~ /^rb_m(\w+)/ && YARD::CodeObjects::BUILTIN_MODULES.include?($1)
+              namespace = namespaces[var_name] = YARD::CodeObjects::ModuleObject.new(:root, $1)
+            end
+          end
+
+          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.explicit = true
+            add_predicate_return_tag(obj) 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)
+            register_file_info(obj, statement.file, statement.line)
+            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 = new_name.to_sym
+          old_meth = 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$|^global_const$/
+          namespace = type == 'global_const' ?
+            :root : 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
+              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 = statement.file
+          in_file = false
+          if statement.comments && statement.comments.source =~ /\A\s*in (\S+)\Z/
+            file = $1
+            in_file = true
+            process_file(file, object)
+          end
+
+          src_stmt = symbols[symbol]
+          if src_stmt
+            register_file_info(object, src_stmt.file, src_stmt.line, true)
+            register_source(object, src_stmt)
+            record_parameters(object, symbol, 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
+          return if override_comments.any? do |name, override_comment|
+            next unless override_comment.file == file
+            name = name.gsub(/::([^:\.#]+?)\Z/, '.\1')
+
+            # explicit namespace in override comment
+            path = (name =~ /\.|#/ ? object.path : object.name.to_s)
+            if path == name || path == name.sub(/new$/, 'initialize') || path == name.sub('.', '#')
+              register_docstring(object, override_comment.source, override_comment)
+              true
+            else
+              false
+            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
+
+        def record_parameters(object, symbol, src)
+          # use regex to extract comma-delimited list of parameters from cfunc definition
+          if src.source =~ /VALUE\s+#{symbol}\(([^)]*)\)\s*\{/m
+            params = $~[1].split(/\s*,\s*/) # rubocop:disable Style/SpecialGlobalVars
+            # cfunc for a "varargs" method has params "int argc, VALUE *argv"
+            if params[0] =~ /int\s+argc/ && params[1] =~ /VALUE\s*\*\s*argv/
+              object.parameters = [['*args', nil]]
+            else
+              # the first cfunc argument is the 'self' argument, we don't need that
+              object.parameters = params.drop(1).map {|s| [s[/VALUE\s+(\S+)/, 1], nil] }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/gems/yard-0.9.25/lib/yard/handlers/c/init_handler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# Handles the Init_Libname() method
+class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
+  MATCH = /\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*/
+  handles MATCH
+  statement_class ToplevelStatement
+
+  process do
+    parse_block
+    decl = statement.declaration[MATCH, 1]
+    if decl
+      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/gems/yard-0.9.25/lib/yard/handlers/c/method_handler.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
+  MATCH1 = /rb_define_
+                 (
+                    singleton_method |
+                    method           |
+                    module_function  |
+                    private_method
+                 )
+                 \s*\(\s*([\w\.]+)\s*,
+                   \s*"([^"]+)"\s*,
+                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
+                   \s*(-?\w+)\s*\)/xm
+  MATCH2 = /rb_define_global_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                \s*(-?\w+)\s*\)/xm
+  MATCH3 = /define_filetest_function\s*\(
+                \s*"([^"]+)",
+                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                \s*(-?\w+)\s*\)/xm
+  handles MATCH1
+  handles MATCH2
+  handles MATCH3
+  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
+
+    statement.source.scan(MATCH3) do |name, func_name, _param_count|
+      handle_method("singleton_method", "rb_cFile", name, func_name)
+    end
+  end
+end

data/gems/yard-0.9.25/lib/yard/handlers/c/mixin_handler.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+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)
+
+      var = namespace_for_variable(mixin_var)
+      if var
+        namespace.mixins(:instance) << var
+      else
+        raise YARD::Parser::UndocumentableError,
+          "CRuby mixin for unrecognized variable '#{mixin_var}'"
+      end
+    end
+  end
+end

data/gems/yard-0.9.25/lib/yard/handlers/c/module_handler.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+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/gems/yard-0.9.25/lib/yard/handlers/c/override_comment_handler.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# Parses comments
+class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
+  handles(/./)
+  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/gems/yard-0.9.25/lib/yard/handlers/c/path_handler.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+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/gems/yard-0.9.25/lib/yard/handlers/c/struct_handler.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+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/gems/yard-0.9.25/lib/yard/handlers/c/symbol_handler.rb

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

data/gems/yard-0.9.25/lib/yard/handlers/common/method_handler.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module YARD::Handlers
+  module Common
+    # Shared functionality between Ruby and C method handlers.
+    module MethodHandler
+      # @param [MethodObject] obj
+      def add_predicate_return_tag(obj)
+        if obj.tag(:return) && (obj.tag(:return).types || []).empty?
+          obj.tag(:return).types = ['Boolean']
+        elsif obj.tag(:return).nil?
+          unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
+            obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
+          end
+        end
+      end
+    end
+  end
+end