yard-link_stdlib 0.1.0 → 0.1.1

data/lib/yard/link_stdlib/object_map.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 # encoding: UTF-8
+# doctest: true
 
 
 # Requirements
@@ -56,11 +57,55 @@ class ObjectMap
   }
 
   @@current = nil
+  
+  
+  # A map of module names that we know *actually* point to another one.
+  # 
+  # This is basically here to support {YAML}, which internally points to 
+  # {Psych} in a truly annoying fashion... seems to be a remnant from when 
+  # `Syck` was around, but that appears to have been yanked out years ago 
+  # around Ruby 2.0, and I can't think of seeing anyone use anything except 
+  # {Psych} for about a decade.
+  # 
+  # However, it means that there is no entry in the object map for things like
+  # {YAML.load}, which are pretty commonly used. This functionality allows
+  # us to address that, by being aware that {YAML} points to {Psych} for 
+  # practical purposes.
+  # 
+  # @return [Hash<String, String>]
+  #
+  @@module_aliases = {
+    "YAML" => "Psych",
+  }
+  
+  @@name_rewrites = {
+    # The instance methods of the {JSON} module are encapsulated in a 
+    # {Module#module_function} context, which adds them as module methods as
+    # well, but RDoc doesn't seem to pick that up, so we just transform them
+    # to make this bullshit work.
+    # 
+    # Creates mappings like:
+    # 
+    #     "JSON::load" => "JSON.html#method-i-load"
+    #     "JSON::dump" => "JSON.html#method-i-dump"
+    # 
+    /\AJSON#(.*)\z/ => ->( match ) { "JSON::#{ match[ 1 ] }" },
+  }
 
   
-  # Class Methods
+  # Singleton Methods
   # ========================================================================
-
+  
+  # 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.
+  # 
   def self.data_dir= path
     expanded = Pathname.new( path ).expand_path
 
@@ -74,12 +119,24 @@ class ObjectMap
     @@data_dir = expanded
   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]
+  # 
   def self.data_dir
     @@data_dir
   end
 
-
+  
+  # Get the {ObjectMap} for {RubyVersion.get}.
+  # 
+  # @return [ObjectMap]
+  # 
   def self.current
     version = RubyVersion.get
 
@@ -90,43 +147,40 @@ class ObjectMap
     @@current
   end
 
-
   
-  # @todo Document list method.
+  # Get all the object maps present.
   # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
+  # @return [Array<ObjectMap>]
   # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def self.list
+  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 # .list
-
-
-  # def self.cache key, &load
-  #   @cache ||= {}
-
-  #   unless @cache.key? key
-  #     @cache[key] = load.call
-  #   end
-
-  #   @cache[key]
-  # end
-
-
-  # def self.get version = LinkStdlib::RubyVersion.get, make: true
-  #   cache version do
-  #     make( version ) if make
-  #     load version
-  #   end
-  # end
+  end # .all
+  
+  
+  # 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.
+  # 
+  def self.add ruby_version, force: false
+    new( ruby_version ).make force: force
+  end
+  
+  
+  def self.remove ruby_version, remove_source: true, force: false
+    raise "TODO"
+  end
 
 
   # Ruby version.
@@ -134,18 +188,45 @@ class ObjectMap
   # @return [Gem::Version]
   #     
   attr_reader :version
-
-
+  
+  
+  # Construction
+  # ==========================================================================
+  
+  # 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.
+  # 
   def initialize version
     @version = Gem::Version.new version
   end
+  
+  
+  # Instance Methods
+  # ==========================================================================
 
-
+  
+  # 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]
+  # 
   def filename
     @filename ||= "ruby-#{ version }.json.gz"
   end
 
-
+  
+  # Absolute path to this {ObjectMap}'s data file.
+  # 
+  # @return [Pathname]
+  # 
   def path
     @path ||= self.class.data_dir.join filename
   end
