yard-link_stdlib 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a59fb5f579b3ba52d91480842cba718088aabf7
-  data.tar.gz: 719132fdcb142763240354613603ade4a7c1422d
+  metadata.gz: 7966efdc84cb97c6137cbb70585abb20633f388b
+  data.tar.gz: bcdc1e6b09e76868433f0a3165a69fa1972d940b
 SHA512:
-  metadata.gz: df1320327489dbe4bb9f61420922a85aa73a2a317d54c7e5311b5c42e43b5f031a775d62816dbfb5e5e5c8b23f680081aac9965fc8a25c1f575b31189674bc34
-  data.tar.gz: 83e3a17de615b41176dc0aab4ed5bd93e851d84a050f7ea91ce30af17bee4df5f5f8094b151b2bc74a517a4cdc0f60858204cc2d820a175bc0a654b36ee41c70
+  metadata.gz: 58df15ecd9f973b793b7578c3b8bc566de595f8cd1c6de7d80d11ef613e8f562fde34d2808361c8471e105d5ae05e4dd80c8a80e58608ce1463d4209d9ab1d94
+  data.tar.gz: 81249ca138789654b2027bd81ff9936499da5baaef927a17cafc833d91de661fc1b08164daf0cb8d3ecba2af0f7f4a34755d75f33304e31eccb4dc0531efb1fb

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.1.1

data/bin/make_map.rb

@@ -1,17 +1,38 @@
 #!/usr/bin/env ruby
 
+##############################################################################
+# Make a {YARD::LinkStdlib::ObjectMap} Data File
+# ============================================================================
+#
+# Running this script is what creates the `//maps/ruby-M.m.p.json.gz` data files
+# index object names to their relative URL path in the generated documentation,
+# which is in turn how the plugin generates document URLs.
+#
+# Coming back now (2019.03.09) I don't remember a ton of how ro why things got
+# this way (comment your code, kids!). From the commit history, I can see that
+# this script came over from initial work somewhere in `nrser/nrser.rb`.
+#
+# I think I remember this needing to run in a separate child process (versus
+# just in the main `yard` one), but I don't recall why.
+#
+# It might have just been to try to emulate `rdoc` as much as possible, and
+# might no longer be needed given present knowledge and understanding, but I
+# think I'm just going to leave it for now, because it does work, and to fuck
+# with it I would probably want some sort of testing set up to check I'm not
+# breaking things, and that's a whole 'nother thing...
+#
+##############################################################################
+
 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
@@ -24,6 +45,10 @@ class RDoc::RDoc
       @options = load_options
       @options.parse options
     end
+    
+    # We want **all** of the names available, so force the highest visibility
+    # level.
+    @options.visibility = :nodoc
 
     if @options.pipe then
       handle_pipe
@@ -55,18 +80,22 @@ class RDoc::RDoc
     gen_klass = @options.generator
 
     @generator = gen_klass.new @store, @options
-
+    
+    # What we *don't* do:
     # generate
+    
     nil
-  end
-end
+  end # #almost_document
+  
+end # class RDoc::RDoc
+
 
 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 }"
+  puts "src: #{ src }"
+  puts "dest: #{ dest }"
 
   # 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
@@ -85,18 +114,26 @@ def main 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
+    # if mod.full_name == 'Gem::Specification'
+    #   require 'pry'
+    #   Pry.config.should_load_rc = false
+    #   binding.pry
+    # end
+    
+    [
+      mod,
+      mod.constants,
+      mod.class_attributes,
+      mod.class_method_list,
+      mod.instance_attributes,
+      mod.instance_method_list,
+    ].flatten.each { |entry|
+      map[ entry.full_name ] = entry.path
+    }
+    
   end
 
-  FileUtils.mkdir_p dest.dirname unless dest.dirname.exist?
+  FileUtils.mkdir_p( dest.dirname ) unless dest.dirname.exist?
 
   Zlib::GzipWriter.open dest do |gz|
     gz.write JSON.pretty_generate( map )

data/lib/yard/cli/link_stdlib.rb

@@ -4,17 +4,16 @@
 # Requirements
 # =======================================================================
 
-# Stdlib
-# -----------------------------------------------------------------------
+### Stdlib ###
 
-# Deps
-# -----------------------------------------------------------------------
+require 'optparse'
+
+### Deps ###
 
 # We need {YARD::CLI::Command}
 require 'yard'
 
-# Project / Package
-# -----------------------------------------------------------------------
+### Project / Package ###
 
 require 'yard/link_stdlib/ruby_source'
 
@@ -29,77 +28,314 @@ module  CLI
 # Definitions
 # =======================================================================
 
