class Solargraph::Pin::Base

The base class for map pins.

Attributes

code_object[R]

@return [YARD::CodeObjects::Base]

location[R]

@return [Solargraph::Location]

name[R]

@return [String]

path[R]

@return [String]

probed[W]

@return [Boolean]

proxied[W]

@return [Boolean]

return_type[W]

@return [ComplexType]

Public Class Methods

new(location: nil, closure: nil, name: '', comments: '') click to toggle source

@param location [Solargraph::Location] @param kind [Integer] @param closure [Solargraph::Pin::Closure] @param name [String] @param comments [String]

# File lib/solargraph/pin/base.rb, line 28
def initialize location: nil, closure: nil, name: '', comments: ''
  @location = location
  @closure = closure
  @name = name
  @comments = comments
end

Public Instance Methods

==(other) click to toggle source

Pin equality is determined using the nearly? method and also requiring both pins to have the same location.

# File lib/solargraph/pin/base.rb, line 68
def == other
  return false unless nearly? other
  comments == other.comments and location == other.location
end
comments() click to toggle source

@return [String]

# File lib/solargraph/pin/base.rb, line 36
def comments
  @comments ||= ''
end
completion_item_kind() click to toggle source

@return [Integer]

# File lib/solargraph/pin/base.rb, line 47
def completion_item_kind
  LanguageServer::CompletionItemKinds::KEYWORD
end
deprecated?() click to toggle source

@return [Boolean]

# File lib/solargraph/pin/base.rb, line 127
def deprecated?
  @deprecated ||= docstring.has_tag?('deprecated')
end
directives() click to toggle source

@return [Array<YARD::Tags::Directive>]

# File lib/solargraph/pin/base.rb, line 103
def directives
  parse_comments unless defined?(@directives)
  @directives
end
docstring() click to toggle source

@return [YARD::Docstring]

# File lib/solargraph/pin/base.rb, line 97
def docstring
  parse_comments unless defined?(@docstring)
  @docstring ||= Solargraph::Source.parse_docstring('').to_docstring
end
filename() click to toggle source

@return [String, nil]

# File lib/solargraph/pin/base.rb, line 41
def filename
  return nil if location.nil?
  location.filename
end
identity() click to toggle source
# File lib/solargraph/pin/base.rb, line 215
def identity
  @identity ||= "#{closure.context.namespace}|#{name}"
end
infer(api_map) click to toggle source

@deprecated Use typify and/or probe instead @param api_map [ApiMap] @return [ComplexType]

# File lib/solargraph/pin/base.rb, line 154
def infer api_map
  Solargraph::Logging.logger.warn "WARNING: Pin #infer methods are deprecated. Use #typify or #probe instead."
  type = typify(api_map)
  return type unless type.undefined?
  probe api_map
end
inspect() click to toggle source
# File lib/solargraph/pin/base.rb, line 219
def inspect
  "#<#{self.class} `#{self.path}` at #{self.location.inspect}>"
end
macros() click to toggle source

@return [Array<YARD::Tags::MacroDirective>]

# File lib/solargraph/pin/base.rb, line 109
def macros
  @macros ||= collect_macros
end
maybe_directives?() click to toggle source

Perform a quick check to see if this pin possibly includes YARD directives. This method does not require parsing the comments.

After the comments have been parsed, this method will return false if no directives were found, regardless of whether it previously appeared possible.

@return [Boolean]

# File lib/solargraph/pin/base.rb, line 121
def maybe_directives?
  return !@directives.empty? if defined?(@directives)
  @maybe_directives ||= comments.include?('@!')
end
nearly?(other) click to toggle source

True if the specified pin is a near match to this one. A near match indicates that the pins contain mostly the same data. Any differences between them should not have an impact on the API surface.

@param other [Solargraph::Pin::Base, Object] @return [Boolean]

# File lib/solargraph/pin/base.rb, line 79
def nearly? other
  self.class == other.class &&
    name == other.name &&
    (closure == other.closure || (closure && closure.nearly?(other.closure))) &&
    (comments == other.comments ||
      (((maybe_directives? == false && other.maybe_directives? == false) || compare_directives(directives, other.directives)) &&
      compare_docstring_tags(docstring, other.docstring))
    )
end
probe(api_map) click to toggle source

Infer the pin's return type via static code analysis.

@param api_map [ApiMap] @return [ComplexType]

# File lib/solargraph/pin/base.rb, line 147
def probe api_map
  typify api_map
end
probed?() click to toggle source
# File lib/solargraph/pin/base.rb, line 185
def probed?
  @probed ||= false
end
proxied?() click to toggle source
# File lib/solargraph/pin/base.rb, line 181
def proxied?
  @proxied ||= false
