Class: Solargraph::Pin::Base
Overview
The base class for map pins.
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
-
#==(other) ⇒ Object
Pin equality is determined using the #nearly? method and also requiring both pins to have the same location.
-
#all_location_text ⇒ Object
-
#all_rooted? ⇒ Boolean
-
#assert_same(other, attr) ⇒ Object?
-
#assert_same_array_content(other, attr, &block) ⇒ void
-
#assert_same_count(other, attr) ⇒ ::Enumerable
-
#assert_same_macros(other) ⇒ void
-
#assert_source_provided ⇒ Object
-
#best_location ⇒ Location?
-
#choose(other, attr) ⇒ Object?
when choices are arbitrary, make sure the choice is consistent.
-
#choose_longer(other, attr) ⇒ undefined
-
#choose_node(other, attr) ⇒ undefined
-
#choose_pin_attr(other, attr) ⇒ Object
-
#choose_pin_attr_with_same_name(other, attr) ⇒ undefined
-
#combine_directives(other) ⇒ ::Array<YARD::Tags::Directive>?
-
#combine_name(other) ⇒ String
-
#combine_return_type(other) ⇒ ComplexType
-
#combine_with(other, attrs = {}) ⇒ self
-
#comments ⇒ String
-
#completion_item_kind ⇒ Integer
-
#deprecated? ⇒ Boolean
-
#desc ⇒ Object
-
#dodgy_return_type_source? ⇒ Boolean
-
#erase_generics(generics_to_erase) ⇒ self
-
#filename ⇒ String?
-
#identity ⇒ String
deprecated
Deprecated.
-
#infer(api_map) ⇒ ComplexType
deprecated
Deprecated.
Use #typify and/or #probe instead
-
#initialize(location: nil, type_location: nil, closure: nil, source: nil, name: '', comments: '', docstring: nil, directives: nil) ⇒ Base
constructor
-
#inner_desc ⇒ String
-
#inspect ⇒ String
-
#macros ⇒ ::Array<YARD::Tags::MacroDirective>
-
#maybe_directives? ⇒ Boolean
Perform a quick check to see if this pin possibly includes YARD directives.
-
#nearly?(other) ⇒ Boolean
True if the specified pin is a near match to this one.
-
#needs_consistent_name? ⇒ Boolean
-
#prefer_rbs_location(other, attr) ⇒ undefined
-
#presence_certain? ⇒ Boolean
-
#probe(api_map) ⇒ ComplexType
Infer the pin’s return type via static code analysis.
-
#probed? ⇒ Boolean
-
#proxied? ⇒ Boolean
-
#proxy(return_type) ⇒ self
Return a proxy for this pin with the specified return type.
-
#rbs_location? ⇒ Boolean
-
#realize(api_map) ⇒ self
-
#reset_generated! ⇒ void
-
#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.
-
#resolve_generics_from_context(generics_to_resolve, return_type_context = nil, resolved_generic_values: {}) ⇒ self
-
#symbol_kind ⇒ Integer?
-
#to_rbs ⇒ String?
-
#to_s ⇒ Object
-
#transform_types {|| ... } ⇒ self
-
#type_desc ⇒ String
-
#typify(api_map) ⇒ ComplexType
Get a fully qualified type from the pin’s return type.
-
#variable? ⇒ Boolean
Methods included from Logging
logger
#documentation, normalize_indentation, strip_html_comments
#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.
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 =
@source = source
@identity = nil
@docstring = docstring
@directives = directives
assert_source_provided
end
|
Instance Attribute Details
#code_object ⇒ 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>
425
426
427
428
|
# File 'lib/solargraph/pin/base.rb', line 425
def directives
unless @directives
@directives
end
|
#docstring ⇒ YARD::Docstring
419
420
421
422
|
# File 'lib/solargraph/pin/base.rb', line 419
def docstring
unless @docstring
@docstring ||= Solargraph::Source.parse_docstring('').to_docstring
end
|
17
18
19
|
# File 'lib/solargraph/pin/base.rb', line 17
def location
@location
end
|
#name ⇒ String
23
24
25
|
# File 'lib/solargraph/pin/base.rb', line 23
def name
@name
end
|
#path ⇒ String
26
27
28
|
# File 'lib/solargraph/pin/base.rb', line 26
def path
@path
end
|
414
415
416
|
# File 'lib/solargraph/pin/base.rb', line 414
def return_type
@return_type ||= ComplexType::UNDEFINED
end
|
#source ⇒ ::Symbol
29
30
31
|
# File 'lib/solargraph/pin/base.rb', line 29
def source
@source
end
|
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.
406
407
408
409
|
# File 'lib/solargraph/pin/base.rb', line 406
def == other
return false unless nearly? other
== other. && location == other.location
end
|
#all_location_text ⇒ Object
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
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?
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.
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)
arr2 = other.send(attr)
raise "Expected #{attr} on #{other} to be an Enumerable, got #{arr2.class}" unless arr2.is_a?(::Enumerable)
values1 = arr1.map(&block)
values2 = arr2.map(&block)
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
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)
arr1 = self.send(attr)
raise "Expected #{attr} on #{self} to be an Enumerable, got #{arr1.class}" unless arr1.is_a?(::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.
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_provided ⇒ Object
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_location ⇒ Location?
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
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
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
86
87
88
89
90
91
92
93
94
95
|
# File 'lib/solargraph/pin/base.rb', line 86
def choose_longer(other, attr)
val1 = send(attr)
val2 = other.send(attr)
return val1 if val1 == val2
return val2 if val1.nil?
val1.length > val2.length ? val1 : val2
end
|
#choose_node(other, attr) ⇒ 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)
val1 = send(attr)
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
[val1, val2].compact.min_by { _1.best_location.to_s }
end
|
#choose_pin_attr_with_same_name(other, attr) ⇒ 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)
val1 = send(attr)
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>?
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
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
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 }
all_items.delete_if { |item| item.rooted_tag == context.rooted_tag }
end
ComplexType.new(all_items)
end
end
|
#combine_with(other, attrs = {}) ⇒ 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..inspect}, self.comments = #{self.}" }
out = self.class.new(**new_attrs)
out.reset_generated!
out
end
|
312
313
314
|
# File 'lib/solargraph/pin/base.rb', line 312
def
@comments ||= ''
end
|
#completion_item_kind ⇒ Integer
#deprecated? ⇒ Boolean
449
450
451
|
# File 'lib/solargraph/pin/base.rb', line 449
def deprecated?
@deprecated ||= docstring.has_tag?('deprecated')
end
|
#desc ⇒ Object
551
552
553
|
# File 'lib/solargraph/pin/base.rb', line 551
def desc
"[#{inner_desc}]"
end
|
#dodgy_return_type_source? ⇒ Boolean
161
162
163
164
|
# File 'lib/solargraph/pin/base.rb', line 161
def dodgy_return_type_source?
location&.filename&.include?('core_ext/object/')
end
|
#erase_generics(generics_to_erase) ⇒ 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
|
#filename ⇒ String?
357
358
359
360
|
# File 'lib/solargraph/pin/base.rb', line 357
def filename
return nil if location.nil?
location.filename
end
|
#identity ⇒ String
519
520
521
|
# File 'lib/solargraph/pin/base.rb', line 519
def identity
@identity ||= "#{closure&.path}|#{name}|#{location}"
end
|
Deprecated.
Use #typify and/or #probe instead
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_desc ⇒ 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
|
#inspect ⇒ 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>
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.
443
444
445
446
|
# File 'lib/solargraph/pin/base.rb', line 443
def maybe_directives?
return !@directives.empty? if defined?(@directives) && @directives
@maybe_directives ||= .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.
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))) &&
( == other. ||
(((maybe_directives? == false && other.maybe_directives? == false) || compare_directives(directives, other.directives)) &&
compare_docstring_tags(docstring, other.docstring))
)
end
|
#needs_consistent_name? ⇒ Boolean
131
132
133
|
# File 'lib/solargraph/pin/base.rb', line 131
def needs_consistent_name?
true
end
|
#prefer_rbs_location(other, attr) ⇒ 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
31
32
33
|
# File 'lib/solargraph/pin/base.rb', line 31
def presence_certain?
true
end
|
Infer the pin’s return type via static code analysis.
469
470
471
|
# File 'lib/solargraph/pin/base.rb', line 469
def probe api_map
typify api_map
end
|
#probed? ⇒ Boolean
487
488
489
|
# File 'lib/solargraph/pin/base.rb', line 487
def probed?
@probed ||= false
end
|
#proxied? ⇒ 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.
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
208
209
210
|
# File 'lib/solargraph/pin/base.rb', line 208
def rbs_location?
type_location&.rbs?
end
|
#realize(api_map) ⇒ 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!
@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.
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
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_kind ⇒ Integer?
368
369
370
|
# File 'lib/solargraph/pin/base.rb', line 368
def symbol_kind
nil
end
|
#to_rbs ⇒ String?
524
525
526
|
# File 'lib/solargraph/pin/base.rb', line 524
def to_rbs
return_type.to_rbs
end
|
#to_s ⇒ Object
372
373
374
|
# File 'lib/solargraph/pin/base.rb', line 372
def to_s
desc
end
|
330
331
332
|
# File 'lib/solargraph/pin/base.rb', line 330
def transform_types(&transform)
proxy return_type.transform(&transform)
end
|
#type_desc ⇒ 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 = return_type.rooted_tags if return_type.name == 'Class'
if path
if rbs
path + ' ' + rbs
else
path
end
else
rbs
end
end
|
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.
461
462
463
|
# File 'lib/solargraph/pin/base.rb', line 461
def typify api_map
return_type.qualify(api_map, namespace)
end
|
#variable? ⇒ Boolean
377
378
379
|
# File 'lib/solargraph/pin/base.rb', line 377
def variable?
false
end
|