Class: Solargraph::Library

Inherits:
Object
  • Object
show all
Includes:
Observable, Logging
Defined in:
lib/solargraph/library.rb

Overview

A Library handles coordination between a Workspace and an ApiMap.

Constant Summary

Constants included from Logging

Solargraph::Logging::DEFAULT_LOG_LEVEL, Solargraph::Logging::LOG_LEVELS

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Logging

logger

Constructor Details

#initialize(workspace = Solargraph::Workspace.new, name = nil) ⇒ Library

Returns a new instance of Library.

Parameters:

  • workspace (Solargraph::Workspace) (defaults to: Solargraph::Workspace.new)
  • name (String, nil) (defaults to: nil) 


28
29
30
31
32
33
34
35
36
 
# File 'lib/solargraph/library.rb', line 28

def initialize workspace = Solargraph::Workspace.new, name = nil
  @workspace = workspace
  @name = name
  # @type [Integer, nil]
  @total = nil
  # @type [Source, nil]
  @current = nil
  @sync_count = 0
end

Instance Attribute Details

#cache_progress ⇒ LanguageServer::Progress? (readonly)

Returns:



24
25
26
 
# File 'lib/solargraph/library.rb', line 24

def cache_progress
  @cache_progress
end

#current ⇒ Source? (readonly)

Returns:



21
22
23
 
# File 'lib/solargraph/library.rb', line 21

def current
  @current
end

#name ⇒ String? (readonly)

Returns:

  • (String, nil) 


18
19
20
 
# File 'lib/solargraph/library.rb', line 18

def name
  @name
end

#workspace ⇒ Solargraph::Workspace (readonly)

Returns:



15
16
17
 
# File 'lib/solargraph/library.rb', line 15

def workspace
  @workspace
end

Class Method Details

.load(directory = '', name = nil) ⇒ Solargraph::Library

Create a library from a directory.

Parameters:

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

    The path to be used for the workspace

  • name (String, nil) (defaults to: nil)

Returns:



445
446
447
 
# File 'lib/solargraph/library.rb', line 445

def self.load directory = '', name = nil
  Solargraph::Library.new(Solargraph::Workspace.new(directory), name)
end

Instance Method Details

#attach(source) ⇒ void

This method returns an undefined value.

Attach a source to the library.

The attached source does not need to be a part of the workspace. The library will include it in the ApiMap while it’s attached. Only one source can be attached to the library at a time.

Parameters:



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/solargraph/library.rb', line 59

def attach source
  if @current && (!source || @current.filename != source.filename) && source_map_hash.key?(@current.filename) && !workspace.has_file?(@current.filename)
    source_map_hash.delete @current.filename
    source_map_external_require_hash.delete @current.filename
    @external_requires = nil
  end
  changed = source && @current != source
  @current = source
  maybe_map @current
  catalog if changed
end

#attached?(filename) ⇒ Boolean Also known as: open?

True if the specified file is currently attached.

Parameters:

  • filename (String)

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/solargraph/library.rb', line 75

def attached? filename
  !@current.nil? && @current.filename == filename
end

#bench ⇒ Bench

Returns:



431
432
433
434
435
436
437
438
 
# File 'lib/solargraph/library.rb', line 431

def bench
  Bench.new(
    source_maps: source_map_hash.values,
    workspace: workspace,
    external_requires: external_requires,
    live_map: @current ? source_map_hash[@current.filename] : nil
  )
end

#catalog ⇒ void

This method returns an undefined value.

Update the ApiMap from the library’s workspace and open files.



426
427
428
 
# File 'lib/solargraph/library.rb', line 426

def catalog
  @sync_count += 1
end

#close(filename) ⇒ void

This method returns an undefined value.

Close a file in the library. Closing a file will make it unavailable for checkout although it may still exist in the workspace.

Parameters:

  • filename (String) 


147
148
149
150
151
152
 
# File 'lib/solargraph/library.rb', line 147

def close filename
  return unless @current&.filename == filename

  @current = nil
  catalog unless workspace.has_file?(filename)
end

#completions_at(filename, line, column) ⇒ SourceMap::Completion?

TODO:

Take a Location instead of filename/line/column

Get completion suggestions at the specified file and location.

Parameters:

  • filename (String) —

    The file to analyze

  • line (Integer) —

    The zero-based line number

  • column (Integer) —

    The zero-based column number

Returns:



161
162
163
164
165
166
167
168
 
# File 'lib/solargraph/library.rb', line 161

def completions_at filename, line, column
  sync_catalog
  position = Position.new(line, column)
  cursor = Source::Cursor.new(read(filename), position)
  mutex.synchronize { api_map.clip(cursor).complete }