end
proxy(return_type) click to toggle source

Return a proxy for this pin with the specified return type. Other than the return type and the proxied? setting, the proxy should be a clone of the original.

@param #return_type [ComplexType] @return [self]

# File lib/solargraph/pin/base.rb, line 208
def proxy return_type
  result = dup
  result.return_type = return_type
  result.proxied = true
  result
end
realize(api_map) click to toggle source

@param api_map [ApiMap] @return [self]

# File lib/solargraph/pin/base.rb, line 191
def realize api_map
  return self if return_type.defined?
  type = typify(api_map)
  return proxy(type) if type.defined?
  type = probe(api_map)
  return self if type.undefined?
  result = proxy(type)
  result.probed = true
  result
end
return_type() click to toggle source

The pin's return type.

@return [ComplexType]

# File lib/solargraph/pin/base.rb, line 92
def return_type
  @return_type ||= ComplexType::UNDEFINED
end
symbol_kind() click to toggle source

@return [Integer, nil]

# File lib/solargraph/pin/base.rb, line 52
def symbol_kind
  nil
end
to_s() click to toggle source
# File lib/solargraph/pin/base.rb, line 56
def to_s
  name.to_s
end
try_merge!(pin) click to toggle source

Try to merge data from another pin. Merges are only possible if the pins are near matches (see the nearly? method). The changes should not have any side effects on the API surface.

@param pin [Pin::Base] The pin to merge into this one @return [Boolean] True if the pins were merged

# File lib/solargraph/pin/base.rb, line 167
def try_merge! pin
  return false unless nearly?(pin)
  @location = pin.location
  @closure = pin.closure
  return true if comments == pin.comments
  @comments = pin.comments
  @docstring = pin.docstring
  @return_type = pin.return_type
  @documentation = nil
  @deprecated = nil
  reset_conversions
  true
end
typify(api_map) click to toggle source

Get a fully qualified type from the pin's return type.

The relative type is determined from YARD documentation (@return, @param, @type, etc.) and its namespaces are fully qualified using the provided ApiMap.

@param api_map [ApiMap] @return [ComplexType]

# File lib/solargraph/pin/base.rb, line 139
def typify api_map
  return_type.qualify(api_map, namespace)
end
variable?() click to toggle source

@return [Boolean]

# File lib/solargraph/pin/base.rb, line 61
def variable?
  false
end

Private Instance Methods

collect_macros() click to toggle source

@return [Array<YARD::Tags::Handlers::Directive>]

# File lib/solargraph/pin/base.rb, line 288
def collect_macros
  return [] unless maybe_directives?
  parse = Solargraph::Source.parse_docstring(comments)
  parse.directives.select{ |d| d.tag.tag_name == 'macro' }
end
compare_directives(dir1, dir2) click to toggle source

@param dir1 [Array<YARD::Tags::Directive>] @param dir2 [Array<YARD::Tags::Directive>] @return [Boolean]

# File lib/solargraph/pin/base.rb, line 268
def compare_directives dir1, dir2
  return false if dir1.length != dir2.length
  dir1.each_index do |i|
    return false unless compare_tags(dir1[i].tag, dir2[i].tag)
  end
  true
end
compare_docstring_tags(d1, d2) click to toggle source

True if two docstrings have the same tags, regardless of any other differences.

@param d1 [YARD::Docstring] @param d2 [YARD::Docstring] @return [Boolean]

# File lib/solargraph/pin/base.rb, line 257
def compare_docstring_tags d1, d2
  return false if d1.tags.length != d2.tags.length
  d1.tags.each_index do |i|
    return false unless compare_tags(d1.tags[i], d2.tags[i])
  end
  true
end
compare_tags(tag1, tag2) click to toggle source

@param tag1 [YARD::Tags::Tag] @param tag2 [YARD::Tags::Tag] @return [Boolean]

# File lib/solargraph/pin/base.rb, line 279
def compare_tags tag1, tag2
  tag1.class == tag2.class &&
    tag1.tag_name == tag2.tag_name &&
    tag1.text == tag2.text &&
    tag1.name == tag2.name &&
    tag1.types == tag2.types
end
parse_comments() click to toggle source

@return [void]

# File lib/solargraph/pin/base.rb, line 237
def parse_comments
  # HACK: Avoid a NoMethodError on nil with empty overload tags
  if comments.nil? || comments.empty? || comments.strip.end_with?('@overload')
    @docstring = nil
    @directives = []
  else
    # HACK: Pass a dummy code object to the parser for plugins that
    # expect it not to be nil
    parse = Solargraph::Source.parse_docstring(comments)
    @docstring = parse.to_docstring
    @directives = parse.directives
  end
end