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 29
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 69
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 37
def comments
  @comments ||= ''
end
completion_item_kind() click to toggle source

@return [Integer]

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

@return [Boolean]

# File lib/solargraph/pin/base.rb, line 128
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 104
def directives
  parse_comments unless defined?(@directives)
  @directives
end
docstring() click to toggle source

@return [YARD::Docstring]

# File lib/solargraph/pin/base.rb, line 98
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 42
def filename
  return nil if location.nil?
  location.filename
end
identity() click to toggle source
# File lib/solargraph/pin/base.rb, line 216
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 155
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 220
def inspect
  "#<#{self.class} at #{self.location.inspect}>"
end
macros() click to toggle source

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

# File lib/solargraph/pin/base.rb, line 110
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 122
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 80
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 148
def probe api_map
  typify api_map
end
probed?() click to toggle source
# File lib/solargraph/pin/base.rb, line 186
def probed?
  @probed ||= false
end
proxied?() click to toggle source
# File lib/solargraph/pin/base.rb, line 182
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 209
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 192
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 93
def return_type
  @return_type ||= ComplexType::UNDEFINED
end
symbol_kind() click to toggle source

@return [Integer, nil]

# File lib/solargraph/pin/base.rb, line 53
def symbol_kind
  nil
end
to_s() click to toggle source
# File lib/solargraph/pin/base.rb, line 57
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 168
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 140
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 62
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 289
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 269
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 258
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 280
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 238
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