Class: Solargraph::Pin::Base

Inherits:
Object
  • Object
show all
Includes:
Logging, 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

Constant Summary

Constants included from Logging

Logging::DEFAULT_LOG_LEVEL, Logging::LOG_LEVELS

Instance Attribute Summary collapse

Attributes included from Common

#closure, #context

Instance Method Summary collapse

Methods included from Logging

logger

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: '', docstring: nil, directives: nil) ⇒ Base

Returns a new instance of Base.

Parameters:

  • location (Solargraph::Location, nil) (defaults to: nil)
  • type_location (Solargraph::Location, nil) (defaults to: nil)
  • closure (Solargraph::Pin::Closure, nil) (defaults to: nil)
  • name (String) (defaults to: '')
  • comments (String) (defaults to: '')
  • source (Symbol, nil) (defaults to: nil)
  • docstring (YARD::Docstring, nil) (defaults to: nil)
  • directives (::Array<YARD::Tags::Directive>, nil) (defaults to: nil)


43
44
45
46
47
48
49
50
51
52
53
54
# File 'lib/solargraph/pin/base.rb', line 43

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

Instance Attribute Details

#code_objectYARD::CodeObjects::Base (readonly)

Returns:

  • (YARD::CodeObjects::Base)


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

def code_object
  @code_object
end

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

Returns:

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


425
426
427
428
# File 'lib/solargraph/pin/base.rb', line 425

def directives
  parse_comments unless @directives
  @directives
end

#docstringYARD::Docstring

Returns:

  • (YARD::Docstring)


419
420
421
422
# File 'lib/solargraph/pin/base.rb', line 419

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

#locationSolargraph::Location (readonly)



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

def location
  @location
end

#nameString (readonly)

Returns:

  • (String)


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

def name
  @name
end

#pathString (readonly)

Returns:

  • (String)


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

def path
  @path
end

#return_typeComplexType

The pin’s return type.

Returns:



414
415
416
# File 'lib/solargraph/pin/base.rb', line 414

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

#source::Symbol

Returns:

  • (::Symbol)


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

def source
  @source
end

#type_locationSolargraph::Location (readonly)



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

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.

Parameters:

  • other (self)


406
407
408
409
# File 'lib/solargraph/pin/base.rb', line 406

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

#all_location_textObject



560
561
562
563
564
565
566
567
568
569
570
# File 'lib/solargraph/pin/base.rb', line 560

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)


345
346
347
# File 'lib/solargraph/pin/base.rb', line 345

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

#assert_same(other, attr) ⇒ Object?

Parameters:

  • other (self)
  • attr (::Symbol)

Returns:

  • (Object, nil)


265
266
267
268
269
270
271
272
273
# File 'lib/solargraph/pin/base.rb', line 265

def assert_same(other, attr)
  return false if other.nil?
  val1 = send(attr)
  val2 = other.send(attr)
  return val1 if val1 == val2
  Solargraph.assert_or_log("combine_with_#{attr}".to_sym,
                           "Inconsistent #{attr.inspect} values between \nself =#{inspect} and \nother=#{other.inspect}:\n\n self.#{attr} = #{val1.inspect}\nother.#{attr} = #{val2.inspect}")
  val1
end

#assert_same_array_content(other, attr, &block) ⇒ void

TODO:

strong typechecking should complain when there are no block-related tags

This method returns an undefined value.

Parameters:

  • other (self)
  • attr (::Symbol)


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

def assert_same_array_content(other, attr, &block)
  arr1 = send(attr)
  raise "Expected #{attr} on #{self} to be an Enumerable, got #{arr1.class}" unless arr1.is_a?(::Enumerable)
  # @type arr1 [::Enumerable]
  arr2 = other.send(attr)
  raise "Expected #{attr} on #{other} to be an Enumerable, got #{arr2.class}" unless arr2.is_a?(::Enumerable)
  # @type arr2 [::Enumerable]

  # @sg-ignore
  # @type [undefined]
  values1 = arr1.map(&block)
  # @type [undefined]
  values2 = arr2.map(&block)
  # @sg-ignore
  return arr1 if values1 == values2
  Solargraph.assert_or_log("combine_with_#{attr}".to_sym,
                           "Inconsistent #{attr.inspect} values between \nself =#{inspect} and \nother=#{other.inspect}:\n\n self values = #{values1}\nother values =#{attr} = #{values2}")
  arr1
end

#assert_same_count(other, attr) ⇒ ::Enumerable

