yard-link_stdlib 0.1.0

data/lib/yard/link_stdlib/dump.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+
+# Namespace
+# ========================================================================
+
+module  YARD
+module  LinkStdlib
+
+
+# Definitions
+# ========================================================================
+
+# Dump a hash of values as a `debug`-level log message (`log` is a global
+# function when you're hangin' in the YARD).
+# 
+# @example Dump values with a message
+#   dump "There was a problem with the ", obj, "object!",
+#     value_a: value_a,
+#     value_b: value_b
+# 
+# @example Dump values without a message
+#   dump value_a: value_a, value_b: value_b
+# 
+# @param [Array<String | Object>] message
+#   Optional log message. Entries will be space-joined to form the message 
+#   string: strings will be left as-is, and other objects will be
+#   stringified by calling their `#inspect` method. See examples.
+# 
+# @param [Hash<Symbol, Object>] values
+#   Map of names to values to dump.
+# 
+# @return
+#   Whatever `log.debug` returns.
+# 
+def self.dump *message, **values
+
+  max_name_length = values.
+    keys.
+    map { |name| name.to_s.length }.
+    max
+
+  values_str = values.
+    map { |name, value|
+      name_str = "%-#{ max_name_length + 2 }s" % "#{ name }:"
+
+      "  #{ name_str } #{ value.inspect } (#{ value.class })"
+    }.
+    join( "\n" )
+  
+  message_str = message.
+    map { |part|
+      case part
+      when String
+        part
+      else
+        part.inspect
+      end
+    }.
+    join( " " )
+  
+  log_str = "Values:\n\n#{ values_str }\n"
+  log_str = "#{ message_str }\n\n#{ log_str }" unless message_str.empty?
+
+  log.debug "yard-link_stdlib: #{ log_str }"
+end # .dump
+
+
+# /Namespace
+# ========================================================================
+
+end # module LinkStdlib
+end # module YARD

data/lib/yard/link_stdlib/html_helper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ------------------------------------------------------------------------
+
+require 'zlib'
+
+# Deps
+# ------------------------------------------------------------------------
+
+require 'yard'
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+require_relative './dump'
+require_relative './ruby_version'
+require_relative './object_map'
+
+
+# Namespace
+# ========================================================================
+
+module  YARD
+module  LinkStdlib
+
+
+# Definitions
+# ========================================================================
+
+# A helper module to add to {YARD::Templates::Template.extra_includes} to 
+# handle linking stdlib references.
+# 
+# @see https://www.rubydoc.info/gems/yard/YARD%2FTemplates%2FTemplate.extra_includes
+# 
+module HtmlHelper
+
+  # The {Proc} we pass to 
+  # 
+  # @return [Proc]
+  # 
+  INCLUDE_FILTER = proc do |options|
+    HtmlHelper if options.format == :html
+  end
+
+
+  # The only real meat of this whole gem - hook into object linking.
+  # 
+  # We link to the stdlib if:
+  # 
+  # 1.  We didn't link to anything else (local stuff take precedence).
+  # 2.  We can find a match for the reference.
+  # 
+  # @see https://www.rubydoc.info/gems/yard/YARD/Templates/Helpers/HtmlHelper#link_object-instance_method
+  # 
+  # @param [YARD::CodeObjects::Base] obj
+  #   The object to link to.
+  # 
+  # @param [String?] title
+  #   Optional title to display the link as.
+  # 
+  # @param [nil | ?] anchor
+  #   Not sure... not doc'd in YARD.
+  # 
+  # @param [Boolean] relative
+  #   Again, not sure... not doc'd in YARD, but seems like a boolean.
+  # 
+  # @return [String]
+  #   The HTML source for the link.
+  # 
+  def link_object obj, title = nil, anchor = nil, relative = true
+    # See what the super method can do...
+    super_link = super
+
+    # Bail out unless `super` returned a {String}, which I'm guessing would be
+    # `nil`, but not sure.
+    unless super_link.is_a?( String )
+      LinkStdlib.dump "Object not linkable",
+        obj: obj,
+        super_link: super_link
+      return super_link
+    end
+
+    LinkStdlib.dump "Object *may* be linkable!",
+      obj: obj,
+      super_link: super_link
+
+    # `key` is what we gonna look up in the stdlib...
+    key = super_link
+
+    # Strip off any leading `::`
+    key = key[2..-1] if key.start_with?( '::' )
+
+    # Stdlib rdoc uses `ClassOrModule::class_method` format for class methods,
+    # so we want to convert to that
+    stdlib_key = key.sub /\.(\w+[\?\!]?)\z/, '::\1'
+
+    if ( path = ObjectMap.current.data[ stdlib_key ] )
+      LinkStdlib.dump "Matched stdlib link!",
+        path: path,
+        key: key,
+        stdlib_key: stdlib_key
+      
+      version = LinkStdlib::RubyVersion.minor
+      
+      [
+        %{<a href="https://docs.ruby-lang.org/en/#{ version }/#{ path }">},
+        key,
+        %{</a>},
+      ].join ''
+
+    else
+      LinkStdlib.dump "Got nada.",
+        super_link: super_link
+      
+      super_link
+
+    end
+
+  end # #link_object
+
+end # module HtmlHelper
+
+
+# /Namespace
+# ========================================================================
+
+end # module LinkStdlib
+end # module YARD

