yard-link_stdlib 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3334c95ebde62bc497aaab158361d28cb88bcb3e
-  data.tar.gz: 04117641eaf696120948d32d3e23354308e33d77
+  metadata.gz: 35e1ca61be63e6ca2ec8b75762cf24cb2139e375
+  data.tar.gz: c5be9c26529b4fea0ebb8e32f84603090bf2b193
 SHA512:
-  metadata.gz: f5c660eb08a0a7656e305771d7603788b8396bec4221ee2c3030137e7ad7cfbef4682ee3a481fe62b84b3a0cd8b6972abfdc82d0fda9f39ea9ed778f161eb113
-  data.tar.gz: 227aa9d466ab557c835d84c581d205b79dbe993dd62fea51c868e03b0b9a8f60418944257ea20003717b060fb2fd56e2ad2dcd4e5a14a2764c0012a72275d8cd
+  metadata.gz: 374248e1ffd21df5717efc40de3dccbd7bc0ae62d804ce4acb36f84776cfa9293ea620547954d497c407ec91e040d408ca550dd831d5a375d6fcf4e2c6aca1e3
+  data.tar.gz: f4638c958009fbeccf3c6fedbdcac2ba14af45d21286ac6ac0988c6b94e093c1b7db7983e5a067460b1b2e8e4f96fab935f8f1615f0e0884e36b96b0abc2302d

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/lib/yard/cli/link_stdlib.rb

@@ -15,7 +15,12 @@ require 'yard'
 
 ### Project / Package ###
 
-require 'yard/link_stdlib/ruby_source'
+#### Sub-Commands ####
+require_relative './link_stdlib/add'
+require_relative './link_stdlib/help'
+require_relative './link_stdlib/list'
+require_relative './link_stdlib/search'
+require_relative './link_stdlib/url'
 
 
 # Namespace
@@ -28,357 +33,29 @@ 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.
+# Top-level {YARD::CLI::Command} for the `yard-link_stdlib` plugin. Added under 
+# the name `stdlib` (see {YARD::LinkStdlib.install!}).
+# 
+# Simply a router to the sub-commands. Like {YARD::CLI::CommandParser}, which
+# handles routing for `yard`, but is not really re-usable. In addition, this 
+# class handles "-" → "_" conversion in sub-command names, since we have 
+# multi-word commands.
+# 
 class LinkStdlib < Command
-
-  # Sub-commands
-  # ============================================================================
-
-  class List < Command
-    include CommandHelper
-    
-    DESCRIPTION = "List Ruby versions"
-    USAGE = "yard stdlib list"
-
-    def run *args
-      
-      
-      log.puts \
-        YARD::LinkStdlib::ObjectMap.
-          all.
-          map { |om| om.version.to_s }.
-          join( "\n" )
-    end
-  end # class List
-
-
-  class Add < Command
-    
-    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
-    
-  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
-      # Default format is `:plain`
-      opts[ :format ] = :plain
-      
-      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$'
-            
-            3.  Print results in serialized formats.
-                
-                All `#to_s` instance methods in JSON:
-                
-                    $ yard stdlib search --format=json '#to_s$'
-                
-                Supports a short `-f` flag and first-letter formats too.
-                
-                Instance methods of {Array} in YAML:
-                
-                    $ yard stdlib search -f y '^Array#'
-        END
-        
-        add_version_opt op
-        
-        op.on(  '-u', '--urls',
-                %(Print doc URLs along with names)
-        ) { |urls| opts[ :urls ] = !!urls }
-        
-        op.on(  '-f FORMAT', '--format=FORMAT',
-                %(Specify print format: (p)lain, (j)son or (y)aml)
-        ) { |format|
-          opts[ :format ] = \
-            case format.downcase
-            when 'p', 'plain'
-              :plain
-            when 'j', 'json'
-              :json
-            when 'y', 'yaml'
-              :yaml
-            else
-              log.fatal \
-                %(Unknown format - expected "plain", "json" or "yaml"; ) +
-                %(given #{ format.inspect })
-              exit false
-            end
-        }
-        
-      }.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|
-        begin
-          Regexp.new arg
-        rescue RegexpError => error
-          Regexp.new \
-            Regexp.escape( YARD::LinkStdlib.normalize_name( arg ) )
-        end
-      }
-      
-      log.debug "Terms:\n  " + terms.map( &:to_s ).join( "\n  " )
-      
-      names = YARD::LinkStdlib.grep *terms
-      
-      results = \
-        if opts[ :urls ]
-          names.each_with_object( {} ) { |name, hash|
-            hash[ name ] = YARD::LinkStdlib::ObjectMap.current.url_for name
-          }
-        else
-          names
-        end
-      
-      case opts[ :format ]
-      when :plain
-        results.each do |entry|
-          if entry.is_a? ::Array
-            log.puts "#{ entry[0] } <#{ entry[ 1 ]}>"
-          else
-            log.puts entry
-          end
-        end
-      when :json
-        require 'json'
-        log.puts JSON.pretty_generate( results )
-      when :yaml
-        require 'yaml'
-        log.puts YAML.dump( results )
-      end
-      
-      exit true
-    end
-  end # class Search
-
-
-  class Help < Command
-    
-    include CommandHelper
-    
-    DESCRIPTION = "Show this message"
-
-    def run
-      commands = LinkStdlib.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
   