+
+class OptionParser < ::OptionParser
+  def after_parse_block
+    @after_parse_block ||= []
+  end
+  
+  def after_parse &block
+    after_parse_block << block
+  end
+
+  def parse! *args
+    super( *args ).tap { after_parse_block.each &:call }
+  end
+end
+
+
+module CommandHelper
+  
+  def description
+    self.class::DESCRIPTION
+  end
+  
+  
+  def usage
+    self.class::USAGE
+  end
+  
+  
+  def check_args! args, count
+    if args.length < count
+      log.error "Too few args! Expected #{ count }, given #{ args.length }"
+      exit false
+    elsif args.length > count
+      log.error "Too many args! Expected #{ count }, given #{ args.length }"
+      exit false
+    end
+    
+    if args.length == 1 then args[ 0 ] else args end
+  end
+
+  
+  def opts
+    @opts ||= {}
+  end
+  
+
+  def add_header op, text = nil
+    op.banner = description
+    op.separator ''
+    op.separator 'Usage:'
+    op.separator ''
+    op.separator "    #{ usage }"
+    op.separator ''
+    unless text.nil?
+      text.lines.each { |line| op.separator line }
+    end
+    op.separator ''
+    op.separator 'Options:'
+    
+    op.on_tail( '-q', '--quiet', 'Show no warnings.' ) {
+      log.level = Logger::ERROR
+    }
+    
+    op.on_tail( '--verbose', 'Show more information.') {
+      log.level = Logger::INFO
+    }
+    
+    op.on_tail( '--debug', 'Show debugging information.' ) {
+      log.level = Logger::DEBUG
+    }
+    
+    op.on_tail( '--backtrace', 'Show stack traces' ) {
+      log.show_backtraces = true
+    }
+    
+    op.on_tail( '-h', '--help', %(You're looking at it!) ) {
+      log.puts op
+      exit true
+    }
+  end
+  
+  def add_version_opt op
+    # **DON'T** make missing versions by default here!
+    YARD::LinkStdlib::RubySource.make_missing = false
+    
+    op.on(
+      '-v VERSION',
+      '--ruby-version=VERSION',
+      %(Set Ruby version)
+    ) { |ruby_version|
+      YARD::LinkStdlib::RubyVersion.set ruby_version
+      # opts[ :ruby_version ] = ruby_version
+    }
+    
+    op.on(
+      '--make-missing',
+      %(Download and make an object map if the Ruby version is not present)
+    ) { |make_missing|
+      YARD::LinkStdlib::RubySource.make_missing = make_missing
+      # opts[ :make_missing ] = make_missing
+    }
+  end
+  
+end # CommandHelper
+
+
 # @todo document LinkStdlib class.
 class LinkStdlib < Command
 
-  # Subcommands
+  # Sub-commands
   # ============================================================================
 
   class List < Command
-    def description
-      "List Ruby versions"
-    end
+    include CommandHelper
+    
+    DESCRIPTION = "List Ruby versions"
+    USAGE = "yard stdlib list"
 
-    def run
+    def run *args
+      
+      
       log.puts \
         YARD::LinkStdlib::ObjectMap.
-          list.
+          all.
           map { |om| om.version.to_s }.
           join( "\n" )
     end
-  end
+  end # class List
 
 
   class Add < Command
-    def description
-      "Download version source and build object map"
+    
+    include CommandHelper
+    
+    DESCRIPTION = "Download version source and build object map"
+    USAGE = "yard stdlib add [OPTIONS] RUBY_VERSION"
+
+    def run *args
+      # Want to see what's going on by default here...
+      log.level = Logger::INFO
+      
+      opts[ :force ] = false
+    
+      OptionParser.new { |op|
+        add_header op
+        
+        op.on( '-f', '--force',
+                %(Force building of map data when already present)
+        ) { |force| opts[ :force ] = force }
+        
+      }.parse! args
+      
+      args.each do |version|    
+        log.info "Adding object map for Ruby #{ version }..."
+        YARD::LinkStdlib::ObjectMap.add version, force: opts[ :force ]
+      end
+      
+      exit true
     end
-
-    def run version
-      log.puts "Adding object map for Ruby #{ version }..."
-      YARD::LinkStdlib::ObjectMap.new( version ).make
+    
+  end # class Add
+  
+  
+  class URL < Command
+    
+    include CommandHelper
+    
+    DESCRIPTION = "Print the online doc URL for a stdlib name"
+    USAGE = "yard stdlib url [OPTIONS] NAME"
+    
+    def run *args
+      OptionParser.new { |op|
+        add_header op
+        add_version_opt op
+      }.parse! args
+      
+      name = check_args! args, 1
+      
+      url = YARD::LinkStdlib::ObjectMap.current.url_for name
+      
+      if url.nil?
+        $stderr.puts "Name not found: #{ name.inspect }"
+        exit false
+      end
+      
+      puts url
+      exit true
     end
   end
+  
+  
+  # Hooks into {YARD::LinkStdlib::ObjectMap#grep} to search for names using 
+  # regular expressions.
+  # 
+  class Search < Command
+    
+    include CommandHelper
+    
+    DESCRIPTION = "Find stdlib names that match Regexp patterns"
+    USAGE = "yard stdlib search [OPTIONS] TERMS..."
+    
+    def run *args
+      OptionParser.new { |op|
+        add_header op, <<~END
+          Examples:
+          
+            1.  {Pathname} instance methods
+                
+                yard stdlib search '^Pathname#'
+          
+            2. All `#to_s` methods
+                
+                yard stdlib search '#to_s$'
+        END
+        
+        add_version_opt op
+        
+        op.on(  '-u', '--urls',
+                %(Print doc URLs along with names)
+        ) { |urls| opts[ :urls ] = urls }
+        
+      }.parse! args
+      
+      if args.empty?
+        YARD::LinkStdlib::ObjectMap.
+          current.
+          names.
+          sort_by( &:downcase ).
+          each { |key| log.puts key }
+        exit true
+      end
+      
+      terms = args.map { |arg| Regexp.new arg }
+      
+      log.debug "Terms:\n  " + terms.map( &:to_s ).join( "\n  " )
+      
+      names = YARD::LinkStdlib.grep *terms
+      
+      names.each { |name|
+        line = \
+          if opts[ :urls ]
+            "#{ name } <#{ YARD::LinkStdlib::ObjectMap.current.url_for name }>"
+          else
+            name
+          end
+        log.puts line
+      }
+      
+      exit true
+    end
+  end # class Search
 
 
   class Help < Command
-    def description
-      "Show this message"
-    end
+    
+    include CommandHelper
+    
+    DESCRIPTION = "Show this message"
 
     def run
       commands = LinkStdlib.commands
-      log.puts "Usage: yard stdlib COMMAND... [OPTIONS] [ARGS]"
-      log.puts
-      log.puts "Commands:"
+      log.puts <<~END
+        yard-link_stdlib provides linking to online Ruby docs for standard 
+        library code objects.
+        
+        Usage:
+        
+            yard stdlib COMMAND... [OPTIONS] [ARGS]
+        
+        Commands:
+        
+      END
       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
+      log.puts
     end
   end
-
   
-  # Instance Methods
-  # ========================================================================
-
-  def description
-    "Mange Ruby stdlib linking"
-  end
-
-
+  
+  # Singleton Methods
+  # ==========================================================================
+  
   def self.commands
     {
       help: Help,
       list: List,
       add: Add,
+      url: URL,
+      search: Search,
     }
   end
   
+  
+  # Instance Methods
+  # ========================================================================
+
+  def description
+    "Mange Ruby stdlib linking"
+  end
+  
 
   def run *args
+    # log.level = Logger::INFO
+    
     target = self.class.commands
 
     args = [ 'help' ] if args.empty?
@@ -118,25 +354,6 @@ class LinkStdlib < Command
   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
 
 

data/lib/yard/link_stdlib/html_helper.rb

@@ -17,7 +17,6 @@ require 'yard'
 # Project / Package
 # ------------------------------------------------------------------------
 
-require_relative './dump'
 require_relative './ruby_version'
 require_relative './object_map'
 
@@ -89,29 +88,16 @@ module HtmlHelper
       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 ] )
+    # if ( path = ObjectMap.current.data[ stdlib_key ] )
+    if (url = ObjectMap.current.url_for super_link)
       LinkStdlib.dump "Matched stdlib link!",
-        path: path,
-        key: key,
-        stdlib_key: stdlib_key
-      
-      version = LinkStdlib::RubyVersion.minor
+        name: super_link,
+        url: url
       
-      [
-        %{<a href="https://docs.ruby-lang.org/en/#{ version }/#{ path }">},
-        key,
-        %{</a>},
-      ].join ''
+      # NOTE  `url` is **not** escaped because it may contains '#' followed
+      #       by a fragment, and that needs to be preserved. At this point,
+      #       I'm just assuming it's ready for use as-is.
+      %(<a href="#{ url }">#{ CGI.escapeHTML super_link }</a>)
 
     else
       LinkStdlib.dump "Got nada.",