Class: Solargraph::ApiMap

Inherits:
Object
  • Object
show all
Includes:
SourceToYard
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,
lib/solargraph/api_map/bundler_methods.rb

Overview

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

Defined Under Namespace

Modules: BundlerMethods, SourceToYard Classes: Cache, Store

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from SourceToYard

#code_object_at, #code_object_paths, #rake_yard

Constructor Details

#initialize(pins: []) ⇒ ApiMap

Returns a new instance of ApiMap.

Parameters:



28
29
30
31
32
33
 
# File 'lib/solargraph/api_map.rb', line 28

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

Instance Attribute Details

#missing_docs ⇒ Array<String> (readonly)

Returns:



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

def missing_docs
  @missing_docs
end

#unresolved_requires ⇒ Array<String> (readonly)

Returns:



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

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:



118
119
120
121
122
123
124
125
126
 
# File 'lib/solargraph/api_map.rb', line 118

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

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) 


438
439
440
 
# File 'lib/solargraph/api_map.rb', line 438

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

#catalog(bench) ⇒ Object

Catalog a bench.

Parameters:



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

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
  external_requires = bench.external_requires
  source_map_hash.each_value do |map|
    implicit.merge map.environ
  end
  external_requires.merge implicit.requires
  external_requires.merge bench.workspace.config.required
  yard_map.change(external_requires, bench.workspace.directory, bench.workspace.source_gems)
  @store = Store.new(yard_map.pins + implicit.pins + pins)
  @unresolved_requires = yard_map.unresolved_requires
  @missing_docs = yard_map.missing_docs
  @rebindable_method_names = nil
  store.block_pins.each { |blk| blk.rebind(self) }
  self
end

#clip(cursor) ⇒ SourceMap::Clip

Parameters:

Returns:

Raises:



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

def clip cursor
  raise FileNotFoundError, "ApiMap did not catalog #{cursor.filename}" unless source_map_hash.key?(cursor.filename)
  SourceMap::Clip.new(self, cursor)
end

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

Get a clip by filename and position.

Parameters:

Returns:



109
110
111
112
 
# File 'lib/solargraph/api_map.rb', line 109

def clip_at filename, position
  position = Position.normalize(position)
  SourceMap::Clip.new(self, cursor_at(filename, position))
end

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

Parameters:

Returns:

Raises:



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

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) ⇒ Array<YARD::CodeObjects::Base>

Get YARD documentation for the specified path.

Examples:

api_map.document('String#split')

Parameters:

  • path (String) —

    The path to find

Returns:

  • (Array<YARD::CodeObjects::Base>) 


378
379
380
381
382
383
 
# File 'lib/solargraph/api_map.rb', line 378

def document path
  rake_yard(store)
  docs = []
  docs.push code_object_at(path) unless code_object_at(path).nil?
  docs
end

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

Get an array of document symbols from a file.

Parameters:

  • filename (String)

Returns:



415
416
417
418
 
# File 'lib/solargraph/api_map.rb', line 415

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) ⇒ Array<Solargraph::Pin::ClassVariable>

Get an array of class variable pins for a namespace.

Parameters:

  • namespace (String) —

    A fully qualified namespace

Returns:



231
232
233
 
# File 'lib/solargraph/api_map.rb', line 231

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:



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/solargraph/api_map.rb', line 292

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.namespace, 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:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
 
# File 'lib/solargraph/api_map.rb', line 172

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 ⇒ Array<Solargraph::Pin::GlobalVariable>

Returns:



241
242
243
 
# File 'lib/solargraph/api_map.rb', line 241

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:



214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/solargraph/api_map.rb', line 214

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(fqns, name, scope: :instance) ⇒ Array<Solargraph::Pin::Method>

Get a stack of method pins for a method name in a 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:

  • fqns (String)
  • name (String)
  • scope (Symbol) (defaults to: :instance) —

    :instance or :class

Returns:



329
330
331
 
# File 'lib/solargraph/api_map.rb', line 329

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

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

Get an array of methods available in a particular context.

