Class: Solargraph::ApiMap

Inherits:
Object
  • Object
show all
Defined in:
lib/solargraph/api_map.rb,
lib/solargraph/api_map/cache.rb,
lib/solargraph/api_map/store.rb,
lib/solargraph/api_map/source_to_yard.rb

Overview

An aggregate provider for information about workspaces, sources, gems, and the Ruby core.

Defined Under Namespace

Modules: SourceToYard Classes: Cache, Store

Constant Summary collapse

@@core_map = 
RbsMap::CoreMap.new

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(pins: []) ⇒ ApiMap

Returns a new instance of ApiMap.

Parameters:



25
26
27
28
29
30
 
# File 'lib/solargraph/api_map.rb', line 25

def initialize pins: []
  @source_map_hash = {}
  @cache = Cache.new
  @method_alias_stack = []
  index pins
end

Instance Attribute Details

#missing_docs ⇒ Array<String> (readonly)

Returns:

  • (Array<String>) 


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

def missing_docs
  @missing_docs
end

#unresolved_requires ⇒ Array<String> (readonly)

Returns:

  • (Array<String>) 


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

def unresolved_requires
  @unresolved_requires
end

Class Method Details

.load(directory) ⇒ ApiMap

Create an ApiMap with a workspace in the specified directory.

Parameters:

  • directory (String)

Returns:



125
126
127
128
129
130
131
132
133
 
# File 'lib/solargraph/api_map.rb', line 125

def self.load directory
  api_map = new
  workspace = Solargraph::Workspace.new(directory)
  # api_map.catalog Bench.new(workspace: workspace)
  library = Library.new(workspace)
  library.map!
  api_map.catalog library.bench
  api_map
end

.load_with_cache(directory) ⇒ ApiMap

Create an ApiMap with a workspace in the specified directory and cache any missing gems.

Parameters:

  • directory (String)

Returns:



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/solargraph/api_map.rb', line 140

def self.load_with_cache directory
  api_map = load(directory)
  return api_map if api_map.uncached_gemspecs.empty?

  api_map.uncached_gemspecs.each do |gemspec|
    Solargraph.logger.info "Caching #{gemspec.name} #{gemspec.version}..."
    pins = GemPins.build(gemspec)
    Solargraph::Cache.save('gems', "#{gemspec.name}-#{gemspec.version}.ser", pins)
  end
  load(directory)
end

Instance Method Details

#bundled?(filename) ⇒ Boolean

True if the specified file was included in a bundle, i.e., it’s either included in a workspace or open in a library.

Parameters:

  • filename (String)

Returns:

  • (Boolean) 


495
496
497
 
# File 'lib/solargraph/api_map.rb', line 495

def bundled? filename
  source_map_hash.keys.include?(filename)
end

#catalog(bench) ⇒ self

Catalog a bench.

Parameters:

Returns:

  • (self) 


58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/solargraph/api_map.rb', line 58

def catalog bench
  implicit.clear
  @cache.clear
  @source_map_hash = bench.source_maps.map { |s| [s.filename, s] }.to_h
  pins = bench.source_maps.map(&:pins).flatten
  source_map_hash.each_value do |map|
    implicit.merge map.environ
  end
  unresolved_requires = (bench.external_requires + implicit.requires + bench.workspace.config.required).uniq
  @doc_map = DocMap.new(unresolved_requires, []) # @todo Implement gem preferences
  @store = Store.new(@@core_map.pins + @doc_map.pins + implicit.pins + pins)
  @unresolved_requires = @doc_map.unresolved_requires
  @missing_docs = [] # @todo Implement missing docs
  @rebindable_method_names = nil
  store.block_pins.each { |blk| blk.rebind(self) }
  self
end

#clip(cursor) ⇒ SourceMap::Clip

Parameters:

Returns:

Raises:



459
460
461
462
463
464
465
466
 
# File 'lib/solargraph/api_map.rb', line 459

def clip cursor
  raise FileNotFoundError, "ApiMap did not catalog #{cursor.filename}" unless source_map_hash.key?(cursor.filename)

  # @todo Clip caches are disabled pending resolution of a stale cache bug
  # cache.get_clip(cursor) ||
  #   SourceMap::Clip.new(self, cursor).tap { |clip| cache.set_clip(cursor, clip) }
  SourceMap::Clip.new(self, cursor)
end

#clip_at(filename, position) ⇒ SourceMap::Clip

Get a clip by filename and position.