Parameters:

  • other (self)
  • attr (::Symbol)

Returns:

  • (::Enumerable)


248
249
250
251
252
253
254
255
256
257
258
259
# File 'lib/solargraph/pin/base.rb', line 248

def assert_same_count(other, attr)
  # @type [::Enumerable]
  arr1 = self.send(attr)
  raise "Expected #{attr} on #{self} to be an Enumerable, got #{arr1.class}" unless arr1.is_a?(::Enumerable)
  # @type [::Enumerable]
  arr2 = other.send(attr)
  raise "Expected #{attr} on #{other} to be an Enumerable, got #{arr2.class}" unless arr2.is_a?(::Enumerable)
  return arr1 if arr1.count == arr2.count
  Solargraph.assert_or_log("combine_with_#{attr}".to_sym,
                           "Inconsistent #{attr.inspect} count value between \nself =#{inspect} and \nother=#{other.inspect}:\n\n self.#{attr} = #{arr1.inspect}\nother.#{attr} = #{arr2.inspect}")
  arr1
end

#assert_same_macros(other) ⇒ void

This method returns an undefined value.

Parameters:

  • other (self)


214
215
216
217
218
# File 'lib/solargraph/pin/base.rb', line 214

def assert_same_macros(other)
  return unless self.source == :yardoc && other.source == :yardoc
  assert_same_count(other, :macros)
  assert_same_array_content(other, :macros) { |macro| macro.tag.name }
end

#assert_source_providedObject



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

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

#best_locationLocation?

Returns:



382
383
384
# File 'lib/solargraph/pin/base.rb', line 382

def best_location
  location || type_location
end

#choose(other, attr) ⇒ Object?

when choices are arbitrary, make sure the choice is consistent

Parameters:

Returns:

  • (Object, nil)


172
173
174
175
176
177
178
179
180
# File 'lib/solargraph/pin/base.rb', line 172

def choose(other, attr)
  results = [self, other].map(&attr).compact
  # true and false are different classes and can't be sorted
  return true if results.any? { |r| r == true || r == false }
  results.min
rescue
  STDERR.puts("Problem handling #{attr} for \n#{self.inspect}\n and \n#{other.inspect}\n\n#{self.send(attr).inspect} vs #{other.send(attr).inspect}")
  raise
end

#choose_longer(other, attr) ⇒ undefined

@sg-ignore

Parameters:

  • other (self)
  • attr (::Symbol)

Returns:

  • (undefined)


86
87
88
89
90
91
92
93
94
95
# File 'lib/solargraph/pin/base.rb', line 86

def choose_longer(other, attr)
  # @type [undefined]
  val1 = send(attr)
  # @type [undefined]
  val2 = other.send(attr)
  return val1 if val1 == val2
  return val2 if val1.nil?
  # @sg-ignore
  val1.length > val2.length ? val1 : val2
end

#choose_node(other, attr) ⇒ undefined

@sg-ignore

Parameters:

Returns:

  • (undefined)


186
187
188
189
190
191
192
# File 'lib/solargraph/pin/base.rb', line 186

def choose_node(other, attr)
  if other.object_id < attr.object_id
    other.send(attr)
  else
    send(attr)
  end
end

#choose_pin_attr(other, attr) ⇒ Object



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

def choose_pin_attr(other, attr)
  # @type [Pin::Base, nil]
  val1 = send(attr)
  # @type [Pin::Base, nil]
  val2 = other.send(attr)
  if val1.class != val2.class
    Solargraph.assert_or_log("combine_with_#{attr}_class".to_sym,
                             "Inconsistent #{attr.inspect} class values between \nself =#{inspect} and \nother=#{other.inspect}:\n\n self.#{attr} = #{val1.inspect}\nother.#{attr} = #{val2.inspect}")
    return val1
  end
  # arbitrary way of choosing a pin
  [val1, val2].compact.min_by { _1.best_location.to_s }
end

#choose_pin_attr_with_same_name(other, attr) ⇒ undefined

@sg-ignore

Parameters:

  • other (self)
  • attr (::Symbol)

Returns:

  • (undefined)


279
280
281
282
283
284
285
286
287
288
289
290
291
# File 'lib/solargraph/pin/base.rb', line 279

