Class: Solargraph::Pin::Base

Inherits:
Object
  • Object
show all
Includes:
Common, Conversions, Documenting
Defined in:
lib/solargraph/pin/base.rb

Overview

The base class for map pins.

Direct Known Subclasses

BaseVariable, Closure, Keyword, ProxyType, Reference, Symbol, Until, While

Instance Attribute Summary collapse

Attributes included from Common

#closure, #context

Instance Method Summary collapse

Methods included from Documenting

#documentation, normalize_indentation, strip_html_comments

Methods included from Conversions

#completion_item, #detail, #link_documentation, #reset_conversions, #resolve_completion_item, #signature_help, #text_documentation

Methods included from Common

#binder, #namespace

Constructor Details

#initialize(location: nil, type_location: nil, closure: nil, source: nil, name: '', comments: '') ⇒ Base

Returns a new instance of Base.

Parameters:



39
40
41
42
43
44
45
46
47
 
# File 'lib/solargraph/pin/base.rb', line 39

def initialize location: nil, type_location: nil, closure: nil, source: nil, name: '', comments: ''
  @location = location
  @type_location = type_location
  @closure = closure
  @name = name
  @comments = comments
  @source = source
  assert_source_provided
end

Instance Attribute Details

#code_object ⇒ YARD::CodeObjects::Base (readonly)

Returns:

  • (YARD::CodeObjects::Base) 


13
14
15
 
# File 'lib/solargraph/pin/base.rb', line 13

def code_object
  @code_object
end

#location ⇒ Solargraph::Location (readonly)

Returns:



16
17
18
 
# File 'lib/solargraph/pin/base.rb', line 16

def location
  @location
end

#name ⇒ String (readonly)

Returns:

  • (String) 


22
23
24
 
# File 'lib/solargraph/pin/base.rb', line 22

def name
  @name
end

#path ⇒ String (readonly)

Returns:

  • (String) 


25
26
27
 
# File 'lib/solargraph/pin/base.rb', line 25

def path
  @path
end

#return_type ⇒ ComplexType

The pin’s return type.

Returns:



155
156
157
 
# File 'lib/solargraph/pin/base.rb', line 155

def return_type
  @return_type ||= ComplexType::UNDEFINED
end

#source ⇒ ::Symbol

Returns:

  • (::Symbol) 


28
29
30
 
# File 'lib/solargraph/pin/base.rb', line 28

def source
  @source
end

#type_location ⇒ Solargraph::Location (readonly)

Returns:



19
20
21
 
# File 'lib/solargraph/pin/base.rb', line 19

def type_location
  @type_location
end

Instance Method Details

#==(other) ⇒ Object

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



147
148
149
150
 
# File 'lib/solargraph/pin/base.rb', line 147

def == other
  return false unless nearly? other
  comments == other.comments && location == other.location
end

#all_location_text ⇒ Object 



320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/solargraph/pin/base.rb', line 320

def all_location_text
  if location.nil? && type_location.nil?
    ''
  elsif !location.nil? && type_location.nil?
    " at #{location.inspect})"
  elsif !type_location.nil? && location.nil?
    " at #{type_location.inspect})"
  else
    " at (#{location.inspect} and #{type_location.inspect})"
  end
end

#all_rooted? ⇒ Boolean

Returns:

  • (Boolean) 


87
88
89
 
# File 'lib/solargraph/pin/base.rb', line 87

def all_rooted?
  !return_type || return_type.all_rooted?
end

#assert_source_provided ⇒ Object 



49
50
51
 
# File 'lib/solargraph/pin/base.rb', line 49

def assert_source_provided
  Solargraph.assert_or_log(:source, "source not provided - #{@path} #{@source} #{self.class}") if source.nil?
end

#best_location ⇒ Location?

Returns:



124
125
126
 
# File 'lib/solargraph/pin/base.rb', line 124

def best_location
  location || type_location
end

#comments ⇒ String

Returns:

  • (String) 


54
55
56
 
# File 'lib/solargraph/pin/base.rb', line 54

def comments
  @comments ||= ''
end

#completion_item_kind ⇒ Integer