data/lib/yard/link_stdlib/object_map.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ----------------------------------------------------------------------------
+
+# Encode object maps in JSON... it's just super easy for everything, and
+# gzip should take care of any size concerns.
+require 'json'
+
+# Good ol' mkdir_p...
+require 'fileutils'
+
+# Store the JSON-encoded maps compressed
+require 'zlib'
+
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+# We need {YARD::LinkStdlib::ROOT} to find `//tmp`
+require_relative './version'
+
+# Need to be able to {RubySource.ensure} we have source code we need
+require_relative './ruby_source'
+
+
+# Namespace
+# ========================================================================
+
+module  YARD
+module  LinkStdlib
+
+
+# Definitions
+# ========================================================================
+
+
+class ObjectMap
+
+  # Mixins
+  # ==========================================================================
+
+  include Comparable
+
+  
+  # Class Variables
+  # ==========================================================================
+
+  @@data_dir = LinkStdlib::ROOT.join( 'maps' ).tap { |path|
+    FileUtils.mkdir_p( path ) unless path.exist?
+  }
+
+  @@current = nil
+
+  
+  # Class Methods
+  # ========================================================================
+
+  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
+
+
+  def self.data_dir
+    @@data_dir
+  end
+
+
+  def self.current
+    version = RubyVersion.get
+
+    if @@current.nil? || @@current.version != version
+      @@current = new( version ).make
+    end
+
+    @@current
+  end
+
+
+  
+  # @todo Document list method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def self.list
+    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
+
+
+  # Ruby version.
+  # 
+  # @return [Gem::Version]
+  #     
+  attr_reader :version
+
+
+  def initialize version
+    @version = Gem::Version.new version
+  end
+
+
+  def filename
+    @filename ||= "ruby-#{ version }.json.gz"
+  end
+
+
+  def path
+    @path ||= self.class.data_dir.join filename
+  end
+
+
+  # Is the object map present for this {#version}?
+  # 
+  # @return [Boolean]
+  # 
+  def present?
+    path.exist?
+  end
+
+
+  def source
+    @source ||= RubySource.new version
+  end
+
+
+  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
+
+
+  def data reload: false
+    if reload || @data.nil?
+      @data = Zlib::GzipReader.open path do |gz|
+        JSON.load gz.read
+      end
+    end
+
+    @data
+  end
+
+
+  def <=> other
+    version <=> other.version
+  end
+
+
+end # class ObjectMap
+
+
+# /Namespace
+# ========================================================================
+
+end # module LinkStdlib
+end # module YARD