+  @commands = SymbolHash[
+    help: Help,
+    list: List,
+    add: Add,
+    url: URL,
+    search: Search,
+  ]
   
   # Singleton Methods
   # ==========================================================================
   
   def self.commands
-    {
-      help: Help,
-      list: List,
-      add: Add,
-      url: URL,
-      search: Search,
-    }
+    @commands
   end
   
   

data/lib/yard/cli/link_stdlib/add.rb

@@ -0,0 +1,70 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Stdlib ###
+
+require 'optparse'
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+require_relative './command_helper'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+class Add < Command
+  
+  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
+  
+end # class Add
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

data/lib/yard/cli/link_stdlib/command_helper.rb

@@ -0,0 +1,103 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+# `.make_missing`, `.set` from {YARD::LinkStdlib::RubySource}
+require 'yard/link_stdlib/ruby_source'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+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
+    
+    # Call {YARD::CLI::Command#common_options}, which adds file loading, plugin
+    # loading, logging, YARD version and help options
+    common_options( op )
+  end
+  
+  def add_version_opt op
+    # **DON'T** make missing versions by default here!
+    YARD::LinkStdlib::RubySource.make_missing = false
+    
+    op.on(
+      '-R VERSION',
+      '--ruby-version=VERSION',
+      %(Set Ruby version)
+    ) { |ruby_version|
+      YARD::LinkStdlib::RubyVersion.set 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
+    }
+  end
+  
+end # CommandHelper
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

data/lib/yard/cli/link_stdlib/help.rb

@@ -0,0 +1,72 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Stdlib ###
+
+require 'optparse'
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+require_relative './command_helper'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+class Help < Command
+    
+    include CommandHelper
+    
+    USAGE = "yard stdlib help [OTHER_OPTIONS]"
+    DESCRIPTION = "Show this message"
+
+    def run *args
+      OptionParser.new { |op|
+        add_header op
+      }.parse! args
+      
+      commands = LinkStdlib.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
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

data/lib/yard/cli/link_stdlib/list.rb

@@ -0,0 +1,59 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Stdlib ###
+
+require 'optparse'
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+require_relative './command_helper'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+class List < Command
+  include CommandHelper
+  
+  DESCRIPTION = "List Ruby versions"
+  USAGE = "yard stdlib list"
+
+  def run *args
+    OptionParser.new { |op|
+      add_header op
+    }.parse! args
+    
+    check_args! args, 0
+    
+    log.puts \
+      YARD::LinkStdlib::ObjectMap.
+        all.
+        map { |om| om.version.to_s }.
+        join( "\n" )
+  end
+end # class List
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

