Class: Solargraph::ApiMap
- Inherits:
-
Object
- Object
- Solargraph::ApiMap
- Includes:
- Logging
- Defined in:
- lib/solargraph/api_map.rb,
lib/solargraph/api_map/cache.rb,
lib/solargraph/api_map/index.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, Index, Store
Constant Summary collapse
Constants included from Logging
Logging::DEFAULT_LOG_LEVEL, Logging::LOG_LEVELS
Instance Attribute Summary collapse
- #missing_docs ⇒ Array<String> readonly
- #unresolved_requires ⇒ Array<String> readonly
Class Method Summary collapse
-
.load(directory) ⇒ ApiMap
Create an ApiMap with a workspace in the specified directory.
-
.load_with_cache(directory, out = IO::NULL) ⇒ ApiMap
Create an ApiMap with a workspace in the specified directory and cache any missing gems.
Instance Method Summary collapse
- #==(other) ⇒ Object
-
#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.
-
#catalog(bench) ⇒ self
Catalog a bench.
- #clip(cursor) ⇒ SourceMap::Clip
-
#clip_at(filename, position) ⇒ SourceMap::Clip
Get a clip by filename and position.
- #core_pins ⇒ Array<Pin::Base>
- #cursor_at(filename, position) ⇒ Source::Cursor
-
#document(path) ⇒ Enumerable<Pin::Base>
Get YARD documentation for the specified path.
-
#document_symbols(filename) ⇒ Array<Pin::Symbol>
Get an array of document symbols from a file.
-
#eql?(other) ⇒ Boolean
This is a mutable object, which is cached in the Chain class - if you add any fields which change the results of calls (not just caches), please also change ‘equality_fields` below.
- #get_block_pins ⇒ Enumerable<Solargraph::Pin::Block>
-
#get_class_variable_pins(namespace) ⇒ Enumerable<Solargraph::Pin::ClassVariable>
Get an array of class variable pins for a namespace.
-
#get_complex_type_methods(complex_type, context = '', internal = false) ⇒ Array<Solargraph::Pin::Base>
Get an array of method pins for a complex type.
-
#get_constants(namespace, *contexts) ⇒ Array<Solargraph::Pin::Base>
Get suggestions for constants in the specified namespace.
- #get_global_variable_pins ⇒ Enumerable<Solargraph::Pin::GlobalVariable>
-
#get_instance_variable_pins(namespace, scope = :instance) ⇒ Array<Solargraph::Pin::InstanceVariable>
Get an array of instance variable pins defined in specified namespace and scope.
-
#get_method_stack(rooted_tag, name, scope: :instance, visibility: [:private, :protected, :public], preserve_generics: false) ⇒ Array<Solargraph::Pin::Method>
Get a stack of method pins for a method name in a potentially parameterized namespace.
-
#get_methods(rooted_tag, scope: :instance, visibility: [:public], deep: true) ⇒ Array<Solargraph::Pin::Method>
Get an array of methods available in a particular context.
- #get_namespace_pins(namespace, context) ⇒ Array<Pin::Namespace>
-
#get_path_pins(path) ⇒ Enumerable<Pin::Base>
Get an array of pins that match the specified path.
-
#get_path_suggestions(path) ⇒ Enumerable<Solargraph::Pin::Base>
deprecated
Deprecated.
Use #get_path_pins instead.
- #get_symbols ⇒ Enumerable<Solargraph::Pin::Base>
- #hash ⇒ Object
- #implicit ⇒ Environ
- #index(pins) ⇒ self
-
#initialize(pins: []) ⇒ ApiMap
constructor
A new instance of ApiMap.
-
#inspect ⇒ Object
avoid enormous dump.
-
#keyword_pins ⇒ Enumerable<Solargraph::Pin::Keyword>
An array of pins based on Ruby keywords (‘if`, `end`, etc.).
- #locate_pins(location) ⇒ Array<Solargraph::Pin::Base>
-
#map(source) ⇒ self
Map a single source.
- #named_macro(name) ⇒ YARD::Tags::MacroDirective?
-
#namespace_exists?(name, context = '') ⇒ Boolean
True if the namespace exists.
-
#namespaces ⇒ Set<String>
An array of namespace names defined in the ApiMap.
- #pins ⇒ Array<Solargraph::Pin::Base>
-
#qualify(tag, context_tag = '') ⇒ String?
Determine fully qualified tag for a given tag used inside the definition of another tag (“context”).
-
#qualify_namespace(namespace, context_namespace = '') ⇒ String?
Determine fully qualified namespace for a given namespace used inside the definition of another tag (“context”).
-
#query_symbols(query) ⇒ Array<Pin::Base>
Get an array of all symbols in the workspace that match the query.
- #required ⇒ Set<String>
-
#search(query) ⇒ Array<String>
Get a list of documented paths that match the query.
-
#source_map(filename) ⇒ SourceMap
Get a source map by filename.
- #source_maps ⇒ Array<SourceMap>
-
#super_and_sub?(sup, sub) ⇒ Boolean
Check if a class is a superclass of another class.
- #to_s ⇒ Object
-
#type_include?(host_ns, module_ns) ⇒ Boolean
Check if the host class includes the specified module, ignoring type parameters used.
- #uncached_gemspecs ⇒ ::Array<Gem::Specification>
Methods included from Logging
Constructor Details
Instance Attribute Details
#missing_docs ⇒ Array<String> (readonly)
23 24 25 |
# File 'lib/solargraph/api_map.rb', line 23 def missing_docs @missing_docs end |
#unresolved_requires ⇒ Array<String> (readonly)
18 19 20 |
# File 'lib/solargraph/api_map.rb', line 18 def unresolved_requires @unresolved_requires end |
Class Method Details
.load(directory) ⇒ ApiMap
Create an ApiMap with a workspace in the specified directory.
166 167 168 169 170 171 172 173 174 |
# File 'lib/solargraph/api_map.rb', line 166 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, out = IO::NULL) ⇒ ApiMap
IO::NULL is incorrectly inferred to be a String.
Create an ApiMap with a workspace in the specified directory and cache any missing gems.
@sg-ignore
186 187 188 189 190 191 192 193 194 195 196 |
# File 'lib/solargraph/api_map.rb', line 186 def self.load_with_cache directory, out = IO::NULL api_map = load(directory) return api_map if api_map.uncached_gemspecs.empty? api_map.uncached_gemspecs.each do |gemspec| out.puts "Caching gem #{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
#==(other) ⇒ Object
44 45 46 |
# File 'lib/solargraph/api_map.rb', line 44 def ==(other) self.eql?(other) end |
#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.
571 572 573 |
# File 'lib/solargraph/api_map.rb', line 571 def bundled? filename source_map_hash.keys.include?(filename) end |
#catalog(bench) ⇒ self
Catalog a bench.
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 |
# File 'lib/solargraph/api_map.rb', line 87 def catalog bench old_api_hash = @source_map_hash&.values&.map(&:api_hash) need_to_uncache = (old_api_hash != bench.source_maps.map(&:api_hash)) # @todo Work around #to_h problem in current Ruby head (3.5) @source_map_hash = bench.source_maps.map { |s| [s.filename, s] }.to_h pins = bench.source_maps.flat_map(&:pins).flatten implicit.clear source_map_hash.each_value do |map| implicit.merge map.environ end unresolved_requires = (bench.external_requires + implicit.requires + bench.workspace.config.required).to_a.compact.uniq if @unresolved_requires != unresolved_requires || @doc_map&.uncached_gemspecs&.any? @doc_map = DocMap.new(unresolved_requires, [], bench.workspace.rbs_collection_path) # @todo Implement gem preferences @unresolved_requires = unresolved_requires need_to_uncache = true end store.update! @@core_map.pins + @doc_map.pins, implicit.pins + pins @cache.clear if need_to_uncache @missing_docs = [] # @todo Implement missing docs self end |
#clip(cursor) ⇒ SourceMap::Clip
538 539 540 541 542 |
# File 'lib/solargraph/api_map.rb', line 538 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.
157 158 159 160 |
# File 'lib/solargraph/api_map.rb', line 157 def clip_at filename, position position = Position.normalize(position) clip(cursor_at(filename, position)) end |
#core_pins ⇒ Array<Pin::Base>
123 124 125 |
# File 'lib/solargraph/api_map.rb', line 123 def core_pins @@core_map.pins end |
#cursor_at(filename, position) ⇒ Source::Cursor
146 147 148 149 150 |
# File 'lib/solargraph/api_map.rb', line 146 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>
This method is likely superfluous. Calling get_path_pins directly should be sufficient.
Get YARD documentation for the specified path.
513 514 515 |
# File 'lib/solargraph/api_map.rb', line 513 def document path get_path_pins(path) end |
#document_symbols(filename) ⇒ Array<Pin::Symbol>
Get an array of document symbols from a file.
548 549 550 551 |
# File 'lib/solargraph/api_map.rb', line 548 def document_symbols filename return [] unless source_map_hash.key?(filename) # @todo Raise error? resolve_method_aliases source_map_hash[filename].document_symbols end |
#eql?(other) ⇒ Boolean
This is a mutable object, which is cached in the Chain class - if you add any fields which change the results of calls (not just caches), please also change ‘equality_fields` below.
39 40 41 42 |
# File 'lib/solargraph/api_map.rb', line 39 def eql?(other) self.class == other.class && equality_fields == other.equality_fields end |
#get_block_pins ⇒ Enumerable<Solargraph::Pin::Block>
346 347 348 |
# File 'lib/solargraph/api_map.rb', line 346 def get_block_pins store.pins_by_class(Pin::Block) end |
#get_class_variable_pins(namespace) ⇒ Enumerable<Solargraph::Pin::ClassVariable>
Get an array of class variable pins for a namespace.
331 332 333 |
# File 'lib/solargraph/api_map.rb', line 331 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.
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 |
# File 'lib/solargraph/api_map.rb', line 425 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.
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 |
# File 'lib/solargraph/api_map.rb', line 232 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>
341 342 343 |
# File 'lib/solargraph/api_map.rb', line 341 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.
314 315 316 317 318 319 320 321 322 323 324 325 |
# File 'lib/solargraph/api_map.rb', line 314 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, visibility: [:private, :protected, :public], preserve_generics: false) ⇒ 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.
462 463 464 465 466 467 468 469 |
# File 'lib/solargraph/api_map.rb', line 462 def get_method_stack rooted_tag, name, scope: :instance, visibility: [:private, :protected, :public], preserve_generics: false rooted_type = ComplexType.parse(rooted_tag) fqns = rooted_type.namespace namespace_pin = store.get_path_pins(fqns).select { |p| p.is_a?(Pin::Namespace) }.first methods = get_methods(rooted_tag, scope: scope, visibility: visibility).select { |p| p.name == name } methods = erase_generics(namespace_pin, rooted_type, methods) unless preserve_generics methods 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.
357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 |
# File 'lib/solargraph/api_map.rb', line 357 def get_methods rooted_tag, scope: :instance, visibility: [:public], deep: true rooted_type = ComplexType.try_parse(rooted_tag) fqns = rooted_type.namespace namespace_pin = store.get_path_pins(fqns).select { |p| p.is_a?(Pin::Namespace) }.first cached = cache.get_methods(rooted_tag, scope, visibility, deep) return cached.clone unless cached.nil? # @type [Array<Solargraph::Pin::Method>] 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) unless %w[Class Class<Class>].include?(rooted_tag) result.map! do |pin| next pin unless pin.path == 'Class#new' init_pin = get_method_stack(rooted_tag, 'initialize').first next pin unless init_pin type = ComplexType.try_parse(ComplexType.try_parse(rooted_tag).namespace) Pin::Method.new( name: 'new', scope: :class, location: init_pin.location, parameters: init_pin.parameters, signatures: init_pin.signatures.map { |sig| sig.proxy(type) }, return_type: type, comments: init_pin.comments, closure: init_pin.closure # @todo Hack to force TypeChecker#internal_or_core? ).tap { |pin| pin.source = :rbs } end end result.concat inner_get_methods('Kernel', :instance, [:public], deep, skip) if visibility.include?(:private) result.concat inner_get_methods('Module', scope, visibility, deep, skip) if scope == :module end result = resolve_method_aliases(result, visibility) if namespace_pin && rooted_tag != rooted_type.name result = result.map { |method_pin| method_pin.resolve_generics(namespace_pin, rooted_type) } end cache.set_methods(rooted_tag, scope, visibility, deep, result) result end |
#get_namespace_pins(namespace, context) ⇒ Array<Pin::Namespace>
252 253 254 |
# File 'lib/solargraph/api_map.rb', line 252 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.
486 487 488 |
# File 'lib/solargraph/api_map.rb', line 486 def get_path_pins path get_path_suggestions(path) end |
#get_path_suggestions(path) ⇒ Enumerable<Solargraph::Pin::Base>
Use #get_path_pins instead.
Get an array of all suggestions that match the specified path.
477 478 479 480 |
# File 'lib/solargraph/api_map.rb', line 477 def get_path_suggestions path return [] if path.nil? resolve_method_aliases store.get_path_pins(path) end |
#get_symbols ⇒ Enumerable<Solargraph::Pin::Base>
336 337 338 |
# File 'lib/solargraph/api_map.rb', line 336 def get_symbols store.get_symbols end |
#hash ⇒ Object
48 49 50 |
# File 'lib/solargraph/api_map.rb', line 48 def hash equality_fields.hash end |
#implicit ⇒ Environ
139 140 141 |
# File 'lib/solargraph/api_map.rb', line 139 def implicit @implicit ||= Environ.new end |
#index(pins) ⇒ self
63 64 65 66 67 68 69 70 71 |
# File 'lib/solargraph/api_map.rb', line 63 def index pins # @todo This implementation is incomplete. It should probably create a # Bench. @source_map_hash = {} implicit.clear cache.clear store.update! @@core_map.pins, pins self end |
#inspect ⇒ Object
avoid enormous dump
57 58 59 |
# File 'lib/solargraph/api_map.rb', line 57 def inspect to_s end |
#keyword_pins ⇒ Enumerable<Solargraph::Pin::Keyword>
An array of pins based on Ruby keywords (‘if`, `end`, etc.).
206 207 208 |
# File 'lib/solargraph/api_map.rb', line 206 def keyword_pins store.pins_by_class(Pin::Keyword) end |
#locate_pins(location) ⇒ Array<Solargraph::Pin::Base>
530 531 532 533 |
# File 'lib/solargraph/api_map.rb', line 530 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.
77 78 79 80 81 |
# File 'lib/solargraph/api_map.rb', line 77 def map source map = Solargraph::SourceMap.map(source) catalog Bench.new(source_maps: [map]) self end |
#named_macro(name) ⇒ YARD::Tags::MacroDirective?
129 130 131 |
# File 'lib/solargraph/api_map.rb', line 129 def named_macro name store.named_macros[name] end |
#namespace_exists?(name, context = '') ⇒ Boolean
True if the namespace exists.
222 223 224 |
# File 'lib/solargraph/api_map.rb', line 222 def namespace_exists? name, context = '' !qualify(name, context).nil? end |
#namespaces ⇒ Set<String>
An array of namespace names defined in the ApiMap.
213 214 215 |
# File 'lib/solargraph/api_map.rb', line 213 def namespaces store.namespaces end |
#pins ⇒ Array<Solargraph::Pin::Base>
199 200 201 |
# File 'lib/solargraph/api_map.rb', line 199 def pins store.pins.clone.freeze 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.
271 272 273 274 275 276 277 278 279 280 281 282 283 284 |
# File 'lib/solargraph/api_map.rb', line 271 def qualify tag, context_tag = '' return tag if ['self', nil].include?(tag) context_type = ComplexType.parse(context_tag).force_rooted return unless context_type type = ComplexType.try_parse(tag) return unless type fqns = qualify_namespace(type.rooted_namespace, context_type.namespace) return unless fqns 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.
296 297 298 299 300 301 302 303 304 305 306 |
# File 'lib/solargraph/api_map.rb', line 296 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.
521 522 523 524 525 526 |
# File 'lib/solargraph/api_map.rb', line 521 def query_symbols query Pin::Search.new( source_map_hash.values.flat_map(&:document_symbols), query ).results end |
#required ⇒ Set<String>
134 135 136 |
# File 'lib/solargraph/api_map.rb', line 134 def required @required ||= Set.new end |
#search(query) ⇒ Array<String>
Get a list of documented paths that match the query.
497 498 499 500 501 |
# File 'lib/solargraph/api_map.rb', line 497 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.
562 563 564 565 |
# File 'lib/solargraph/api_map.rb', line 562 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>
554 555 556 |
# File 'lib/solargraph/api_map.rb', line 554 def source_maps source_map_hash.values end |
#super_and_sub?(sup, sub) ⇒ Boolean
Check if a class is a superclass of another class.
580 581 582 583 584 585 586 587 588 589 590 |
# File 'lib/solargraph/api_map.rb', line 580 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 |
#to_s ⇒ Object
52 53 54 |
# File 'lib/solargraph/api_map.rb', line 52 def to_s self.class.to_s end |
#type_include?(host_ns, module_ns) ⇒ Boolean
Check if the host class includes the specified module, ignoring type parameters used.
599 600 601 |
# File 'lib/solargraph/api_map.rb', line 599 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>
118 119 120 |
# File 'lib/solargraph/api_map.rb', line 118 def uncached_gemspecs @doc_map&.uncached_gemspecs || [] end |