Module: Solargraph::YardMap::CoreDocs

Defined in:
lib/solargraph/yard_map/core_docs.rb

Overview

Tools for managing core documentation.

Constant Summary collapse

SOURCE =

The URL for downloading core documentation

'https://solargraph.org/download'
DEFAULT =

The default core documentation version

'2.2.2'

Class Method Summary collapse

Class Method Details

.available ⇒ Array<String>

Get a list of core documentation versions that are available for download.

Returns:

  • (Array<String>) —

    The version numbers

Raises:



80
81
82
83
84
85
86
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 80

def available
  uri = URI.parse("#{SOURCE}/versions.json")
  response = Net::HTTP.get_response(uri)
  obj = JSON.parse(response.body)
  raise SourceNotAvailableError, "Error connecting to #{SOURCE}" unless obj['status'] == 'ok'
  obj['cores']
end

.best_download(current = RUBY_VERSION) ⇒ String

Get the version number of core documentation available for download that is the closest match for the current Ruby version.

Parameters:

  • current (String) (defaults to: RUBY_VERSION) —

    The version to compare

Returns:

  • (String) —

    The version number of the best match



93
94
95
96
97
98
99
100
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 93

def best_download current = RUBY_VERSION
  rv = Gem::Version.new(current)
  found = available
  found.each do |ver|
    return ver if Gem::Version.new(ver) <= rv
  end
  found.last
end

.best_match ⇒ String

Get the version number of the installed core documentation that is the closest match for the current Ruby version.

Returns:

  • (String) —

    The closest match



67
68
69
70
71
72
73
74
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 67

def best_match
  avail = versions
  cur = Gem::Version.new(RUBY_VERSION)
  avail.each do |v|
    return v if Gem::Version.new(v) <= cur
  end
  avail.last
end

.cache_dir ⇒ String

The directory where core documentation is installed.

Returns:

  • (String) 


23
24
25
26
27
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 23

def cache_dir
  # The directory is not stored in a variable so it can be overridden
  # in specs.
  ENV['SOLARGRAPH_CACHE'] || File.join(Dir.home, '.solargraph', 'cache')
end

.clear ⇒ void

This method returns an undefined value.

Reset the core documentation cache to the minimum requirement.



141
142
143
144
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 141

def clear
  FileUtils.rm_rf cache_dir, secure: true
  require_minimum
end

.download(version) ⇒ void

This method returns an undefined value.

Download the specified version of core documentation.

Parameters:

  • version (String) 


124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 124

def download version
  FileUtils.mkdir_p cache_dir
  uri = URI.parse("#{SOURCE}/#{version}.tar.gz")
  # @type [Net::HTTPResponse]
  response = Net::HTTP.get_response(uri)
  if response.code == '404'
    raise ArgumentError, "Version #{version} is not available from #{SOURCE}"
  else
    zipfile = File.join(cache_dir, "#{version}.tar.gz")
    File.binwrite zipfile, response.body
    install_archive zipfile
  end
end

.require_minimum ⇒ void

This method returns an undefined value.

Ensure installation of minimum documentation.



32
33
34
35
36
37
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 32

def require_minimum
  FileUtils.mkdir_p File.join(cache_dir, 'gems')
  return unless best_match.nil?
  FileUtils.cp File.join(Solargraph::YARDOC_PATH, "#{DEFAULT}.tar.gz"), cache_dir
  install_archive File.join(cache_dir, "#{DEFAULT}.tar.gz")
end

.valid?(ver) ⇒ Boolean

True if core documentation is installed for the specified version number.

Parameters:

  • ver (String) —

    The version number to check

Returns:

  • (Boolean) 


44
45
46
47
48
49
50
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 44

def valid?(ver)
  dir = File.join(cache_dir, ver)
  return false unless File.directory?(dir)
  return false unless File.directory?(File.join(dir, 'yardoc'))
  return false unless File.directory?(File.join(dir, 'yardoc-stdlib'))
  true
end

.versions ⇒ Array<String>

Get a list of version numbers for currently installed core documentation.

Returns:

  • (Array<String>) —

    The installed version numbers



56
57
58
59
60
61
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 56

def versions
  dirs = Dir[File.join(cache_dir, '*')].map{|d| File.basename(d)}
  dirs.keep_if{|d| valid?(d)}
  dirs.sort!{|a, b| Gem::Version.new(b) <=> Gem::Version.new(a)}
  dirs
end

.yardoc_file(ver = best_match) ⇒ String

Get the path to a yardoc file for Ruby core documentation.

Parameters:

  • ver (String) (defaults to: best_match) —

    The version number (best match is default)

Returns:

  • (String) —

    The path to the yardoc

Raises:

  • (ArgumentError) 


106
107
108
109
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 106

def yardoc_file(ver = best_match)
  raise ArgumentError, "Invalid core yardoc version #{ver}" unless valid?(ver)
  File.join(cache_dir, ver, 'yardoc')
end

.yardoc_stdlib_file(ver = best_match) ⇒ String

Get the path to a yardoc file for Ruby stdlib documentation.

Parameters:

  • ver (String) (defaults to: best_match) —

    The version number (best match is default)

Returns:

  • (String) —

    The path to the yardoc

Raises:

  • (ArgumentError) 


115
116
117
118
 
# File 'lib/solargraph/yard_map/core_docs.rb', line 115

def yardoc_stdlib_file(ver = best_match)
  raise ArgumentError, "Invalid core yardoc version #{ver}" unless valid?(ver)
  File.join(cache_dir, ver, 'yardoc-stdlib')
end