Parameters:

  • filename (String)
  • position (Position, Array(Integer, Integer))

Returns:



116
117
118
119
 
# File 'lib/solargraph/api_map.rb', line 116

def clip_at filename, position
  position = Position.normalize(position)
  clip(cursor_at(filename, position))
end

#core_pins ⇒ Array<Pin::Base>

Returns:



82
83
84
 
# File 'lib/solargraph/api_map.rb', line 82

def core_pins
  @@core_map.pins
end

#cursor_at(filename, position) ⇒ Source::Cursor

Parameters:

  • filename (String)
  • position (Position, Array(Integer, Integer))

Returns:

Raises:



105
106
107
108
109
 
# File 'lib/solargraph/api_map.rb', line 105

def cursor_at filename, position
  position = Position.normalize(position)
  raise FileNotFoundError, "File not found: #{filename}" unless source_map_hash.key?(filename)
  source_map_hash[filename].cursor_at(position)
end

#document(path) ⇒ Enumerable<Pin::Base>

TODO:

This method is likely superfluous. Calling get_path_pins directly should be sufficient.

Get YARD documentation for the specified path.

Examples:

api_map.document('String#split')

Parameters:

  • path (String) —

    The path to find

Returns:



434
435
436
 
# File 'lib/solargraph/api_map.rb', line 434

def document path
  get_path_pins(path)
end

#document_symbols(filename) ⇒ Array<Pin::Symbol>

Get an array of document symbols from a file.

Parameters:

  • filename (String)

Returns:



472
473
474
475
 
# File 'lib/solargraph/api_map.rb', line 472

def document_symbols filename
  return [] unless source_map_hash.key?(filename) # @todo Raise error?
  resolve_method_aliases source_map_hash[filename].document_symbols
end

#get_class_variable_pins(namespace) ⇒ Enumerable<Solargraph::Pin::ClassVariable>

Get an array of class variable pins for a namespace.

Parameters:

  • namespace (String) —

    A fully qualified namespace

Returns:



289
290
291
 
# File 'lib/solargraph/api_map.rb', line 289

def get_class_variable_pins(namespace)
  prefer_non_nil_variables(store.get_class_variables(namespace))
end

#get_complex_type_methods(complex_type, context = '', internal = false) ⇒ Array<Solargraph::Pin::Base>

Get an array of method pins for a complex type.

The type’s namespace and the context should be fully qualified. If the context matches the namespace type or is a subclass of the type, protected methods are included in the results. If protected methods are included and internal is true, private methods are also included.

Examples:

api_map = Solargraph::ApiMap.new
type = Solargraph::ComplexType.parse('String')
api_map.get_complex_type_methods(type)

Parameters:

  • complex_type (Solargraph::ComplexType) —

    The complex type of the namespace

  • context (String) (defaults to: '') —

    The context from which the type is referenced

  • internal (Boolean) (defaults to: false) —

    True to include private methods

Returns:



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/solargraph/api_map.rb', line 351

def get_complex_type_methods complex_type, context = '', internal = false
  # This method does not qualify the complex type's namespace because
  # it can cause conflicts between similar names, e.g., `Foo` vs.
  # `Other::Foo`. It still takes a context argument to determine whether
  # protected and private methods are visible.
  return [] if complex_type.undefined? || complex_type.void?
  result = Set.new
  complex_type.each do |type|
    if type.duck_type?
      result.add Pin::DuckMethod.new(name: type.to_s[1..-1])
      result.merge get_methods('Object')
    else
      unless type.nil? || type.name == 'void'
        visibility = [:public]
        if type.namespace == context || super_and_sub?(type.namespace, context)
          visibility.push :protected
          visibility.push :private if internal
        end
        result.merge get_methods(type.tag, scope: type.scope, visibility: visibility)
      end
    end
  end
  result.to_a
end

#get_constants(namespace, *contexts) ⇒ Array<Solargraph::Pin::Base>

Get suggestions for constants in the specified namespace. The result may contain both constant and namespace pins.

Parameters:

  • namespace (String) —

    The namespace

  • contexts (Array<String>) —

    The contexts

Returns:



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'lib/solargraph/api_map.rb', line 197

def get_constants namespace, *contexts
  namespace ||= ''
  contexts.push '' if contexts.empty?
  cached = cache.get_constants(namespace, contexts)
  return cached.clone unless cached.nil?
  skip = Set.new
  result = []
  contexts.each do |context|
    fqns = qualify(namespace, context)
    visibility = [:public]
    visibility.push :private if fqns == context
    result.concat inner_get_constants(fqns, visibility, skip)
  end
  cache.set_constants(namespace, contexts, result)
  result