rescue FileNotFoundError => e
  handle_file_not_found filename, e
end

#contain?(filename) ⇒ Boolean

True if the specified file is included in the workspace (but not necessarily open).

Parameters:

  • filename (String)

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/solargraph/library.rb', line 95

def contain? filename
  workspace.has_file?(filename)
end

#create(filename, text) ⇒ Boolean

Create a source to be added to the workspace. The file is ignored if it is neither open in the library nor included in the workspace.

Parameters:

  • filename (String)
  • text (String) —

    The contents of the file

Returns:

  • (Boolean) —

    True if the file was added to the workspace.



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

def create filename, text
  return false unless contain?(filename) || open?(filename)
  source = Solargraph::Source.load_string(text, filename)
  workspace.merge(source)
  true
end

#create_from_disk(*filenames) ⇒ Boolean

Create file sources from files on disk. A file is ignored if it is neither open in the library nor included in the workspace.

Parameters:

  • filenames (Array<String>)

Returns:

  • (Boolean) —

    True if at least one file was added to the workspace.



117
118
119
120
121
122
123
124
 
# File 'lib/solargraph/library.rb', line 117

def create_from_disk *filenames
  sources = filenames
    .reject { |filename| File.directory?(filename) || !File.exist?(filename) }
    .map { |filename| Solargraph::Source.load_string(File.read(filename), filename) }
  result = workspace.merge(*sources)
  sources.each { |source| maybe_map source }
  result
end

#definitions_at(filename, line, column) ⇒ Array<Solargraph::Pin::Base>?

TODO:

Take filename/position instead of filename/line/column

Get definition suggestions for the expression at the specified file and location.

Parameters:

  • filename (String) —

    The file to analyze

  • line (Integer) —

    The zero-based line number

  • column (Integer) —

    The zero-based column number

Returns:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/solargraph/library.rb', line 178

def definitions_at filename, line, column
  sync_catalog
  position = Position.new(line, column)
  cursor = Source::Cursor.new(read(filename), position)
  if cursor.comment?
    source = read(filename)
    offset = Solargraph::Position.to_offset(source.code, Solargraph::Position.new(line, column))
    lft = source.code[0..offset-1].match(/\[[a-z0-9_:<, ]*?([a-z0-9_:]*)\z/i)
    rgt = source.code[offset..-1].match(/^([a-z0-9_]*)(:[a-z0-9_:]*)?[\]>, ]/i)
    if lft && rgt
      tag = (lft[1] + rgt[1]).sub(/:+$/, '')
      clip = mutex.synchronize { api_map.clip(cursor) }
      clip.translate tag
    else
      []
    end
  else
    mutex.synchronize do
      clip = api_map.clip(cursor)
      clip.define.map { |pin| pin.realize(api_map) }
    end
  end
rescue FileNotFoundError => e
  handle_file_not_found(filename, e)
end

#delete(*filenames) ⇒ Boolean

Delete files from the library. Deleting a file will make it unavailable for checkout and optionally remove it from the workspace unless the workspace configuration determines that it should still exist.

Parameters:

  • filenames (Array<String>)

Returns:

  • (Boolean) —

    True if any file was deleted



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

def delete *filenames
  result = false
  filenames.each do |filename|
    detach filename
    source_map_hash.delete(filename)
    result ||= workspace.remove(filename)
  end
  result
end

#detach(filename) ⇒ Boolean

Detach the specified file if it is currently attached to the library.

Parameters:

  • filename (String)

Returns:

  • (Boolean) —

    True if the specified file was detached



84
85
86
87
88
 
# File 'lib/solargraph/library.rb', line 84

def detach filename
  return false if @current.nil? || @current.filename != filename
  attach nil
  true
end

#diagnose(filename) ⇒ Array<Hash>

Get diagnostics about a file.

Parameters:

  • filename (String)

Returns:

  • (Array<Hash>) 


391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/solargraph/library.rb', line 391

def diagnose filename
  # @todo Only open files get diagnosed. Determine whether anything or
  #   everything in the workspace should get diagnosed, or if there should
  #   be an option to do so.
  #
  sync_catalog
  return [] unless open?(filename)
  result = []
  source = read(filename)

  # @type [Hash{Class<Solargraph::Diagnostics::Base> => Array<String>}]
  repargs = {}
  workspace.config.reporters.each do |line|
    if line == 'all!'
      Diagnostics.reporters.each do |reporter_name|
        repargs[Diagnostics.reporter(reporter_name)] ||= []
      end
    else
      args = line.split(':').map(&:strip)
      name = args.shift
      reporter = Diagnostics.reporter(name)
      raise DiagnosticsError, "Diagnostics reporter #{name} does not exist" if reporter.nil?
      repargs[reporter] ||= []
      repargs[reporter].concat args
    end
  end
  repargs.each_pair do |reporter, args|
    result.concat reporter.new(*args.uniq).diagnose(source, api_map)
  end
  result