def choose_pin_attr_with_same_name(other, attr)
  # @type [Pin::Base, nil]
  val1 = send(attr)
  # @type [Pin::Base, nil]
  val2 = other.send(attr)
  raise "Expected pin for #{attr} on\n#{self.inspect},\ngot #{val1.inspect}" unless val1.nil? || val1.is_a?(Pin::Base)
  raise "Expected pin for #{attr} on\n#{other.inspect},\ngot #{val2.inspect}" unless val2.nil? || val2.is_a?(Pin::Base)
  if val1&.name != val2&.name
    Solargraph.assert_or_log("combine_with_#{attr}_name".to_sym,
                             "Inconsistent #{attr.inspect} name values between \nself =#{inspect} and \nother=#{other.inspect}:\n\n self.#{attr} = #{val1.inspect}\nother.#{attr} = #{val2.inspect}")
  end
  choose_pin_attr(other, attr)
end

#combine_directives(other) ⇒ ::Array<YARD::Tags::Directive>?

Parameters:

  • other (self)

Returns:

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


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

def combine_directives(other)
  return self.directives if other.directives.empty?
  return other.directives if directives.empty?
  [directives + other.directives].uniq
end

#combine_name(other) ⇒ String

Parameters:

  • other (self)

Returns:

  • (String)


107
108
109
110
111
112
113
# File 'lib/solargraph/pin/base.rb', line 107

def combine_name(other)
  if needs_consistent_name? || other.needs_consistent_name?
    assert_same(other, :name)
  else
    choose(other, :name)
  end
end

#combine_return_type(other) ⇒ ComplexType

Parameters:

  • other (self)

Returns:



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# File 'lib/solargraph/pin/base.rb', line 142

def combine_return_type(other)
  if return_type.undefined?
    other.return_type
  elsif other.return_type.undefined?
    return_type
  elsif dodgy_return_type_source? && !other.dodgy_return_type_source?
    other.return_type
  elsif other.dodgy_return_type_source? && !dodgy_return_type_source?
    return_type
  else
    all_items = return_type.items + other.return_type.items
    if all_items.any? { |item| item.selfy? } && all_items.any? { |item| item.rooted_tag == context.rooted_tag }
      # assume this was a declaration that should have said 'self'
      all_items.delete_if { |item| item.rooted_tag == context.rooted_tag }
    end
    ComplexType.new(all_items)
  end
end

#combine_with(other, attrs = {}) ⇒ self

Parameters:

  • other (self)
  • attrs (Hash{Symbol => Object}) (defaults to: {})

Returns:

  • (self)


60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
# File 'lib/solargraph/pin/base.rb', line 60

def combine_with(other, attrs={})
  raise "tried to combine #{other.class} with #{self.class}" unless other.class == self.class
  type_location = choose(other, :type_location)
  location = choose(other, :location)
  combined_name = combine_name(other)
  new_attrs = {
    location: location,
    type_location: type_location,
    name: combined_name,
    closure: choose_pin_attr_with_same_name(other, :closure),
    comments: choose_longer(other, :comments),
    source: :combined,
    docstring: choose(other, :docstring),
    directives: combine_directives(other),
  }.merge(attrs)
  assert_same_macros(other)
  logger.debug { "Base#combine_with(path=#{path}) - other.comments=#{other.comments.inspect}, self.comments = #{self.comments}" }
  out = self.class.new(**new_attrs)
  out.reset_generated!
  out
end

#commentsString

Returns:

  • (String)


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

def comments
  @comments ||= ''
end

#completion_item_kindInteger

Returns:

  • (Integer)


363
364
365
# File 'lib/solargraph/pin/base.rb', line 363

def completion_item_kind
  LanguageServer::CompletionItemKinds::KEYWORD
end

#deprecated?Boolean

Returns:

  • (Boolean)


449
450
451
# File 'lib/solargraph/pin/base.rb', line 449

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

#descObject



551
552
553
# File 'lib/solargraph/pin/base.rb', line 551

def desc
  "[#{inner_desc}]"
end

#dodgy_return_type_source?Boolean

Returns:

  • (Boolean)


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

def dodgy_return_type_source?
  # uses a lot of 'Object' instead of 'self'
  location&.filename&.include?('core_ext/object/')
end

#erase_generics(generics_to_erase) ⇒ self

Parameters:

  • generics_to_erase (::Array<String>)

Returns:

  • (self)


351
352
353
354
# File 'lib/solargraph/pin/base.rb', line 351

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

#filenameString?

Returns:

  • (String, nil)


357
358
359
360
# File 'lib/solargraph/pin/base.rb', line 357

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

#identityString

Deprecated.

Returns:

  • (String)


