class YARD::LinkStdlib::ObjectMap
Definitions
¶ ↑
Attributes
Ruby version.
@return [Gem::Version]
Public Class Methods
Add a Ruby version (download and build map data, see {#make}).
@param [String | Gem::Version] ruby_version
Version to add.
@param [Boolean] force
Pass `true` to re-build map when already present (see {#make}).
@return [ObjectMap]
Added map.
# File lib/yard/link_stdlib/object_map.rb, line 176 def self.add ruby_version, force: false new( ruby_version ).make force: force end
Get all the object maps present.
@return [Array<ObjectMap>]
# File lib/yard/link_stdlib/object_map.rb, line 155 def self.all data_dir.entries. select { |filename| filename.to_s =~ /\Aruby\-(\d+\.)+json\.gz\z/ }. map { |filename| new File.basename( filename.to_s, '.json.gz' ).sub( /\Aruby\-/, '' ) }. sort end
Get the {ObjectMap} for {RubyVersion.get}.
@return [ObjectMap]
# File lib/yard/link_stdlib/object_map.rb, line 140 def self.current version = RubyVersion.get if @@current.nil? || @@current.version != version @@current = new( version ).make end @@current end
The directory in which to load and store object map data.
@example
YARD::LinkStdlib::ObjectMap.data_dir #=> Pathname.new "#{ LinkStdlib::ROOT }/maps"
@return [Pathname]
# File lib/yard/link_stdlib/object_map.rb, line 131 def self.data_dir @@data_dir end
Set the directory in which to load and store map data. Must exist.
@param [String | Pathname] path
New data directory. Will be expanded.
@return [Pathname]
@raise [ArgumentError]
If `path` is not a directory.
# File lib/yard/link_stdlib/object_map.rb, line 109 def self.data_dir= path expanded = Pathname.new( path ).expand_path unless expanded.directory? raise ArgumentError, "Custom ObjectMap.data_dir must expand to an existing directory," + "try creating it first? Received #{ path.inspect }, expanded to " + expanded.to_s.inspect end @@data_dir = expanded end
Instantiate an {ObjectMap} for a Ruby version.
This just initialized the interface - the source may need to be downloaded and the map generated (see {#make}) to use it for anything.
@param [String | Gem::Version] version
Ruby version.
# File lib/yard/link_stdlib/object_map.rb, line 204 def initialize version @version = Gem::Version.new version end
# File lib/yard/link_stdlib/object_map.rb, line 181 def self.remove ruby_version, remove_source: true, force: false raise "TODO" end
Public Instance Methods
Compare {ObjectMap} instances by their {#version} (used to sort them).
@return [Fixnum]
`0` is equal, negatives and positives denote order.
# File lib/yard/link_stdlib/object_map.rb, line 419 def <=> other version <=> other.version end
# File lib/yard/link_stdlib/object_map.rb, line 286 def data reload: false if reload || @data.nil? @name_rewrites = nil @data = Zlib::GzipReader.open path do |gz| JSON.load gz.read end end @data end
The name for this {ObjectMap}'s data file.
@example
YARD::LinkStdlib::ObjectMap.new( '2.3.7' ).filename #=> "ruby-2.3.7.json.gz"
@return [String]
# File lib/yard/link_stdlib/object_map.rb, line 221 def filename @filename ||= "ruby-#{ version }.json.gz" end
Build the map data file (if needed or forced).
@param [Boolean] force
Set to true to re-build even if the map data file is present.
@return [ObjectMap] self
# File lib/yard/link_stdlib/object_map.rb, line 260 def make force: false # Bail unless forced or the map is not present if force log.info "FORCE making object map for Ruby #{ version }..." elsif !present? log.info "Making object map for Ruby #{ version }..." else log.info "Object map for Ruby #{ version } is present." return self end # Make sure we have the source files in place source.ensure # Invoke the build script LinkStdlib.system! \ LinkStdlib::ROOT.join( 'bin', 'make_map.rb' ).to_s, source.src_path.to_s, path.to_s log.info "Made object map for Ruby #{ version }." self end
# File lib/yard/link_stdlib/object_map.rb, line 310 def name_rewrites reload: false data( reload: true ) if reload @name_rewrites ||= \ data.each_with_object( {} ) do |(name, rel_path), name_rewrites| @@name_rewrites.each do |regexp, transformer| if (match = regexp.match( name )) name_rewrites[ transformer.call match ] = rel_path end end end end
Names of the objects in {#data} (equivalent to `self.data.keys`).
@param [Boolean] reload
When `true`, reload the {#data} from disk first.
@return [Array<String>]
# File lib/yard/link_stdlib/object_map.rb, line 305 def names reload: false data( reload: reload ).keys end
Absolute path to this {ObjectMap}'s data file.
@return [Pathname]
# File lib/yard/link_stdlib/object_map.rb, line 230 def path @path ||= self.class.data_dir.join filename end
Is the object map present for this {#version}?
@return [Boolean]
# File lib/yard/link_stdlib/object_map.rb, line 239 def present? path.exist? end
Get the relative path for the URL of an online stdlib document given the code object's name.
@example
YARD::LinkStdlib::ObjectMap.current.resolve 'String' #=> [ 'String', 'String.html' ]
@example De-Aliasing
YARD::LinkStdlib::ObjectMap.current.resolve 'YAML.load' #=> [ 'Psych::load', 'Psych.html#method-c-load' ]
@param [String] name
@return [nil]
The (normalized) `name` was not found in the {ObjectMap}.
@return [Array[(String, String?)>]
The normalized name (which may be totally different than the `name` argument due to de-aliasing) followed by the relative URL path to it's doc.
# File lib/yard/link_stdlib/object_map.rb, line 345 def resolve name name = LinkStdlib.normalize_name name rel_path = data[ name ] if rel_path.nil? split = name.split '::' if (de_aliased_module_name = @@module_aliases[ split.first ]) de_aliased_name = \ [ de_aliased_module_name, *split[ 1..-1 ] ].join( '::' ) if (de_aliased_module_name = data[ de_aliased_name ]) return [ de_aliased_name, de_aliased_module_name ] end end if (rewritten_rel_path = name_rewrites[ name ]) log.debug "Found re-written relative path: " + "#{ name } -> #{ rewritten_rel_path.inspect }" return [ name, rewritten_rel_path ] end # if rewritten_rel_path end # if rel_path.nil? # NOTE `rel_path` may be `nil`, indicating we didn't find shit [ name, rel_path ] end
The {RubySource} interface for this {ObjectMap}.
@return [RubySource]
# File lib/yard/link_stdlib/object_map.rb, line 248 def source @source ||= RubySource.new version end
Get the doc URL for a name.
@example Using defaults
YARD::LinkStdlib::ObjectMap.current.url_for 'String' #=> 'https://docs.ruby-lang.org/en/2.3.0/String.html'
@example Manually override components
YARD::LinkStdlib::ObjectMap.current.url_for 'String', https: false, domain: 'example.com', lang: 'ja' #=> 'http://example.com/ja/2.3.0/String.html'
@param [String] name
Name of the code object.
@param [Hash<Symbol, Object>] url_options
Passed to {LinkStdlib.build_url}.
@return [nil]
The (normalized) `name` was not found in the {ObjectMap}.
@return [String]
The fully-formed URL to the online doc.
# File lib/yard/link_stdlib/object_map.rb, line 399 def url_for name, **url_options name, rel_path = resolve name if rel_path LinkStdlib.build_url \ rel_path, **url_options, version: RubyVersion.minor( version ) end end