Parameters:

  • fqns (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:



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/solargraph/api_map.rb', line 252

def get_methods fqns, scope: :instance, visibility: [:public], deep: true
  cached = cache.get_methods(fqns, scope, visibility, deep)
  return cached.clone unless cached.nil?
  result = []
  skip = Set.new
  if fqns == ''
    # @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(fqns, :class, visibility, deep, skip)
    result.concat inner_get_methods(fqns, :instance, visibility, deep, skip)
    result.concat inner_get_methods('Kernel', :instance, visibility, deep, skip)
  else
    result.concat inner_get_methods(fqns, scope, visibility, deep, skip)
    result.concat inner_get_methods('Kernel', :instance, [:public], deep, skip) if visibility.include?(:private)
  end
  resolved = resolve_method_aliases(result, visibility)
  cache.set_methods(fqns, scope, visibility, deep, resolved)
  resolved
end

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

Get an array of pins that match the specified path.

Parameters:

  • path (String)

Returns:



348
349
350
 
# File 'lib/solargraph/api_map.rb', line 348

def get_path_pins path
  get_path_suggestions(path)
end

#get_path_suggestions(path) ⇒ Array<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:



339
340
341
342
 
# File 'lib/solargraph/api_map.rb', line 339

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

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

Returns:



236
237
238
 
# File 'lib/solargraph/api_map.rb', line 236

def get_symbols
  store.get_symbols
end

#implicit ⇒ Environ

Returns:



91
92
93
 
# File 'lib/solargraph/api_map.rb', line 91

def implicit
  @implicit ||= Environ.new
end

#index(pins) ⇒ self

Parameters:

Returns:

  • (self) 


37
38
39
40
41
42
43
44
45
 
# File 'lib/solargraph/api_map.rb', line 37

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

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

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

Returns:



146
147
148
 
# File 'lib/solargraph/api_map.rb', line 146

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

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

Parameters:

Returns:



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

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) 


51
52
53
54
55
 
# File 'lib/solargraph/api_map.rb', line 51

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) 


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

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) 


162
163
164
 
# File 'lib/solargraph/api_map.rb', line 162

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>) 


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

def namespaces
  store.namespaces
end

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

Returns:



129
130
131
 
# File 'lib/solargraph/api_map.rb', line 129

def pins
  store.pins
end

#qualify(namespace, context = '') ⇒ String

Get a fully qualified namespace name. This method will start the search in the specified context until it finds a match for the name.

Parameters:

  • namespace (String, nil) —

    The namespace to match

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

    The context to search

Returns:

  • (String) 


195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/solargraph/api_map.rb', line 195

def qualify namespace, context = ''
  return namespace if ['self', nil].include?(namespace)
  cached = cache.get_qualified_namespace(namespace, context)
  return cached.clone unless cached.nil?
  result = if namespace.start_with?('::')
             inner_qualify(namespace[2..-1], '', Set.new)
           else
             inner_qualify(namespace, context, Set.new)
           end
  cache.set_qualified_namespace(namespace, context, 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:



389
390
391
392
393
394
 
# File 'lib/solargraph/api_map.rb', line 389

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

#rebindable_method_names ⇒ Object 



133
134
135
136
137
138
139
140
141
 
# File 'lib/solargraph/api_map.rb', line 133

def rebindable_method_names
  @rebindable_method_names ||= begin
    result = yard_map.rebindable_method_names
    source_maps.each do |map|
      result.merge map.rebindable_method_names
    end
    result
  end
end

#required ⇒ Object 



86
87
88
 
# File 'lib/solargraph/api_map.rb', line 86

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:



359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/solargraph/api_map.rb', line 359

def search query
  rake_yard(store)
  found = []
  code_object_paths.each do |k|
    if (found.empty? || (query.include?('.') || query.include?('#')) || !(k.include?('.') || k.include?('#'))) &&
       k.downcase.include?(query.downcase)
      found.push k
    end
  end
  found
end

#source_map(filename) ⇒ SourceMap

Get a source map by filename.

Parameters:

  • filename (String)

Returns:

Raises:



429
430
431
432
 
# File 'lib/solargraph/api_map.rb', line 429

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:



421
422
423
 
# File 'lib/solargraph/api_map.rb', line 421

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) 


447
448
449
450
451
452
453
454
455
 
# File 'lib/solargraph/api_map.rb', line 447

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

#type_include?(host, mod) ⇒ Boolean

Check if the host class includes the specified module.

Parameters:

  • host (String) —

    The class

  • mod (String) —

    The module

Returns:

  • (Boolean) 


467
468
469
 
# File 'lib/solargraph/api_map.rb', line 467

def type_include?(host, mod)
  store.get_includes(host).include?(mod)
end

#yard_map ⇒ YardMap

Returns:



458
459
460
 
# File 'lib/solargraph/api_map.rb', line 458

def yard_map
  @yard_map ||= YardMap.new
end