data/lib/yard/cli/link_stdlib/search.rb

@@ -0,0 +1,156 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Stdlib ###
+
+require 'optparse'
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+require_relative './command_helper'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+# 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
+    # Default format is `:plain`
+    opts[ :format ] = :plain
+    
+    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$'
+          
+          3.  Print results in serialized formats.
+              
+              All `#to_s` instance methods in JSON:
+              
+                  $ yard stdlib search --format=json '#to_s$'
+              
+              Supports a short `-f` flag and first-letter formats too.
+              
+              Instance methods of {Array} in YAML:
+              
+                  $ yard stdlib search -f y '^Array#'
+      END
+      
+      add_version_opt op
+      
+      op.on(  '-u', '--urls',
+              %(Print doc URLs along with names)
+      ) { |urls| opts[ :urls ] = !!urls }
+      
+      op.on(  '-f FORMAT', '--format=FORMAT',
+              %(Specify print format: (p)lain, (j)son or (y)aml)
+      ) { |format|
+        opts[ :format ] = \
+          case format.downcase
+          when 'p', 'plain'
+            :plain
+          when 'j', 'json'
+            :json
+          when 'y', 'yaml'
+            :yaml
+          else
+            log.fatal \
+              %(Unknown format - expected "plain", "json" or "yaml"; ) +
+              %(given #{ format.inspect })
+            exit false
+          end
+      }
+      
+    }.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|
+      begin
+        Regexp.new arg
+      rescue RegexpError => error
+        Regexp.new \
+          Regexp.escape( YARD::LinkStdlib.normalize_name( arg ) )
+      end
+    }
+    
+    log.debug "Terms:\n  " + terms.map( &:to_s ).join( "\n  " )
+    
+    names = YARD::LinkStdlib.grep *terms
+    
+    results = \
+      if opts[ :urls ]
+        names.each_with_object( {} ) { |name, hash|
+          hash[ name ] = YARD::LinkStdlib::ObjectMap.current.url_for name
+        }
+      else
+        names
+      end
+    
+    case opts[ :format ]
+    when :plain
+      results.each do |entry|
+        if entry.is_a? ::Array
+          log.puts "#{ entry[0] } <#{ entry[ 1 ]}>"
+        else
+          log.puts entry
+        end
+      end
+    when :json
+      require 'json'
+      log.puts JSON.pretty_generate( results )
+    when :yaml
+      require 'yaml'
+      log.puts YAML.dump( results )
+    end
+    
+    exit true
+  end
+end # class Search
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

data/lib/yard/cli/link_stdlib/url.rb

@@ -0,0 +1,65 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+### Stdlib ###
+
+require 'optparse'
+
+### Deps ###
+
+# We need {YARD::CLI::Command}
+require 'yard'
+
+### Project / Package ###
+
+require_relative './command_helper'
+
+
+# Namespace
+# =======================================================================
+
+module  YARD
+module  CLI
+class   LinkStdlib < Command
+
+
+# Definitions
+# =======================================================================
+
+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
+
+
+# /Namespace
+# =======================================================================
+
+end # class  LinkStdlib
+end # module CLI
+end # module YARD

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-link_stdlib
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-20 00:00:00.000000000 Z
+date: 2019-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -167,6 +167,12 @@ files:
 - bin/make_map.rb
 - lib/yard-link_stdlib.rb
 - lib/yard/cli/link_stdlib.rb
+- lib/yard/cli/link_stdlib/add.rb
+- lib/yard/cli/link_stdlib/command_helper.rb
+- lib/yard/cli/link_stdlib/help.rb
+- lib/yard/cli/link_stdlib/list.rb
+- lib/yard/cli/link_stdlib/search.rb
+- lib/yard/cli/link_stdlib/url.rb
 - lib/yard/link_stdlib.rb
 - lib/yard/link_stdlib/html_helper.rb
 - lib/yard/link_stdlib/object_map.rb