end

#get_global_variable_pins ⇒ Enumerable<Solargraph::Pin::GlobalVariable>

Returns:



299
300
301
 
# File 'lib/solargraph/api_map.rb', line 299

def get_global_variable_pins
  store.pins_by_class(Pin::GlobalVariable)
end

#get_instance_variable_pins(namespace, scope = :instance) ⇒ Array<Solargraph::Pin::InstanceVariable>

Get an array of instance variable pins defined in specified namespace and scope.

Parameters:

  • namespace (String) —

    A fully qualified namespace

  • scope (Symbol) (defaults to: :instance) —

    :instance or :class

Returns:



272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/solargraph/api_map.rb', line 272

def get_instance_variable_pins(namespace, scope = :instance)
  result = []
  used = [namespace]
  result.concat store.get_instance_variables(namespace, scope)
  sc = qualify_lower(store.get_superclass(namespace), namespace)
  until sc.nil? || used.include?(sc)
    used.push sc
    result.concat store.get_instance_variables(sc, scope)
    sc = qualify_lower(store.get_superclass(sc), sc)
  end
  result
end

#get_method_stack(rooted_tag, name, scope: :instance) ⇒ Array<Solargraph::Pin::Method>

Get a stack of method pins for a method name in a potentially parameterized namespace. The order of the pins corresponds to the ancestry chain, with highest precedence first.

Examples:

api_map.get_method_stack('Subclass', 'method_name')
  #=> [ <Subclass#method_name pin>, <Superclass#method_name pin> ]

Parameters:

  • rooted_tag (String) —

    Parameterized namespace, fully qualified

  • name (String) —

    Method name to look up

  • scope (Symbol) (defaults to: :instance) —

    :instance or :class

Returns:



388
389
390
 
# File 'lib/solargraph/api_map.rb', line 388

def get_method_stack rooted_tag, name, scope: :instance
  get_methods(rooted_tag, scope: scope, visibility: [:private, :protected, :public]).select { |p| p.name == name }
end

#get_methods(rooted_tag, scope: :instance, visibility: [:public], deep: true) ⇒ Array<Solargraph::Pin::Method>

Get an array of methods available in a particular context.

Parameters:

  • rooted_tag (String) —

    The fully qualified namespace to search for methods

  • scope (Symbol) (defaults to: :instance) —

    :class or :instance

  • visibility (Array<Symbol>) (defaults to: [:public]) —

    :public, :protected, and/or :private

  • deep (Boolean) (defaults to: true) —

    True to include superclasses, mixins, etc.

Returns:



310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/solargraph/api_map.rb', line 310

def get_methods rooted_tag, scope: :instance, visibility: [:public], deep: true
  cached = cache.get_methods(rooted_tag, scope, visibility, deep)
  return cached.clone unless cached.nil?
  result = []
  skip = Set.new
  if rooted_tag == ''
    # @todo Implement domains
    implicit.domains.each do |domain|
      type = ComplexType.try_parse(domain)
      next if type.undefined?
      result.concat inner_get_methods(type.name, type.scope, visibility, deep, skip)
    end
    result.concat inner_get_methods(rooted_tag, :class, visibility, deep, skip)
    result.concat inner_get_methods(rooted_tag, :instance, visibility, deep, skip)
    result.concat inner_get_methods('Kernel', :instance, visibility, deep, skip)
  else
    result.concat inner_get_methods(rooted_tag, scope, visibility, deep, skip)
    result.concat inner_get_methods('Kernel', :instance, [:public], deep, skip) if visibility.include?(:private)
    result.concat inner_get_methods('Module', scope, visibility, deep, skip)
  end
  resolved = resolve_method_aliases(result, visibility)
  cache.set_methods(rooted_tag, scope, visibility, deep, resolved)
  resolved
end

#get_namespace_pins(namespace, context) ⇒ Array<Pin::Namespace>

Parameters:

  • namespace (String)
  • context (String)

Returns:



217
218
219
 
# File 'lib/solargraph/api_map.rb', line 217

def get_namespace_pins namespace, context
  store.fqns_pins(qualify(namespace, context))
end

#get_path_pins(path) ⇒ Enumerable<Pin::Base>

Get an array of pins that match the specified path.

Parameters:

  • path (String)

Returns:



