yard-link_stdlib 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2a59fb5f579b3ba52d91480842cba718088aabf7
+  data.tar.gz: 719132fdcb142763240354613603ade4a7c1422d
+SHA512:
+  metadata.gz: df1320327489dbe4bb9f61420922a85aa73a2a317d54c7e5311b5c42e43b5f031a775d62816dbfb5e5e5c8b23f680081aac9965fc8a25c1f575b31189674bc34
+  data.tar.gz: 83e3a17de615b41176dc0aab4ed5bd93e851d84a050f7ea91ce30af17bee4df5f5f8094b151b2bc74a517a4cdc0f60858204cc2d820a175bc0a654b36ee41c70

data/LICENSE.txt

@@ -0,0 +1,28 @@
+The BSD License ('Cause we West Coast)
+
+Copyright Two-Thousand Eighteen by NRSER A.K.A. Neil R. Souza
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/NAME

@@ -0,0 +1 @@
+yard-link_stdlib

data/README.md

@@ -0,0 +1,39 @@
+# YARD::LinkStdlib
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/yard/link_stdlib`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yard-link_stdlib'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yard-link_stdlib
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yard-link_stdlib.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/make_map.rb

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+require 'fileutils'
+require 'zlib'
+
+require 'rdoc/rdoc'
+
+# Get paths in order - we want to be in the Ruby repo checkout
+GEM_ROOT = Pathname.new( __dir__ ).join( '..' ).expand_path
+# REPO = GEM_ROOT.join 'tmp', 'ruby'
+# REPO = GEM_ROOT.join 'tmp', 'ruby-2_5_1'
+
+class RDoc::RDoc
+  # Pretty much a copy of `RDoc::RDoc#document`, just with the `#generate` step
+  # commented-out.
+  def almost_document options = ARGV
+    self.store = RDoc::Store.new
+
+    if RDoc::Options === options then
+      @options = options
+      @options.finish
+    else
+      @options = load_options
+      @options.parse options
+    end
+
+    if @options.pipe then
+      handle_pipe
+      exit
+    end
+
+    unless @options.coverage_report then
+      @last_modified = setup_output_dir @options.op_dir, @options.force_update
+    end
+
+    @store.encoding = @options.encoding
+    @store.dry_run  = @options.dry_run
+    @store.main     = @options.main_page
+    @store.title    = @options.title
+    @store.path     = @options.op_dir
+
+    @start_time = Time.now
+
+    @store.load_cache
+
+    file_info = parse_files @options.files
+
+    @options.default_title = "RDoc Documentation"
+
+    @store.complete @options.visibility
+
+    @stats.coverage_level = @options.coverage_report
+
+    gen_klass = @options.generator
+
+    @generator = gen_klass.new @store, @options
+
+    # generate
+    nil
+  end
+end
+
+def main args
+  src = Pathname.new( args.shift ).expand_path
+  dest = Pathname.new( args.shift ).expand_path
+  
+  puts "src: #{ src.inspect }"
+  puts "dest: #{ dest.inspect }"
+
+  # RDoc needs this output dir arg in `ARGV` or it will bail out with an error
+  # due to `//doc` existing, even though we don't ever actually write to any of
+  # it.
+  unless args.include? '--op'
+    args << '--op'
+    args << '/tmp/not_actually_used'
+  end
+
+  Dir.chdir src
+
+  rd = RDoc::RDoc.new
+
+  rd.almost_document args
+
+  map = {}
+
+  rd.store.all_classes_and_modules.each do |mod|
+    map[mod.full_name] = mod.path
+
+    mod.class_method_list.each do |class_method|
+      map[class_method.full_name] = class_method.path
+    end
+
+    mod.instance_method_list.each do |instance_method|
+      map[instance_method.full_name] = instance_method.path
+    end
+  end
+
+  FileUtils.mkdir_p dest.dirname unless dest.dirname.exist?
+
+  Zlib::GzipWriter.open dest do |gz|
+    gz.write JSON.pretty_generate( map )
+  end
+end
+
+# Kickoff!
+main( ARGV ) if __FILE__ == $0

data/lib/yard-link_stdlib.rb

@@ -0,0 +1,21 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+##############################################################################
+# Plugin Entry Point for YARD
+# ============================================================================
+# 
+# While the library itself lives in the `YARD::StdLib` namespaces under the
+# usual directory structure of `//lib/yard/link_stdlib`, when requiring
+# plugins YARD will reach for `yard-link_stdlib`, basically just calling
+# 
+#     require 'yard-link_stdlib'
+# 
+# which leads it here. This is nice, because it lets us use the kind-of funkily
+# 
+##############################################################################
+
+
+require_relative "./yard/link_stdlib"
+
+YARD::LinkStdlib.install!

data/lib/yard/cli/link_stdlib.rb

@@ -0,0 +1,147 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'yard/link_stdlib/ruby_source'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+
+
+# Definitions
+# =======================================================================
+
+# @todo document LinkStdlib class.
+class LinkStdlib < Command
+
+  # Subcommands
+  # ============================================================================
+
+  class List < Command
+    def description
+      "List Ruby versions"
+    end
+
+    def run
+      log.puts \
+        YARD::LinkStdlib::ObjectMap.
+          list.
+          map { |om| om.version.to_s }.
+          join( "\n" )
+    end
+  end
+
+
+  class Add < Command
+    def description
+      "Download version source and build object map"
+    end
+
+    def run version
+      log.puts "Adding object map for Ruby #{ version }..."
+      YARD::LinkStdlib::ObjectMap.new( version ).make
+    end
+  end
+
+
+  class Help < Command
+    def description
+      "Show this message"
+    end
+
+    def run
+      commands = LinkStdlib.commands
+      log.puts "Usage: yard stdlib COMMAND... [OPTIONS] [ARGS]"
+      log.puts
+      log.puts "Commands:"
+      commands.keys.sort_by(&:to_s).each do |command_name|
+        command_class = commands[command_name]
+        next unless command_class < Command
+        command = command_class.new
+        log.puts "%-8s %s" % [command_name, command.description]
+      end
+    end
+  end
+
+  
+  # Instance Methods
+  # ========================================================================
+
+  def description
+    "Mange Ruby stdlib linking"
+  end
+
+
+  def self.commands
+    {
+      help: Help,
+      list: List,
+      add: Add,
+    }
+  end
+  
+
+  def run *args
+    target = self.class.commands
+
+    args = [ 'help' ] if args.empty?
+
+    while target.is_a? Hash
+      key = args[0].gsub( '-', '_' ).to_sym
+      if target.key? key
+        target = target[key]
+        args.shift
+      else
+        raise "Bad command name: #{ args[0] }"
+      end
+    end
+
+    target.run( *args )
+  end
+
+  
+  protected
+  # ========================================================================
+    
+    # @todo Document respond method.
+    # 
+    # @param [type] arg_name
+    #   @todo Add name param description.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def respond response
+      log.puts response unless response.nil?
+      exit true
+    end # #respond
+
+  public # end protected ***************************************************
+
+  
+end # class LinkStdlib
+
+
+# /Namespace
+# =======================================================================
+
+end # module CLI
+end # module YARD

data/lib/yard/link_stdlib.rb

@@ -0,0 +1,212 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+require 'shellwords'
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require_relative "./cli/link_stdlib"
+require_relative "./link_stdlib/version"
+require_relative "./link_stdlib/html_helper"
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  LinkStdlib
+
+
+# Definitions
+# =======================================================================
+
+# Constants
+# ----------------------------------------------------------------------------
+
+# Available helper modules by their format (as found in `options.format`).
+# 
+# We only cover `:html` for the moment, but may add more in the future.
+# 
+# @return [Hash<Symbol, Module>]
+# 
+HELPERS_BY_FORMAT = {
+  html: HtmlHelper,
+}.freeze
+
+
+# The {Proc} that we add to {YARD::Templates::Template.extra_includes} on
+# {.install!}. The proc accepts template options and responds with the helper
+# module corresponding to the format (if any - right now we only handle 
+# `:html`).
+# 
+# We want this to be a constant so we can tell if it's there and
+# avoid ever double-adding it.
+# 
+# @return [Proc<YARD::Templates::TemplateOptions -> Module?>]
+# 
+HELPER_FOR_OPTIONS = proc { |options|
+  HELPERS_BY_FORMAT[ options.format ]
+}.freeze
+
+
+# Add the {HELPER_FOR_OPTIONS} {Proc} to
+# {YARD::Templates::Template.extra_includes} (if it's not there already).
+# 
+# @see https://www.rubydoc.info/gems/yard/YARD/Templates/Template#extra_includes-class_method
+# 
+# @return [nil]
+# 
+def self.install!
+  # NOTE  Due to YARD start-up order, this happens *before* log level is set,
+  #       so the `--debug` CLI switch won't help see it... don't know a way to
+  #       at the moment.
+  log.debug "Installing `yard-link_stdlib` plugin..."
+
+  unless YARD::Templates::Template.extra_includes.include? HELPER_FOR_OPTIONS
+    YARD::Templates::Template.extra_includes << HELPER_FOR_OPTIONS
+  end
+
+  YARD::CLI::CommandParser.commands[:stdlib] ||= YARD::CLI::LinkStdlib
+
+  nil
+end # .install!
+
+
+# General Utilities
+# ----------------------------------------------------------------------------
+
+# @param [Symbol | #to_s] value
+#   Either an object whose string representation expands to a path to an
+#   existing directory, or one of the following symbols:
+#   
+#   1.  `:system`, `:global` - `/tmp/yard-link_stdlib`
+#   2.  
+# 
+# @return [Pathname]
+#   The assigned path.
+# 
+def self.tmp_dir= value
+  @tmp_dir = case value
+  when :system, :global
+    Pathname.new '/tmp/yard-link_stdlib'
+  when :user
+    Pathname.new( '~/tmp/yard-link_stdlib' ).expand_path
+  when :gem, :install
+    ROOT.join 'tmp'
+  when :project
+    Pathname.getwd.join 'tmp', 'yard-link_stdlib'
+  else
+    dir = Pathname.new( value.to_s ).expand_path
+
+    unless dir.directory?
+      raise ArgumentError,
+        "When assigning a custom tmp_dir path it must be an existing " +
+        "directory, received #{ value.to_s.inspect }"
+    end
+  end
+
+  FileUtils.mkdir_p @tmp_dir unless @tmp_dir.exist?
+
+  @tmp_dir
+end
+
+
+# Get where to put temporary shit, most Ruby source code that's been downloaded
+# to generate the link maps from.
+# 
+# @return [Pathname]
+# 
+def self.tmp_dir &block
+  if @tmp_dir.nil?
+    self.tmp_dir = repo? ? :gem : :user
+  end
+
+  if block
+    Dir.chdir @tmp_dir, &block
+  else
+    @tmp_dir
+  end
+end
+
+
+# Run a {Kernel.system}, raising if it fails.
+# 
+# @param [Array] *args
+#   See {Kernel.system}.
+# 
+# @return [true]
+# 
+# @raise [SystemCallError]
+#   If the command fails.
+# 
+def self.system! *args
+  opts  = args[-1].is_a?( Hash )  ? args.pop : {}
+  env   = args[0].is_a?( Hash )   ? args.shift : {}
+
+  log.info [
+    "Making system call:",
+    "\t#{ Shellwords.join args }",
+    ( opts.empty? ? nil : "\toptions: #{ opts.inspect }" ),
+    ( env.empty? ? nil : "\tenv: #{ env.inspect }" ),
+  ].compact.join( "\n" )
+
+  Kernel.system( *args ).tap { |success|
+    unless success
+      raise SystemCallError.new \
+        %{ Code #{ $?.exitstatus } error executing #{ args.inspect } },
+        $?.exitstatus
+    end
+  }
+end
+
+
+# Make a `GET` request. Follows redirects. Handles SSL.
+# 
+# @param [String] url
+#   What ya want.
+# 
+# @param [Integer] redirect_limit
+#   Max number of redirects to follow before it gives up.
+# 
+# @return [Net::HTTPResponse]
+#   The first successful response that's not a redirect.
+# 
+# @raise [Net::HTTPError]
+#   If there was an HTTP error.
+# 
+# @raise 
+# 
+def self.http_get url, redirect_limit = 5
+  raise "Too many HTTP redirects" if redirect_limit < 0
+
+  uri = URI url
+  request = Net::HTTP::Get.new uri.path
+  response = Net::HTTP.start(
+    uri.host,
+    uri.port,
+    use_ssl: uri.scheme == 'https',
+  ) { |http| http.request request }
+  
+  case response
+  when Net::HTTPSuccess
+    response
+  when Net::HTTPRedirection
+    http_get response['location'], redirect_limit - 1
+  else
+    response.error!
+  end 
+end
+
+
+# /Namespace
+# =======================================================================
+
+end # module LinkStdlib
+end # module YARD