data/lib/yard/link_stdlib/ruby_source.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+# encoding: UTF-8
+
+
+# Requirements
+# ========================================================================
+
+# Stdlib
+# ----------------------------------------------------------------------------
+
+require 'net/http'
+require 'uri'
+
+
+# Namespace
+# ========================================================================
+
+module  YARD
+module  LinkStdlib
+
+
+# Definitions
+# ========================================================================
+
+# Light utility object around a Ruby {Gem::Version} used to download and 
+# extract it's source code to the {LinkStdlib.tmp_dir}.
+# 
+class RubySource
+
+  # Mixins
+  # ========================================================================
+
+  include Comparable
+
+
+  # Class Methods
+  # ============================================================================
+
+  # Ensure the version's source is downloaded and extracted.
+  # 
+  # @example
+  #   YARD::LinkStdlib::RubySource.ensure '2.5.1'
+  # 
+  # @param [Gem::Version || #to_s] version
+  #   The Ruby version you need present.
+  # 
+  # @return [RubySource]
+  #   The utility object instance.
+  # 
+  def self.ensure version
+    new( version ).ensure
+  end # .ensure
+
+
+  def self.list
+    LinkStdlib.tmp_dir.entries.
+      select { |filename|
+        filename.to_s =~ /\Aruby\-\d+\_\d+\_\d+\z/
+      }.
+      map { |filename|
+        new filename.to_s.sub( /\Aruby\-/, '' ).gsub( '_', '.' )
+      }.
+      sort
+  end
+
+
+  # Ruby version.
+  # 
+  # @return [Gem::Version]
+  #     
+  attr_reader :version
+
+  
+  # Construction
+  # ========================================================================
+
+  # Make a new instance for a version.
+  # 
+  # @param [Gem::Version || #to_s] version
+  #   The Ruby version to work with.
+  # 
+  def initialize version
+    @version = Gem::Version.new version
+  end
+
+  
+  # Instance Methods
+  # ========================================================================
+
+  def ruby_style_version
+    @ruby_style_version ||= version.to_s.gsub '.', '_'
+  end
+
+
+  def url
+    @url ||=
+      "https://github.com/ruby/ruby/archive/v#{ ruby_style_version }.tar.gz"
+  end
+
+
+  def tar_filename
+    @tar_filename ||= "ruby-#{ ruby_style_version }.tar.gz"
+  end
+
+
+  def tar_path
+    @tar_path ||= LinkStdlib.tmp_dir.join tar_filename
+  end
+
+
+  def src_path
+    @src_path ||= LinkStdlib.tmp_dir.join "ruby-#{ ruby_style_version }"
+  end
+
+
+  def download force: false
+    if force
+      log.info "FORCING download of Ruby #{ version } tarball..."
+    elsif tar_path.exist?
+      log.info "Ruby #{ version } tarball present."
+      return self
+    else
+      log.info "Downloading Ruby #{ version } tarball..."
+    end
+
+    response = LinkStdlib.http_get url
+    tar_path.open( "wb" ) { |file| file.write response.body }
+
+    self # For chaining
+  end
+
+
+  def extract force: false
+    if force
+      log.info "FORCING extraction of Ruby #{ version } source tarball..."
+    elsif src_path.exist?
+      log.info "Ruby #{ version } source present."
+      return self
+    else
+      log.info "Extracting #{ tar_path } -> #{ src_path }..."
+    end
+
+    LinkStdlib.system! \
+      'tar',  '-x',                           # extract
+              '-f', tar_path.to_s,            # file
+              '-C', LinkStdlib.tmp_dir.to_s   # directory (chdir)
+    
+    log.info "Source for Ruby #{ version } extracted to #{ src_path }."
+
+    self # For chaining
+  end
+
+
+  def ensure
+    if src_path.exist?
+      # Nothing to do, source is already in place
+      log.info "Source for Ruby #{ version } is present."
+      return
+    end
+
+    # Download unless the tar's already there
+    download
+
+    # And we must need to extract it since the src path wasn't there
+    extract
+
+    self # For chaining
+  end
+
+
+  def to_s
+    %{#<YARD::LinkStdlib::RubySource "#{ version }">}
+  end
+
+  def inspect; to_s; end
+
+
+  def <=> other
+    version <=> other.version
+  end
+
+end # class RubySource
+
+
+# /Namespace
+# ========================================================================
+
+end # module LinkStdlib
+end # module YARD