# Class: YARD::Handlers::C::Base

Inherits:
  Handlers::Base
  - Object
  - Handlers::Base
  - YARD::Handlers::C::Base
  show all

Includes:
  HandlerMethods, Parser::C

Defined in:
  lib/yard/handlers/c/base.rb

## Overview

Since:

- 0.8.0

## Direct Known Subclasses

AliasHandler, AttributeHandler, ClassHandler, ConstantHandler, InitHandler, MethodHandler, MixinHandler, ModuleHandler, OverrideCommentHandler, PathHandler, StructHandler, SymbolHandler

## Constant Summary

### Constants included from CodeObjects

CodeObjects::BUILTIN_ALL, CodeObjects::BUILTIN_CLASSES, CodeObjects::BUILTIN_EXCEPTIONS, CodeObjects::BUILTIN_EXCEPTIONS_HASH, CodeObjects::BUILTIN_MODULES, CodeObjects::CONSTANTMATCH, CodeObjects::CONSTANTSTART, CodeObjects::CSEP, CodeObjects::CSEPQ, CodeObjects::ISEP, CodeObjects::ISEPQ, CodeObjects::METHODMATCH, CodeObjects::METHODNAMEMATCH, CodeObjects::NAMESPACEMATCH, CodeObjects::NSEP, CodeObjects::NSEPQ

## Registering objects collapse

- #register_docstring(object, docstring = nil, stmt = nil) ⇒ Object
- #register_file_info(object, file = nil, line = nil, comments = nil) ⇒ Object
- #register_source(object, source = nil, type = nil) ⇒ Object
- #register_visibility(object, visibility = nil) ⇒ Object

## Looking up Symbol and Var Values collapse

- #ensure_variable_defined!(var, max_retries = 1) ⇒ Object
- #namespace_for_variable(var) ⇒ Object
- #namespaces ⇒ Object
- #override_comments ⇒ Object
- #processed_files ⇒ Object
- #symbols ⇒ Object

## Parsing an Inner Block collapse

- #parse_block(opts = {}) ⇒ Object

## Processing other files collapse

- #process_file(file, object) ⇒ Object

## Class Method Summary collapse

- .handles?(statement, processor) ⇒ Boolean

  Whether the handler handles this statement.

- .statement_class(type = nil) ⇒ Object

### Methods included from HandlerMethods

#handle_alias, #handle_attribute, #handle_class, #handle_constants, #handle_method, #handle_module

### Methods included from YARD::Handlers::Common::MethodHandler

#add_predicate_return_tag

### Methods included from CodeObjects::NamespaceMapper

#clear_separators, #default_separator, on_invalidate, #register_separator, #separators, #separators_for_type, #separators_match, #types_for_separator, #unregister_separator_by_type

## Class Method Details

### .handles?(statement, processor) ⇒ `Boolean`

Returns whether the handler handles this statement.

Returns:

- (`Boolean`) —

  whether the handler handles this statement

Since:

- 0.8.0

    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26

    # File 'lib/yard/handlers/c/base.rb', line 10

    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

### .statement_class(type = nil) ⇒ `Object`

Since:

- 0.8.0

    28
    29
    30
    31
    32
    33
    34

    # File 'lib/yard/handlers/c/base.rb', line 28

    def self.statement_class(type = nil)
      if type
        @statement_class = type
      else
        (defined?(@statement_class) && @statement_class) || Statement
      end
    end

## Instance Method Details

### #ensure_variable_defined!(var, max_retries = 1) ⇒ `Object`

Since:

- 0.8.0

    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92

    # File 'lib/yard/handlers/c/base.rb', line 77

    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

### #namespace_for_variable(var) ⇒ `Object`

Since:

- 0.8.0

    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75

    # File 'lib/yard/handlers/c/base.rb', line 64

    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

### #namespaces ⇒ `Object`

Since:

- 0.8.0

    94
    95
    96

    # File 'lib/yard/handlers/c/base.rb', line 94

    def namespaces
      globals.cruby_namespaces ||= {}
    end

### #override_comments ⇒ `Object`

Since:

- 0.8.0

    60
    61
    62

    # File 'lib/yard/handlers/c/base.rb', line 60

    def override_comments
      globals.cruby_override_comments ||= []
    end

### #parse_block(opts = {}) ⇒ `Object`

Since:

- 0.8.0

    104
    105
    106
    107
    108
    109

    # File 'lib/yard/handlers/c/base.rb', line 104

    def parse_block(opts = {})
      return if !statement.block || statement.block.empty?
      push_state(opts) do
        parser.process(statement.block)
      end
    end

### #process_file(file, object) ⇒ `Object`

Since:

- 0.8.0

    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124

    # File 'lib/yard/handlers/c/base.rb', line 113

    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

### #processed_files ⇒ `Object`

Since:

- 0.8.0

    98
    99
    100

    # File 'lib/yard/handlers/c/base.rb', line 98

    def processed_files
      globals.cruby_processed_files ||= {}
    end

### #register_docstring(object, docstring = nil, stmt = nil) ⇒ `Object`

Since:

- 0.8.0

    38
    39
    40

    # File 'lib/yard/handlers/c/base.rb', line 38

    def register_docstring(object, docstring = nil, stmt = nil)
      super(object, docstring, stmt) if docstring
    end

### #register_file_info(object, file = nil, line = nil, comments = nil) ⇒ `Object`

Since:

- 0.8.0

    42
    43
    44

    # File 'lib/yard/handlers/c/base.rb', line 42

    def register_file_info(object, file = nil, line = nil, comments = nil)
      super(object, file, line, comments) if file
    end

### #register_source(object, source = nil, type = nil) ⇒ `Object`

Since:

- 0.8.0

    46
    47
    48

    # File 'lib/yard/handlers/c/base.rb', line 46

    def register_source(object, source = nil, type = nil)
      super(object, source, type) if source
    end

### #register_visibility(object, visibility = nil) ⇒ `Object`

Since:

- 0.8.0

    50
    51
    52

    # File 'lib/yard/handlers/c/base.rb', line 50

    def register_visibility(object, visibility = nil)
      super(object, visibility) if visibility
    end

### #symbols ⇒ `Object`

Since:

- 0.8.0

    56
    57
    58

    # File 'lib/yard/handlers/c/base.rb', line 56

    def symbols
      globals.cruby_symbols ||= {}
    end