Returns:

  • (Integer) 


105
106
107
 
# File 'lib/solargraph/pin/base.rb', line 105

def completion_item_kind
  LanguageServer::CompletionItemKinds::KEYWORD
end

#deprecated? ⇒ Boolean

Returns:

  • (Boolean) 


190
191
192
 
# File 'lib/solargraph/pin/base.rb', line 190

def deprecated?
  @deprecated ||= docstring.has_tag?('deprecated')
end

#desc ⇒ Object 



312
313
314
 
# File 'lib/solargraph/pin/base.rb', line 312

def desc
  "[#{inner_desc}]"
end

#directives ⇒ ::Array<YARD::Tags::Directive>

Returns:

  • (::Array<YARD::Tags::Directive>) 


166
167
168
169
 
# File 'lib/solargraph/pin/base.rb', line 166

def directives
  parse_comments unless defined?(@directives)
  @directives
end

#docstring ⇒ YARD::Docstring

Returns:

  • (YARD::Docstring) 


160
161
162
163
 
# File 'lib/solargraph/pin/base.rb', line 160

def docstring
  parse_comments unless defined?(@docstring)
  @docstring ||= Solargraph::Source.parse_docstring('').to_docstring
end

#erase_generics(generics_to_erase) ⇒ self

Parameters:

  • generics_to_erase (::Array<String>)

Returns:

  • (self) 


93
94
95
96
 
# File 'lib/solargraph/pin/base.rb', line 93

def erase_generics(generics_to_erase)
  return self if generics_to_erase.empty?
  transform_types { |t| t.erase_generics(generics_to_erase) }
end

#filename ⇒ String?

Returns:

  • (String, nil) 


99
100
101
102
 
# File 'lib/solargraph/pin/base.rb', line 99

def filename
  return nil if location.nil?
  location.filename
end

#identity ⇒ String

Deprecated.

Returns:

  • (String) 


280
281
282
 
# File 'lib/solargraph/pin/base.rb', line 280

def identity
  @identity ||= "#{closure&.path}|#{name}|#{location}"
end

#infer(api_map) ⇒ ComplexType

Deprecated.

Use #typify and/or #probe instead

Parameters:

Returns:



217
218
219
220
221
222
 
# File 'lib/solargraph/pin/base.rb', line 217

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

#inner_desc ⇒ String

Returns:

  • (String) 


306
307
308
309
310
 
# File 'lib/solargraph/pin/base.rb', line 306

def inner_desc
  closure_info = closure&.desc
  binder_info = binder&.desc
  "name=#{name.inspect} return_type=#{type_desc}, context=#{context.rooted_tags}, closure=#{closure_info}, binder=#{binder_info}"
end

#inspect ⇒ Object 



316
317
318
 
# File 'lib/solargraph/pin/base.rb', line 316

def inspect
  "#<#{self.class} `#{self.inner_desc}`#{all_location_text} via #{source.inspect}>"
end

#macros ⇒ ::Array<YARD::Tags::MacroDirective>

Returns:

  • (::Array<YARD::Tags::MacroDirective>) 


172
173
174
 
# File 'lib/solargraph/pin/base.rb', line 172

def macros
  @macros ||= collect_macros
end

#maybe_directives? ⇒ Boolean

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.

Returns:

  • (Boolean) 


184
185
186
187
 
# File 'lib/solargraph/pin/base.rb', line 184

def maybe_directives?
  return !@directives.empty? if defined?(@directives)
  @maybe_directives ||= comments.include?('@!')
end

#nearly?(other) ⇒ Boolean

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.

Parameters:

Returns:

  • (Boolean) 


134
135
136
137
138
139
140
141
142
 
# File 'lib/solargraph/pin/base.rb', line 134

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

#presence_certain? ⇒ Boolean

Returns:

  • (Boolean) 


30
31
32
 
# File 'lib/solargraph/pin/base.rb', line 30

def presence_certain?
  true
end

#probe(api_map) ⇒ ComplexType

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

Parameters:

Returns:



210
211
212
 
# File 'lib/solargraph/pin/base.rb', line 210

def probe api_map
  typify api_map
end

