class YARD::LinkStdlib::ObjectMap

Definitions

Attributes

version[R]

Ruby version.

@return [Gem::Version]

Public Class Methods

add(ruby_version, force: false) click to toggle source

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
all() click to toggle source

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
current() click to toggle source

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
data_dir() click to toggle source

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
data_dir=(path) click to toggle source

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
new(version) click to toggle source

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
remove(ruby_version, remove_source: true, force: false) click to toggle source
# 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

<=>(other) click to toggle source

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
data(reload: false) click to toggle source
# 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
filename() click to toggle source

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
make(force: false) click to toggle source

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
name_rewrites(reload: false) click to toggle source
# 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(reload: false) click to toggle source

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
path() click to toggle source

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
present?() click to toggle source

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
resolve(name) click to toggle source

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
source() click to toggle source

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
url_for(name, **url_options) click to toggle source

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