407
408
409
 
# File 'lib/solargraph/api_map.rb', line 407

def get_path_pins path
  get_path_suggestions(path)
end

#get_path_suggestions(path) ⇒ Enumerable<Solargraph::Pin::Base>

Deprecated.

Use #get_path_pins instead.

Get an array of all suggestions that match the specified path.

Parameters:

  • path (String) —

    The path to find

Returns:



398
399
400
401
 
# File 'lib/solargraph/api_map.rb', line 398

def get_path_suggestions path
  return [] if path.nil?
  resolve_method_aliases store.get_path_pins(path)
end

#get_symbols ⇒ Enumerable<Solargraph::Pin::Base>

Returns:



294
295
296
 
# File 'lib/solargraph/api_map.rb', line 294

def get_symbols
  store.get_symbols
end

#implicit ⇒ Environ

Returns:



98
99
100
 
# File 'lib/solargraph/api_map.rb', line 98

def implicit
  @implicit ||= Environ.new
end

#index(pins) ⇒ self

Parameters:

Returns:

  • (self) 


34
35
36
37
38
39
40
41
42
 
# File 'lib/solargraph/api_map.rb', line 34

def index pins
  # @todo This implementation is incomplete. It should probably create a
  #   Bench.
  @source_map_hash = {}
  implicit.clear
  cache.clear
  @store = Store.new(@@core_map.pins + pins)
  self
end

#keyword_pins ⇒ Enumerable<Solargraph::Pin::Keyword>