end

#document(query) ⇒ Enumerable<YARD::CodeObjects::Base>, Array(ApiMap, Enumerable<Pin::Base>)

Parameters:

  • query (String)

Returns:

  • (Enumerable<YARD::CodeObjects::Base>)
  • (Array(ApiMap, Enumerable<Pin::Base>)) 


332
333
334
335
 
# File 'lib/solargraph/library.rb', line 332

def document query
  sync_catalog
  mutex.synchronize { [api_map, api_map.get_path_pins(query)] }
end

#document_symbols(filename) ⇒ Array<Solargraph::Pin::Base>

Get an array of document symbols.

Document symbols are composed of namespace, method, and constant pins. The results of this query are appropriate for building the response to a textDocument/documentSymbol message in the language server protocol.

Parameters:

  • filename (String)

Returns:



361
362
363
364
 
# File 'lib/solargraph/library.rb', line 361

def document_symbols filename
  sync_catalog
  mutex.synchronize { api_map.document_symbols(filename) }
end

#external_requires ⇒ Set<String>

Returns:

  • (Set<String>) 


497
498
499
 
# File 'lib/solargraph/library.rb', line 497

def external_requires
  @external_requires ||= source_map_external_require_hash.values.flatten.to_set
end

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

Get an array of pins that match a path.

Parameters:

  • path (String)

Returns:



324
325
326
327
 
# File 'lib/solargraph/library.rb', line 324

def get_path_pins path
  sync_catalog
  mutex.synchronize { api_map.get_path_suggestions(path) }
end

#inspect ⇒ Object 



38
39
40
41
 
# File 'lib/solargraph/library.rb', line 38

def inspect
  # Let's not deal with insane data dumps in spec failures
  to_s
end

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

Get the pins at the specified location or nil if the pin does not exist.

Parameters:

Returns:



290
291
292
293
 
# File 'lib/solargraph/library.rb', line 290

def locate_pins location
  sync_catalog
  mutex.synchronize { api_map.locate_pins(location).map { |pin| pin.realize(api_map) } }
end

#locate_ref(location) ⇒ Location?

Match a require reference to a file.

Parameters:

Returns:



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/solargraph/library.rb', line 299

def locate_ref location
  map = source_map_hash[location.filename]
  return if map.nil?
  pin = map.requires.select { |p| p.location.range.contain?(location.range.start) }.first
  return nil if pin.nil?
  # @param full [String]
  return_if_match = proc do |full|
    if source_map_hash.key?(full)
      return Location.new(full, Solargraph::Range.from_to(0, 0, 0, 0))
    end
  end
  workspace.require_paths.each do |path|
    full = File.join path, pin.name
    return_if_match.(full)
    return_if_match.(full << ".rb")
  end
  nil
rescue FileNotFoundError
  nil
end

#map! ⇒ self

Returns:

  • (self) 


483
484
485
486
487
488
489
 
# File 'lib/solargraph/library.rb', line 483

def map!
  workspace.sources.each do |src|
    source_map_hash[src.filename] = Solargraph::SourceMap.map(src)
    find_external_requires source_map_hash[src.filename]
  end
  self
end

#mapped? ⇒ Boolean

Returns:

  • (Boolean) 


465
466
467
 
# File 'lib/solargraph/library.rb', line 465

def mapped?
  (workspace.filenames - source_map_hash.keys).empty?
end

#merge(source) ⇒ Boolean

Try to merge a source into the library’s workspace. If the workspace is not configured to include the source, it gets ignored.

Parameters:

Returns:

  • (Boolean) —

    True if the source was merged into the workspace.



454
455
456
457
458
 
# File 'lib/solargraph/library.rb', line 454

def merge source
  result = workspace.merge(source)
  maybe_map source
  result
end

#next_map ⇒ SourceMap, Boolean

Returns:



470
471
472
473
474
475
476
477
478
479
480
 
# File 'lib/solargraph/library.rb', line 470

def next_map
  return false if mapped?
  src = workspace.sources.find { |s| !source_map_hash.key?(s.filename) }
  if src
    Logging.logger.debug "Mapping #{src.filename}"
    source_map_hash[src.filename] = Solargraph::SourceMap.map(src)
    source_map_hash[src.filename]
  else
    false
  end
end

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

Parameters:

  • path (String)

Returns:



368
369
370
371
 
# File 'lib/solargraph/library.rb', line 368

def path_pins path
  sync_catalog
  mutex.synchronize { api_map.get_path_suggestions(path) }
end

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

