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/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
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.
-
#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.
-
#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)
22 23 24 |
# File 'lib/solargraph/api_map.rb', line 22 def missing_docs @missing_docs end |
#unresolved_requires ⇒ Array<String> (readonly)
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.
155 156 157 158 159 160 161 162 163 |
# File 'lib/solargraph/api_map.rb', line 155 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
175 176 177 178 179 180 181 182 183 184 185 |
# File 'lib/solargraph/api_map.rb', line 175 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
43 44 45 |
# File 'lib/solargraph/api_map.rb', line 43 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.
559 560 561 |
# File 'lib/solargraph/api_map.rb', line 559 def bundled? filename source_map_hash.keys.include?(filename) end |
#catalog(bench) ⇒ self
Catalog a bench.
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 |
# File 'lib/solargraph/api_map.rb', line 77 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)) @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 = Store.new(@@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
526 527 528 529 530 |
# File 'lib/solargraph/api_map.rb', line 526 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.
146 147 148 149 |
# File 'lib/solargraph/api_map.rb', line 146 def clip_at filename, position position = Position.normalize(position) clip(cursor_at(filename, position)) end |
#core_pins ⇒ Array<Pin::Base>
112 113 114 |
# File 'lib/solargraph/api_map.rb', line 112 def core_pins @@core_map.pins end |
#cursor_at(filename, position) ⇒ Source::Cursor
135 136 137 138 139 |
# File 'lib/solargraph/api_map.rb', line 135 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.
501 502 503 |
# File 'lib/solargraph/api_map.rb', line 501 def document path get_path_pins(path) end |
#document_symbols(filename) ⇒ Array<Pin::Symbol>
Get an array of document symbols from a file.
536 537 538 539 |
# File 'lib/solargraph/api_map.rb', line 536 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.
38 39 40 41 |
# File 'lib/solargraph/api_map.rb', line 38 def eql?(other) self.class == other.class && equality_fields == other.equality_fields end |
#get_block_pins ⇒ Enumerable<Solargraph::Pin::Block>
335 336 337 |
# File 'lib/solargraph/api_map.rb', line 335 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.
320 321 322 |
# File 'lib/solargraph/api_map.rb', line 320 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.
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 |
# File 'lib/solargraph/api_map.rb', line 413 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.
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 |
# File 'lib/solargraph/api_map.rb', line 221 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>
330 331 332 |
# File 'lib/solargraph/api_map.rb', line 330 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.
303 304 305 306 307 308 309 310 311 312 313 314 |
# File 'lib/solargraph/api_map.rb', line 303 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.
450 451 452 453 454 455 456 457 |
# File 'lib/solargraph/api_map.rb', line 450 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.
346 347 348 349 350 351 352 353 354 355 356 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 |
# File 'lib/solargraph/api_map.rb', line 346 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? 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>
241 242 243 |
# File 'lib/solargraph/api_map.rb', line 241 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.
474 475 476 |
# File 'lib/solargraph/api_map.rb', line 474 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.
465 466 467 468 |
# File 'lib/solargraph/api_map.rb', line 465 def get_path_suggestions path return [] if path.nil? resolve_method_aliases store.get_path_pins(path) end |
#get_symbols ⇒ Enumerable<Solargraph::Pin::Base>
325 326 327 |
# File 'lib/solargraph/api_map.rb', line 325 def get_symbols store.get_symbols end |
#hash ⇒ Object
47 48 49 |
# File 'lib/solargraph/api_map.rb', line 47 def hash equality_fields.hash end |
#implicit ⇒ Environ
128 129 130 |
# File 'lib/solargraph/api_map.rb', line 128 def implicit @implicit ||= Environ.new end |
#index(pins) ⇒ self
53 54 55 56 57 58 59 60 61 |
# File 'lib/solargraph/api_map.rb', line 53 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.).
195 196 197 |
# File 'lib/solargraph/api_map.rb', line 195 def keyword_pins store.pins_by_class(Pin::Keyword) end |
#locate_pins(location) ⇒ Array<Solargraph::Pin::Base>
518 519 520 521 |
# File 'lib/solargraph/api_map.rb', line 518 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.
67 68 69 70 71 |
# File 'lib/solargraph/api_map.rb', line 67 def map source map = Solargraph::SourceMap.map(source) catalog Bench.new(source_maps: [map]) self end |
#named_macro(name) ⇒ YARD::Tags::MacroDirective?
118 119 120 |
# File 'lib/solargraph/api_map.rb', line 118 def named_macro name store.named_macros[name] end |
#namespace_exists?(name, context = '') ⇒ Boolean
True if the namespace exists.
211 212 213 |
# File 'lib/solargraph/api_map.rb', line 211 def namespace_exists? name, context = '' !qualify(name, context).nil? end |
#namespaces ⇒ Set<String>
An array of namespace names defined in the ApiMap.
202 203 204 |
# File 'lib/solargraph/api_map.rb', line 202 def namespaces store.namespaces end |
#pins ⇒ Array<Solargraph::Pin::Base>
188 189 190 |
# File 'lib/solargraph/api_map.rb', line 188 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.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 |
# File 'lib/solargraph/api_map.rb', line 260 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.
285 286 287 288 289 290 291 292 293 294 295 |
# File 'lib/solargraph/api_map.rb', line 285 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.
509 510 511 512 513 514 |
# File 'lib/solargraph/api_map.rb', line 509 def query_symbols query Pin::Search.new( source_map_hash.values.flat_map(&:document_symbols), query ).results end |
#required ⇒ Set<String>
123 124 125 |
# File 'lib/solargraph/api_map.rb', line 123 def required @required ||= Set.new end |
#search(query) ⇒ Array<String>
Get a list of documented paths that match the query.
485 486 487 488 489 |
# File 'lib/solargraph/api_map.rb', line 485 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.
550 551 552 553 |
# File 'lib/solargraph/api_map.rb', line 550 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>
542 543 544 |
# File 'lib/solargraph/api_map.rb', line 542 def source_maps source_map_hash.values end |
#super_and_sub?(sup, sub) ⇒ Boolean
Check if a class is a superclass of another class.
568 569 570 571 572 573 574 575 576 577 578 |
# File 'lib/solargraph/api_map.rb', line 568 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.
587 588 589 |
# File 'lib/solargraph/api_map.rb', line 587 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>
107 108 109 |
# File 'lib/solargraph/api_map.rb', line 107 def uncached_gemspecs @doc_map&.uncached_gemspecs || [] end |