An array of pins based on Ruby keywords (‘if`, `end`, etc.).

Returns:



171
172
173
 
# File 'lib/solargraph/api_map.rb', line 171

def keyword_pins
  store.pins_by_class(Pin::Keyword)
end

#locate_pins(location) ⇒ Array<Solargraph::Pin::Base>

Parameters:

Returns:



451
452
453
454
 
# File 'lib/solargraph/api_map.rb', line 451

def locate_pins location
  return [] if location.nil? || !source_map_hash.key?(location.filename)
  resolve_method_aliases source_map_hash[location.filename].locate_pins(location)
end

#map(source) ⇒ self

Map a single source.

Parameters:

Returns:

  • (self) 


48
49
50
51
52
 
# File 'lib/solargraph/api_map.rb', line 48

def map source
  map = Solargraph::SourceMap.map(source)
  catalog Bench.new(source_maps: [map])
  self
end

#named_macro(name) ⇒ YARD::Tags::MacroDirective?

Parameters:

  • name (String)

Returns:

  • (YARD::Tags::MacroDirective, nil) 


88
89
90
 
# File 'lib/solargraph/api_map.rb', line 88

def named_macro name
  store.named_macros[name]
end

#namespace_exists?(name, context = '') ⇒ Boolean

True if the namespace exists.

Parameters:

  • name (String) —

    The namespace to match

  • context (String) (defaults to: '') —

    The context to search

Returns:

  • (Boolean) 


187
188
189
 
# File 'lib/solargraph/api_map.rb', line 187

def namespace_exists? name, context = ''
  !qualify(name, context).nil?
end

#namespaces ⇒ Set<String>

An array of namespace names defined in the ApiMap.

Returns:

  • (Set<String>) 


178
179
180
 
# File 'lib/solargraph/api_map.rb', line 178

def namespaces
  store.namespaces
end

#pins ⇒ Array<Solargraph::Pin::Base>

Returns:



153
154
155
 
# File 'lib/solargraph/api_map.rb', line 153

def pins
  store.pins
end

#qualify(tag, context_tag = '') ⇒ String?

Determine fully qualified tag for a given tag used inside the definition of another tag (“context”). This method will start the search in the specified context until it finds a match for the tag.

Does not recurse into qualifying the type parameters, but returns any which were passed in unchanged.

Parameters:

  • tag (String, nil) —

    The namespace to match, complete with generic parameters set to appropriate values if available

  • context_tag (String) (defaults to: '') —

    The context in which the tag was referenced; start from here to resolve the name

Returns:

  • (String, nil) —

    fully qualified tag



235
236
237
238
239
240
241
242
 
# File 'lib/solargraph/api_map.rb', line 235

def qualify tag, context_tag = ''
  return tag if ['self', nil].include?(tag)
  context_type = ComplexType.parse(context_tag)
  type = ComplexType.parse(tag)
  fqns = qualify_namespace(type.rooted_namespace, context_type.rooted_namespace)
  return nil if fqns.nil?
  fqns + type.substring
end

#qualify_namespace(namespace, context_namespace = '') ⇒ String?

Determine fully qualified namespace for a given namespace used inside the definition of another tag (“context”). This method will start the search in the specified context until it finds a match for the namespace.

Parameters:

  • namespace (String, nil) —

    The namespace to match

  • context_namespace (String) (defaults to: '') —

    The context namespace in which the tag was referenced; start from here to resolve the name

Returns:

  • (String, nil) —

    fully qualified namespace



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

def qualify_namespace(namespace, context_namespace = '')
  cached = cache.get_qualified_namespace(namespace, context_namespace)
  return cached.clone unless cached.nil?
  result = if namespace.start_with?('::')
             inner_qualify(namespace[2..-1], '', Set.new)
           else
             inner_qualify(namespace, context_namespace, Set.new)
           end
  cache.set_qualified_namespace(namespace, context_namespace, result)
  result
end

#query_symbols(query) ⇒ Array<Pin::Base>

Get an array of all symbols in the workspace that match the query.

Parameters:

  • query (String)

Returns:



442
443
444
445
446
447
 
# File 'lib/solargraph/api_map.rb', line 442

def query_symbols query
  Pin::Search.new(
    source_map_hash.values.flat_map(&:document_symbols),
    query
  ).results
end

#rebindable_method_names ⇒ Set<String>

Returns:

  • (Set<String>) 


158
159
160
161
162
163
164
165
166
 
# File 'lib/solargraph/api_map.rb', line 158

def rebindable_method_names
  @rebindable_method_names ||= begin
    result = ['instance_eval', 'instance_exec', 'class_eval', 'class_exec', 'module_eval', 'module_exec', 'define_method'].to_set
    source_maps.each do |map|
      result.merge map.rebindable_method_names
    end
    result
  end
end

#required ⇒ Set<String>

Returns:

  • (Set<String>) 


93
94
95
 
# File 'lib/solargraph/api_map.rb', line 93

def required
  @required ||= Set.new
end

#search(query) ⇒ Array<String>

Get a list of documented paths that match the query.

Examples:

api_map.query('str') # Results will include `String` and `Struct`

Parameters:

  • query (String) —

    The text to match

Returns:

  • (Array<String>) 


418
419
420
421
422
 
# File 'lib/solargraph/api_map.rb', line 418

def search query
  pins.map(&:path)
      .compact
      .select { |path| path.downcase.include?(query.downcase) }
end

#source_map(filename) ⇒ SourceMap

Get a source map by filename.

Parameters:

  • filename (String)

Returns:

Raises:



486
487
488
489
 
# File 'lib/solargraph/api_map.rb', line 486

def source_map filename
  raise FileNotFoundError, "Source map for `#{filename}` not found" unless source_map_hash.key?(filename)
  source_map_hash[filename]
end

#source_maps ⇒ Array<SourceMap>

Returns:



478
479
480
 
# File 'lib/solargraph/api_map.rb', line 478

def source_maps
  source_map_hash.values
end

#super_and_sub?(sup, sub) ⇒ Boolean

Check if a class is a superclass of another class.

Parameters:

  • sup (String) —

    The superclass

  • sub (String) —

    The subclass

Returns:

  • (Boolean) 


504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/solargraph/api_map.rb', line 504

def super_and_sub?(sup, sub)
  fqsup = qualify(sup)
  cls = qualify(sub)
  tested = []
  until fqsup.nil? || cls.nil? || tested.include?(cls)
    return true if cls == fqsup
    tested.push cls
    cls = qualify_superclass(cls)
  end
  false
end

#type_include?(host_ns, module_ns) ⇒ Boolean

Check if the host class includes the specified module, ignoring type parameters used.

Parameters:

  • host_ns (String) —

    The class namesapce (no type parameters)

  • module_ns (String) —

    The module namespace (no type parameters)

Returns:

  • (Boolean) 


523
524
525
 
# File 'lib/solargraph/api_map.rb', line 523

def type_include?(host_ns, module_ns)
  store.get_includes(host_ns).map { |inc_tag| ComplexType.parse(inc_tag).name }.include?(module_ns)
end

#uncached_gemspecs ⇒ ::Array<Gem::Specification>

Returns:

  • (::Array<Gem::Specification>) 


77
78
79
 
# File 'lib/solargraph/api_map.rb', line 77

def uncached_gemspecs
  @doc_map&.uncached_gemspecs || []
end