Returns:



492
493
494
 
# File 'lib/solargraph/library.rb', line 492

def pins
  @pins ||= []
end

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

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

Parameters:

  • query (String)

Returns:



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

def query_symbols query
  sync_catalog
  mutex.synchronize { api_map.query_symbols query }
end

#read_text(filename) ⇒ String

Get the current text of a file in the library.

Parameters:

  • filename (String)

Returns:

  • (String) 


382
383
384
385
 
# File 'lib/solargraph/library.rb', line 382

def read_text filename
  source = read(filename)
  source.code
end

#references_from(filename, line, column, strip: false, only: false) ⇒ Array<Solargraph::Location>

TODO:

Take a Location instead of filename/line/column

Parameters:

  • filename (String)
  • line (Integer)
  • column (Integer)
  • strip (Boolean) (defaults to: false) —

    Strip special characters from variable names

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

    Search for references in the current file only

Returns:



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/solargraph/library.rb', line 243

def references_from filename, line, column, strip: false, only: false
  sync_catalog
  cursor = Source::Cursor.new(read(filename), [line, column])
  clip = mutex.synchronize { api_map.clip(cursor) }
  pin = clip.define.first
  return [] unless pin
  result = []
  files = if only
    [api_map.source_map(filename)]
  else
    (workspace.sources + (@current ? [@current] : []))
  end
  files.uniq(&:filename).each do |source|
    found = source.references(pin.name)
    found.select! do |loc|
      referenced = definitions_at(loc.filename, loc.range.ending.line, loc.range.ending.character).first
      referenced&.path == pin.path
    end
    if pin.path == 'Class#new'
      caller = cursor.chain.base.infer(api_map, clip.send(:block), clip.locals).first
      if caller.defined?
        found.select! do |loc|
          clip = api_map.clip_at(loc.filename, loc.range.start)
          other = clip.send(:cursor).chain.base.infer(api_map, clip.send(:block), clip.locals).first
          caller == other
        end
      else
        found.clear
      end
    end
    # HACK: for language clients that exclude special characters from the start of variable names
    if strip && match = cursor.word.match(/^[^a-z0-9_]+/i)
      found.map! do |loc|
        Solargraph::Location.new(loc.filename, Solargraph::Range.from_to(loc.range.start.line, loc.range.start.column + match[0].length, loc.range.ending.line, loc.range.ending.column))
      end
    end
    result.concat(found.sort do |a, b|
      a.range.start.line <=> b.range.start.line
    end)
  end
  result.uniq
end

#search(query) ⇒ Array<String>

Parameters:

  • query (String)

Returns:

  • (Array<String>) 


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

def search query
  sync_catalog
  mutex.synchronize { api_map.search query }
end

#signatures_at(filename, line, column) ⇒ Array<Solargraph::Pin::Base>

TODO:

Take filename/position instead of filename/line/column

Get signature suggestions for the method at the specified file and location.

Parameters:

  • filename (String) —

    The file to analyze

  • line (Integer) —

    The zero-based line number

  • column (Integer) —

    The zero-based column number

Returns:



229
230
231
232
233
234
 
# File 'lib/solargraph/library.rb', line 229

def signatures_at filename, line, column
  sync_catalog
  position = Position.new(line, column)
  cursor = Source::Cursor.new(read(filename), position)
  mutex.synchronize { api_map.clip(cursor).signify }
end

#source_map_hash ⇒ Hash{String => SourceMap}

Returns:



461
462
463
 
# File 'lib/solargraph/library.rb', line 461

def source_map_hash
  @source_map_hash ||= {}
end

#source_maps ⇒ Array<SourceMap>

Returns:



374
375
376
 
# File 'lib/solargraph/library.rb', line 374

def source_maps
  source_map_hash.values
end

#synchronized? ⇒ Boolean

True if the ApiMap is up to date with the library’s workspace and open files.

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/solargraph/library.rb', line 47

def synchronized?
  @sync_count < 2
end

#type_definitions_at(filename, line, column) ⇒ Array<Solargraph::Pin::Base>?

TODO:

Take filename/position instead of filename/line/column

Get type definition suggestions for the expression at the specified file and location.

Parameters:

  • filename (String) —

    The file to analyze

  • line (Integer) —

    The zero-based line number

  • column (Integer) —

    The zero-based column number

Returns:



212
213
214
215
216
217
218
219
 
# File 'lib/solargraph/library.rb', line 212

def type_definitions_at filename, line, column
  sync_catalog
  position = Position.new(line, column)
  cursor = Source::Cursor.new(read(filename), position)
  mutex.synchronize { api_map.clip(cursor).types }
rescue FileNotFoundError => e
  handle_file_not_found filename, e
end