#probed? ⇒ Boolean

Returns:

  • (Boolean) 


248
249
250
 
# File 'lib/solargraph/pin/base.rb', line 248

def probed?
  @probed ||= false
end

#proxied? ⇒ Boolean

Returns:

  • (Boolean) 


244
245
246
 
# File 'lib/solargraph/pin/base.rb', line 244

def proxied?
  @proxied ||= false
end

#proxy(return_type) ⇒ self

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.

Parameters:

Returns:

  • (self) 


271
272
273
274
275
276
 
# File 'lib/solargraph/pin/base.rb', line 271

def proxy return_type
  result = dup
  result.return_type = return_type
  result.proxied = true
  result
end

#realize(api_map) ⇒ self

Parameters:

Returns:

  • (self) 


254
255
256
257
258
259
260
261
262
263
 
# File 'lib/solargraph/pin/base.rb', line 254

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

#reset_generated! ⇒ Object 



332
333
 
# File 'lib/solargraph/pin/base.rb', line 332

def reset_generated!
end

#resolve_generics(definitions, context_type) ⇒ self

Determine the concrete type for each of the generic type parameters used in this method based on the parameters passed into the its class and return a new method pin.

Parameters:

  • definitions (Pin::Namespace) —

    The module/class which uses generic types

  • context_type (ComplexType) —

    The receiver type

Returns:

  • (self) 


83
84
85
 
# File 'lib/solargraph/pin/base.rb', line 83

def resolve_generics definitions, context_type
  transform_types { |t| t.resolve_generics(definitions, context_type) if t }
end

#resolve_generics_from_context(generics_to_resolve, return_type_context = nil, resolved_generic_values: {}) ⇒ self

Parameters:

  • generics_to_resolve (Enumerable<String>)
  • return_type_context (ComplexType, nil) (defaults to: nil)
  • context (ComplexType)
  • resolved_generic_values (Hash{String => ComplexType}) (defaults to: {})

Returns:

  • (self) 


63
64
65
66
67
 
# File 'lib/solargraph/pin/base.rb', line 63

def resolve_generics_from_context(generics_to_resolve, return_type_context = nil, resolved_generic_values: {})
  proxy return_type.resolve_generics_from_context(generics_to_resolve,
                                                  return_type_context,
                                                  resolved_generic_values: resolved_generic_values)
end

#symbol_kind ⇒ Integer?

Returns:

  • (Integer, nil) 


110
111
112
 
# File 'lib/solargraph/pin/base.rb', line 110

def symbol_kind
  nil
end

#to_rbs ⇒ String?

Returns:

  • (String, nil) 


285
286
287
 
# File 'lib/solargraph/pin/base.rb', line 285

def to_rbs
  return_type.to_rbs
end

#to_s ⇒ Object 



114
115
116
 
# File 'lib/solargraph/pin/base.rb', line 114

def to_s
  desc
end

#transform_types {|| ... } ⇒ self

Yield Parameters:

Yield Returns:

Returns:

  • (self) 


72
73
74
 
# File 'lib/solargraph/pin/base.rb', line 72

def transform_types(&transform)
  proxy return_type.transform(&transform)
end

#try_merge!(pin) ⇒ Boolean

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.

Parameters:

  • pin (Pin::Base) —

    The pin to merge into this one

Returns:

  • (Boolean) —

    True if the pins were merged



230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/solargraph/pin/base.rb', line 230

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

#type_desc ⇒ String

Returns:

  • (String) 


290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/solargraph/pin/base.rb', line 290

def type_desc
  rbs = to_rbs
  # RBS doesn't have a way to represent a Class<x> type
  rbs = return_type.rooted_tags if return_type.name == 'Class'
  if path
    if rbs
      path + ' ' + rbs
    else
      path
    end
  else
    rbs
  end
end

#typify(api_map) ⇒ ComplexType

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.

Parameters:

Returns:



202
203
204
 
# File 'lib/solargraph/pin/base.rb', line 202

def typify api_map
  return_type.qualify(api_map, namespace)
end

#variable? ⇒ Boolean

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/solargraph/pin/base.rb', line 119

def variable?
  false
end