@@ -159,12 +240,23 @@ class ObjectMap
     path.exist?
   end
 
-
+  
+  # The {RubySource} interface for this {ObjectMap}.
+  # 
+  # @return [RubySource]
+  # 
   def source
     @source ||= RubySource.new version
   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
+  # 
   def make force: false
     # Bail unless forced or the map is not present
     if force
@@ -193,6 +285,7 @@ class ObjectMap
 
   def data reload: false
     if reload || @data.nil?
+      @name_rewrites = nil
       @data = Zlib::GzipReader.open path do |gz|
         JSON.load gz.read
       end
@@ -200,8 +293,129 @@ class ObjectMap
 
     @data
   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>]
+  # 
+  def names reload: false
+    data( reload: reload ).keys
+  end
+  
+  
+  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
+  
+  
+  # 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.
+  # 
+  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 # .resolve
+  
+  
+  # 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.
+  # 
+  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 # .url_for
+  
+  
+  # Language Integration Instance Methods
+  # --------------------------------------------------------------------------
 
-
+  # Compare {ObjectMap} instances by their {#version} (used to sort them).
+  # 
+  # @return [Fixnum]
+  #   `0` is equal, negatives and positives denote order.
+  # 
   def <=> other
     version <=> other.version
   end

data/lib/yard/link_stdlib/ruby_source.rb

@@ -35,7 +35,22 @@ class RubySource
 
   # Class Methods
   # ============================================================================
-
+  
+  
+  def self.make_missing?
+    unless instance_variable_defined? :@make_missing
+      @make_missing = true
+    end
+    
+    @make_missing
+  end
+  
+  
+  def self.make_missing= value
+    @make_missing = !!value
+  end
+  
+  
   # Ensure the version's source is downloaded and extracted.
   # 
   # @example
@@ -157,6 +172,12 @@ class RubySource
       log.info "Source for Ruby #{ version } is present."
       return
     end
+    
+    unless self.class.make_missing?
+      raise RuntimeError,
+        "Object map for Ruby version #{ version } missing; " +
+        "not configured to auto-make"
+    end
 
     # Download unless the tar's already there
     download

data/lib/yard/link_stdlib/ruby_version.rb

@@ -91,8 +91,9 @@ module RubyVersion
   # 
   # @return [Gem::Version]
   # 
-  def self.minor
-    Gem::Version.new( ( get.segments[0..1] + [0] ).map( &:to_s ).join( '.' ) )
+  def self.minor version = self.get
+    Gem::Version.new \
+      ( version.segments[0..1] + [0] ).map( &:to_s ).join( '.' )
   end
 
 
@@ -101,7 +102,7 @@ module RubyVersion
   # we were happy with from the gemspec.
   # 
   # @param [:minimum_supported, :latest_stable, :current_runtime] value
-  #   Just picks which of these versions {#fallback} will use:
+  #   Just picks which of these versions {.fallback} will use:
   #   
   #   1.  {MINIMUM_SUPPORTED}
   #   2.  {LATEST_STABLE}

data/lib/yard/link_stdlib/version.rb

@@ -55,13 +55,13 @@ def self.repo?
   ROOT.join( 'dev' ).directory?
 end
 
-# {Singleton} extension of {Gem::Version} that loads {Locd::VERSION} and
+# {Singleton} extension of {Gem::Version} that loads {VERSION} and
 # provides some convenient methods.
 # 
 class Version < Gem::Version
   include ::Singleton
 
-  # Private method to instantiate the {#instance} using the {Locd::VERSION}
+  # Private method to instantiate the {.instance} using the {VERSION}
   # {String}.
   # 
   # @return [Version]
@@ -74,7 +74,7 @@ class Version < Gem::Version
   # instances.
   private_class_method :new
 
-  # Proxies to the {#instance}'s {#dev?}.
+  # Proxies to the {.instance}'s {#dev?}.
   # 
   # @return (see #dev?)
   #