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

log_level, 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:



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

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
70
71
 
# File 'lib/solargraph/library.rb', line 59

def attach source
  # @type [String, nil]
  current_filename = @current&.filename
  if @current && (!source || current_filename != source.filename) && current_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) 


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

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

#bench ⇒ Bench

Returns:



441
442
443
444
445
446
447
448
449
 
# File 'lib/solargraph/library.rb', line 441

def bench
  Bench.new(
    source_maps: source_map_hash.values,
    workspace: workspace,
    external_requires: external_requires,
    # @sg-ignore OK if @current.filename is nil
    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.



436
437
438
 
# File 'lib/solargraph/library.rb', line 436

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) 


149
150
151
152
153
154
 
# File 'lib/solargraph/library.rb', line 149

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:



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

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) 


97
98
99
 
# File 'lib/solargraph/library.rb', line 97

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.



107
108
109
110
111
112
 
# File 'lib/solargraph/library.rb', line 107

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.



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

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:



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

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))
    # @type [MatchData, nil]
    lft = source.code[0..(offset - 1)]&.match(/\[[a-z0-9_:<, ]*?([a-z0-9_:]*)\z/i)
    # @type [MatchData, nil]
    rgt = source.code[offset..]&.match(/^([a-z0-9_]*)(:[a-z0-9_:]*)?[\]>, ]/i)
    if lft && rgt
      # @sg-ignore lft and rgt are checked for nil above
      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



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

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



86
87
88
89
90
 
# File 'lib/solargraph/library.rb', line 86

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


398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/solargraph/library.rb', line 398

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|
        r = Diagnostics.reporter(reporter_name)
        repargs[r] ||= [] if r
      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?
      # @sg-ignore Hash errors
      repargs[reporter] ||= []
      # @sg-ignore Hash errors
      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>)) 


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

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:



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

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

#external_requires ⇒ Set<String>

Returns:

  • (Set<String>) 


512
513
514
 
# File 'lib/solargraph/library.rb', line 512

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:



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

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:



297
298
299
300
 
# File 'lib/solargraph/library.rb', line 297

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:



306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/solargraph/library.rb', line 306

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.call(full)
    return_if_match.call(full << '.rb')
  end
  nil
rescue FileNotFoundError
  nil
end

#map! ⇒ self

Returns:

  • (self) 


496
497
498
499
500
501
502
503
504
 
# File 'lib/solargraph/library.rb', line 496

def map!
  workspace.sources.each do |src|
    # @sg-ignore OK if src.filename is nil
    source_map_hash[src.filename] = Solargraph::SourceMap.map(src)
    # @sg-ignore OK if src.filename is nil
    find_external_requires source_map_hash[src.filename]
  end
  self
end

#mapped? ⇒ Boolean

Returns:

  • (Boolean) 


476
477
478
 
# File 'lib/solargraph/library.rb', line 476

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.



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

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

#next_map ⇒ SourceMap, Boolean

Returns:



481
482
483
484
485
486
487
488
489
490
491
492
493
 
# File 'lib/solargraph/library.rb', line 481

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}"
    # @sg-ignore OK if src.filename is nil
    source_map_hash[src.filename] = Solargraph::SourceMap.map(src)
    # @sg-ignore OK if src.filename is nil
    source_map_hash[src.filename]
  else
    false
  end
end

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

Parameters:

  • path (String)

Returns:



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

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

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

Returns:



507
508
509
 
# File 'lib/solargraph/library.rb', line 507

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:



355
356
357
358
 
# File 'lib/solargraph/library.rb', line 355

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) 


389
390
391
392
 
# File 'lib/solargraph/library.rb', line 389

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:



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
285
286
287
288
289
290
291
 
# File 'lib/solargraph/library.rb', line 248

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(:closure), 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(:closure), 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|
        # @sg-ignore Unresolved call to []
        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>) 


346
347
348
349
 
# File 'lib/solargraph/library.rb', line 346

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:



234
235
236
237
238
239
 
# File 'lib/solargraph/library.rb', line 234

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:



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

def source_map_hash
  @source_map_hash ||= {}
end

#source_maps ⇒ Array<SourceMap>

Returns:



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

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:



217
218
219
220
221
222
223
224
 
# File 'lib/solargraph/library.rb', line 217

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