519
520
521
# File 'lib/solargraph/pin/base.rb', line 519

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

#infer(api_map) ⇒ ComplexType

Deprecated.

Use #typify and/or #probe instead

Parameters:

Returns:



476
477
478
479
480
481
# File 'lib/solargraph/pin/base.rb', line 476

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_descString

Returns:

  • (String)


545
546
547
548
549
# File 'lib/solargraph/pin/base.rb', line 545

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

#inspectString

Returns:

  • (String)


556
557
558
# File 'lib/solargraph/pin/base.rb', line 556

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

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

Returns:

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


431
432
433
# File 'lib/solargraph/pin/base.rb', line 431

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)


443
444
445
446
# File 'lib/solargraph/pin/base.rb', line 443

def maybe_directives?
  return !@directives.empty? if defined?(@directives) && @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)


392
393
394
395
396
397
398
399
400
# File 'lib/solargraph/pin/base.rb', line 392

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

#needs_consistent_name?Boolean

Returns:

  • (Boolean)


131
132
133
# File 'lib/solargraph/pin/base.rb', line 131

def needs_consistent_name?
  true
end

#prefer_rbs_location(other, attr) ⇒ undefined

@sg-ignore

Parameters:

  • other (self)
  • attr (::Symbol)

Returns:

  • (undefined)


198
199
200
201
202
203
204
205
206
# File 'lib/solargraph/pin/base.rb', line 198

def prefer_rbs_location(other, attr)
  if rbs_location? && !other.rbs_location?
    self.send(attr)
  elsif !rbs_location? && other.rbs_location?
    other.send(attr)
  else
    choose(other, attr)
  end
end

#presence_certain?Boolean

Returns:

  • (Boolean)


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

def presence_certain?
  true
end

#probe(api_map) ⇒ ComplexType

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

Parameters:

Returns:



469
470
471
# File 'lib/solargraph/pin/base.rb', line 469

def probe api_map
  typify api_map
end

#probed?Boolean

Returns:

  • (Boolean)


487
488
489
# File 'lib/solargraph/pin/base.rb', line 487

def probed?
  @probed ||= false
end

#proxied?Boolean

Returns:

  • (Boolean)


483
484
485
# File 'lib/solargraph/pin/base.rb', line 483

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)


510
511
512
513
514
515
# File 'lib/solargraph/pin/base.rb', line 510

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

#rbs_location?Boolean

Returns:

  • (Boolean)


208
209
210
# File 'lib/solargraph/pin/base.rb', line 208

def rbs_location?
  type_location&.rbs?
end

#realize(api_map) ⇒ self

Parameters:

Returns:

  • (self)


493
494
495
496
497
498
499
500
501
502
# File 'lib/solargraph/pin/base.rb', line 493

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!void

This method returns an undefined value.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
# File 'lib/solargraph/pin/base.rb', line 116

def reset_generated!
  # @return_type doesn't go here as subclasses tend to assign it
  # themselves in constructors, and they will deal with setting
  # it in any methods that call this
  #
  # @docstring also doesn't go here, as there is code which
  # directly manipulates docstring without editing comments
  # (e.g., Api::Map::Store#index processes overrides that way
  #
  # Same with @directives, @macros, @maybe_directives, which
  # regenerate docstring
  @deprecated = nil
  reset_conversions
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)


341
342
343
# File 'lib/solargraph/pin/base.rb', line 341

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)


321
322
323
324
325
# File 'lib/solargraph/pin/base.rb', line 321

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_kindInteger?

Returns:

  • (Integer, nil)


368
369
370
# File 'lib/solargraph/pin/base.rb', line 368

def symbol_kind
  nil
end

#to_rbsString?

Returns:

  • (String, nil)


524
525
526
# File 'lib/solargraph/pin/base.rb', line 524

def to_rbs
  return_type.to_rbs
end

#to_sObject



372
373
374
# File 'lib/solargraph/pin/base.rb', line 372

def to_s
  desc
end

#transform_types {|| ... } ⇒ self

Yield Parameters:

Yield Returns:

Returns:

  • (self)


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

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

#type_descString

Returns:

  • (String)


529
530
531
532
533
534
535
536
537
538
539
540
541
542
# File 'lib/solargraph/pin/base.rb', line 529

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:



461
462
463
# File 'lib/solargraph/pin/base.rb', line 461

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

#variable?Boolean

Returns:

  • (Boolean)


377
378
379
# File 'lib/solargraph/pin/base.rb', line 377

def variable?
  false
end