yard_ghurt 1.2.1 → 1.2.2

data/lib/yard_ghurt/anchor_links.rb

@@ -3,67 +3,29 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'set'
 require 'uri'
 
 module YardGhurt
-  ###
   # A "database" of anchor links specific to GitHub Flavored Markdown (GFM) & YARDoc.
   #
   # You can use this by itself to view what anchor IDs would be generated:
-  #   al = YardGhurt::AnchorLinks.new()
-  #
-  #   puts al.to_github_anchor_id('This is a test!')
-  #   puts al.to_yard_anchor_id('This is a test!')
+  #   al = YardGhurt::AnchorLinks.new
   #
-  #   # Output:
-  #   # ---
-  #   # this-is-a-test
-  #   # This_is_a_test_
+  #   puts al.to_github_anchor_id('This is a test!') #=> this-is-a-test
+  #   puts al.to_yard_anchor_id('This is a test!')   #=> This_is_a_test_
   #
   # Be aware that YARDoc depends on a common number that will be incremented for all duplicates,
-  # while GFM's number is only local to each specific duplicate:
-  #   al = YardGhurt::AnchorLinks.new()
-  #   name = 'This is a test!'
-  #
-  #   puts al.to_yard_anchor_id(name)   # This_is_a_test_
-  #   puts al.to_yard_anchor_id(name)   # This_is_a_test_
-  #
-  #   puts al.to_github_anchor_id(name) # this-is-a-test
-  #   puts al.to_github_anchor_id(name) # this-is-a-test
-  #
-  #   al << name # Officially add it to the database
-  #
-  #   # Instead of being 0 & 0, will be 0 & 1 (incremented),
-  #   #   even without being added to the database
-  #   puts al.to_yard_anchor_id(name)   # This_is_a_test_0
-  #   puts al.to_yard_anchor_id(name)   # This_is_a_test_1
+  # while GFM's number is only local to each duplicate.
   #
-  #   puts al.to_github_anchor_id(name) # this-is-a-test-1
-  #   puts al.to_github_anchor_id(name) # this-is-a-test-1
-  #
-  #   name = 'This is another test!'
-  #   al << name # Officially add it to the database
-  #
-  #   # Instead of being 0 & 1, will be 2 & 3 (global increment),
-  #   #   even without being added to the database
-  #   puts al.to_yard_anchor_id(name)   # This_is_another_test_2
-  #   puts al.to_yard_anchor_id(name)   # This_is_another_test_3
-  #
-  #   puts al.to_github_anchor_id(name) # this-is-another-test-1
-  #   puts al.to_github_anchor_id(name) # this-is-another-test-1
-  #
-  # @author Jonathan Bradley Whited
-  # @since  1.0.0
+  # @since 1.0.0
   #
   # @see GFMFixTask
-  ###
   class AnchorLinks
     # @return [Hash] the GFM-style anchor IDs pointing to their YARDoc ID equivalents that have been added
     attr_reader :anchor_ids
@@ -75,7 +37,7 @@ module YardGhurt
     attr_accessor :yard_dup_num
 
     def initialize
-      super()
+      super
       reset
     end
 
@@ -101,7 +63,7 @@ module YardGhurt
     #
     # @note +yard_id:+ was added in v1.2.1 for YARD v0.9.25+.
     #
-    # @param  name [String] the name (header text) to convert to anchor IDs and add to the database
+    # @param name [String] the name (header text) to convert to anchor IDs and add to the database
     # @return [self]
     def add_anchor(name,yard_id: nil)
       yard_id = to_yard_anchor_id(name) if yard_id.nil?
@@ -119,9 +81,9 @@ module YardGhurt
     #
     # @return [String] the escaped string
     #
-    # @since  1.2.0
+    # @since 1.2.0
     def self.escape(str)
-      # URI.escape()/encode() is obsolete
+      # URI.escape()/encode() is obsolete.
       return URI.encode_www_form_component(str)
     end
 
@@ -202,7 +164,7 @@ module YardGhurt
         id.downcase!
       end
 
-      id = self.class.escape(id) # For non-English languages
+      id = self.class.escape(id) # For non-English languages.
 
       # Duplicates
       dup_num = 1
@@ -251,9 +213,9 @@ module YardGhurt
       id.strip!
       id.gsub!(/&[^;]+;/,'_') # Replace entities: &...;
       id.gsub!(/[^a-z0-9-]/i,'_')
-      id = self.class.escape(id) # For non-English languages
+      id = self.class.escape(id) # For non-English languages.
 
-      # Duplicates
+      # Duplicates.
       orig_id = id.dup
 
       while @yard_anchor_ids.include?(id)

data/lib/yard_ghurt/gfm_fix_task.rb

@@ -3,22 +3,18 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'rake'
-require 'set'
-
 require 'rake/tasklib'
-
+require 'set'
 require 'yard_ghurt/anchor_links'
 require 'yard_ghurt/util'
 
 module YardGhurt
-  ###
   # Fix (find & replace) text in the GitHub Flavored Markdown (GFM) files in the YARDoc directory,
   # for differences between the two formats.
   #
@@ -26,53 +22,27 @@ module YardGhurt
   #   rake yard_gfm_fix dryrun=true
   #
   # @example What I Use
-  #   YardGhurt::GFMFixTask.new() do |task|
+  #   YardGhurt::GFMFixTask.new do |task|
   #     task.arg_names = [:dev]
   #     task.dry_run = false
   #     task.fix_code_langs = true
   #     task.md_files = ['index.html']
   #
-  #     task.before = Proc.new() do |t2,args|
-  #       # Delete this file as it's never used (index.html is an exact copy)
-  #       YardGhurt.rm_exist(File.join(t2.doc_dir,'file.README.html'))
+  #     task.before = proc do |task2,args|
+  #       # Delete this file as it's never used (`index.html` is an exact copy).
+  #       YardGhurt.rm_exist(File.join(task2.doc_dir,'file.README.html'))
   #
-  #       # Root dir of my GitHub Page for CSS/JS
+  #       # Root dir of my GitHub Page for CSS/JS.
   #       ghp_root_dir = YardGhurt.to_bool(args.dev) ? '../../esotericpig.github.io' : '../../..'
   #
-  #       t2.css_styles << %Q(<link rel="stylesheet" type="text/css" href="#{ghp_root_dir}/css/prism.css" />)
-  #       t2.js_scripts << %Q(<script src="#{ghp_root_dir}/js/prism.js"></script>)
+  #       task2.css_styles << %(
+  #         <link rel="stylesheet" type="text/css" href="#{ghp_root_dir}/css/prism.css" />
+  #       )
+  #       task2.js_scripts << %(<script src="#{ghp_root_dir}/js/prism.js"></script>)
   #     end
   #   end
   #
-  # @example Using All Options
-  #   YardGhurt::GFMFixTask.new(:yard_fix) do |task|
-  #     task.anchor_db           = {'tests' => 'Testing'} # #tests => #Testing
-  #     task.arg_names          << :name # Custom args
-  #     task.css_styles         << '<link rel="stylesheet" href="css/my_css.css" />' # Inserted at </head>
-  #     task.css_styles         << '<style>body{ background-color: linen; }</style>'
-  #     task.custom_gsub         = Proc.new() {|line| !line.gsub!('YardGhurt','YARD GHURT!').nil?()}
-  #     task.custom_gsubs       << [/newline/i,'Do you smell what The Rock is cooking?']
-  #     task.deps               << :yard # Custom dependencies
-  #     task.description         = 'Fix it'
-  #     task.doc_dir             = 'doc'
-  #     task.dry_run             = false
-  #     task.exclude_code_langs  = Set['ruby']
-  #     task.fix_anchor_links    = true
-  #     task.fix_code_langs      = true
-  #     task.fix_file_links      = true
-  #     task.js_scripts         << '<script src="js/my_js.js"></script>' # Inserted at </body>
-  #     task.js_scripts         << '<script>document.write("Hello World!");</script>'
-  #     task.md_files            = ['index.html']
-  #     task.verbose             = false
-  #
-  #     task.before = Proc.new() {|task,args| puts "Hi, #{args.name}!"}
-  #     task.during = Proc.new() {|task,args,file| puts "#{args.name} can haz #{file}?"}
-  #     task.after  = Proc.new() {|task,args| puts "Goodbye, #{args.name}!"}
-  #   end
-  #
-  # @author Jonathan Bradley Whited
-  # @since  1.1.0
-  ###
+  # @since 1.1.0
   class GFMFixTask < Rake::TaskLib
     # This is important so that a subsequent call to this task will not write the CSS again.
     #
@@ -93,7 +63,7 @@ module YardGhurt
     #
     #   # @param task [self]
     #   # @param args [Rake::TaskArguments] the args specified by {arg_names}
-    #   task.after = Proc.new do |task,args|
+    #   task.after = proc do |task,args|
     #     puts args.dev
     #   end
     #
@@ -120,7 +90,7 @@ module YardGhurt
     #
     #   # @param task [self]
     #   # @param args [Rake::TaskArguments] the args specified by {arg_names}
-    #   task.before = Proc.new do |task,args|
+    #   task.before = proc do |task,args|
     #     puts args.dev
     #   end
     #
@@ -141,10 +111,10 @@ module YardGhurt
     #   # @param line [String] the current line being processed from the current file
     #   #
     #   # @return [true,false] whether there was a change
-    #   task.custom_gsub = Proc.new do |line|
+    #   task.custom_gsub = proc do |line|
     #     has_change = false
     #
-    #     has_change = !line.gsub!('dev','prod').nil?() || has_change
+    #     has_change = !line.gsub!('dev','prod').nil? || has_change
     #     # More changes...
     #
     #     return has_change
@@ -191,7 +161,7 @@ module YardGhurt
     #   # @param task [self]
     #   # @param args [Rake::TaskArguments] the args specified by {arg_names}
     #   # @param file [String] the current file being processed
-    #   task.during = Proc.new do |task,args,file|
+    #   task.during = proc do |task,args,file|
     #     puts args.dev
     #   end
     #
@@ -259,7 +229,7 @@ module YardGhurt
     alias_method :verbose?,:verbose
 
     # @param name [Symbol] the name of this task to use on the command line with +rake+
-    def initialize(name=:yard_gfm_fix)
+    def initialize(name = :yard_gfm_fix)
       super()
 
       @after = nil
@@ -283,7 +253,7 @@ module YardGhurt
       @name = name
       @verbose = true
 
-      yield self if block_given?
+      yield(self) if block_given?
       define
     end
 
@@ -298,7 +268,7 @@ module YardGhurt
     # Define the Rake task and description using the instance variables.
     def define
       desc @description
-      task @name,Array(@arg_names) => Array(@deps) do |task,args|
+      task @name,Array(@arg_names) => Array(@deps) do |_task,args|
         env_dryrun = ENV['dryrun']
 
         if !env_dryrun.nil? && !(env_dryrun = env_dryrun.to_s.strip).empty?
@@ -390,14 +360,14 @@ module YardGhurt
 
           has_change = false
 
-          # Standard
+          # Standard.
           has_change = add_css_styles!(line) || has_change
           has_change = add_js_scripts!(line) || has_change
           has_change = gsub_anchor_links!(line) || has_change
           has_change = gsub_code_langs!(line) || has_change
           has_change = gsub_local_file_links!(line) || has_change
 
-          # Custom
+          # Custom.
           has_change = gsub_customs!(line) || has_change
           has_change = gsub_custom!(line) || has_change
 
@@ -506,14 +476,14 @@ module YardGhurt
 
           if yard_link.nil?
             # Either the GFM link is wrong [check with @anchor_links.to_github_anchor_id()]
-            #   or the internal code is broken [check with @anchor_links.to_s()]
+            #   or the internal code is broken [check with @anchor_links.to_s()].
             puts "! YARDoc anchor link for GFM anchor link [#{link}] does not exist"
 
             if !@has_verbose_anchor_links
               if @verbose
                 puts '  GFM anchor link in the Markdown file is wrong?'
                 puts '  Please check the generated links:'
-                puts %Q(  #{@anchor_links.to_s.strip.gsub("\n","\n  ")})
+                puts %(  #{@anchor_links.to_s.strip.gsub("\n","\n  ")})
               else
                 puts "  Turn on #{self.class}.verbose for more info"
               end
@@ -525,7 +495,7 @@ module YardGhurt
           else
             has_change = true
 
-            %Q(href="##{yard_link}")
+            %(href="##{yard_link}")
           end
         end
       end
@@ -543,22 +513,22 @@ module YardGhurt
       has_change = false
       tag = 'code class="'
 
-      line.gsub!(Regexp.new(Regexp.quote(tag) + '[^"]*"')) do |code_class|
+      line.gsub!(Regexp.new(%(#{Regexp.quote(tag)}[^"]*"))) do |code_class|
         lang = code_class[tag.length..-2].strip
 
-        if lang.empty? || lang =~ /^language\-/ || @exclude_code_langs.include?(lang)
+        if lang.empty? || lang =~ /^language-/ || @exclude_code_langs.include?(lang)
           code_class
         else
           has_change = true
 
-          %Q(#{tag}language-#{lang.downcase}")
+          %(#{tag}language-#{lang.downcase}")
         end
       end
 
       return has_change
     end
 
-    # Call the custom Proc {custom_gsub} (if it responds to +:call+) on +line+,
+    # Call the custom Proc {custom_gsub} (if it responds to +:call+) on +line+.
     #
     # @param line [String] the line from the file to fix
     def gsub_custom!(line)
@@ -596,7 +566,7 @@ module YardGhurt
       has_change = false
       tag = 'href="'
 
-      line.gsub!(Regexp.new(Regexp.quote(tag) + '[^#][^"]*"')) do |href|
+      line.gsub!(Regexp.new(%(#{Regexp.quote(tag)}[^#][^"]*"))) do |href|
         link = href[tag.length..-2].strip
 
         if link.empty? || !File.exist?(link)
@@ -605,7 +575,7 @@ module YardGhurt
           link = File.basename(link,'.*')
           has_change = true
 
-          %Q(#{tag}file.#{link}.html")
+          %(#{tag}file.#{link}.html")
         end
       end
 

data/lib/yard_ghurt/ghp_sync_task.rb

@@ -3,47 +3,25 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'rake'
-
 require 'rake/tasklib'
-
 require 'yard_ghurt/util'
 
 module YardGhurt
-  ###
   # Sync YARDoc to a local GitHub Pages repo (uses +rsync+ by default).
   #
   # @example What I Use
-  #   YardGhurt::GHPSyncTask.new() do |task|
+  #   YardGhurt::GHPSyncTask.new do |task|
   #     task.ghp_dir = '../esotericpig.github.io/docs/yard_ghurt/yardoc'
   #     task.sync_args << '--delete-after'
   #   end
   #
-  # @example Using All Options
-  #   # Execute: rake ghp_doc[false,'Ruby']
-  #   YardGhurt::GHPSyncTask.new(:ghp_doc) do |task|
-  #     task.arg_names   << :name                      # Custom args
-  #     task.deps        << :yard                      # Custom dependencies
-  #     task.description  = 'Rsync my_doc/ to my page'
-  #     task.doc_dir      = 'my_doc'                   # YARDoc directory of generated files
-  #     task.ghp_dir      = '../dest_dir/my_page'
-  #     task.strict       = true                       # Fail if doc_dir doesn't exist
-  #     task.sync_args   << '--delete-after'
-  #     task.sync_cmd     = '/usr/bin/rsync'
-  #
-  #     task.before = Proc.new() {|task,args| puts "Hi, #{args.name}!"}
-  #     task.after  = Proc.new() {|task,args| puts "Goodbye, #{args.name}!"}
-  #   end
-  #
-  # @author Jonathan Bradley Whited
-  # @since  1.1.0
-  ###
+  # @since 1.1.0
   class GHPSyncTask < Rake::TaskLib
     # @return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the end of this task or +nil+;
     #                    default: +nil+
@@ -97,7 +75,7 @@ module YardGhurt
     alias_method :strict?,:strict
 
     # @param name [Symbol] the name of this task to use on the command line with +rake+
-    def initialize(name=:yard_ghp_sync)
+    def initialize(name = :yard_ghp_sync)
       super()
 
       @after = nil
@@ -112,7 +90,7 @@ module YardGhurt
       @sync_args = ['-ahv','--progress']
       @sync_cmd = 'rsync'
 
-      yield self if block_given?
+      yield(self) if block_given?
       define
     end
 
@@ -122,17 +100,16 @@ module YardGhurt
       @arg_names.unshift(:deploy) unless @arg_names.include?(:deploy)
 
       desc @description
-      task @name,@arg_names => Array(@deps) do |task,args|
+      task @name,@arg_names => Array(@deps) do |_task,args|
         deploy = Util.to_bool(args.deploy)
 
         @before.call(self,args) if @before.respond_to?(:call)
 
-        # Without these checks, sh raises some pretty cryptic errors.
-        if @strict
-          # If you want to use a non-local dir, set strict to false.
-          if !File.exist?(@doc_dir)
-            raise ArgumentError,%Q(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
-          end
+        # Without the below checks, sh() raises some pretty cryptic errors.
+
+        # If you want to use a non-local dir, set strict to false.
+        if @strict && !File.exist?(@doc_dir)
+          raise ArgumentError,%(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
         end
         # Do not check if ghp_dir exists because rsync may create it.
         if @ghp_dir.nil? || @ghp_dir.to_s.strip.empty?
@@ -143,7 +120,7 @@ module YardGhurt
 
         if !deploy
           puts
-          puts %Q(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
+          puts %(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
         end
 
         @after.call(self,args) if @after.respond_to?(:call)

data/lib/yard_ghurt/util.rb

@@ -3,14 +3,12 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 module YardGhurt
-  ###
   # Utility methods in a separate module/mixin,
   # so that a programmer can require/load a sole task:
   #   require 'yard_ghurt/gfm_fix_task'
@@ -23,15 +21,13 @@ module YardGhurt
   # External code can either use this module or {YardGhurt},
   # which includes this module as a mixin.
   #
-  # @author Jonathan Bradley Whited
-  # @since  1.0.0
-  ###
+  # @since 1.0.0
   module Util
     # @return [Array<String>] the lower-case Strings that will equal to +true+
-    TRUE_BOOLS = %w[ 1 on t true y yes ].freeze
+    TRUE_BOOLS = %w[1 on t true y yes].freeze
 
     # @return a very flexible (non-strict) Semantic Versioning regex, ignoring pre-release/build-metadata
-    # @since  1.2.1
+    # @since 1.2.1
     SEM_VER_REGEX = /(?<major>\d+)(?:\.(?<minor>\d+))?(?:\.(?<patch>\d+))?/.freeze
 
     # If +include Util+ is called, extend {ClassMethods}.
@@ -48,7 +44,7 @@ module YardGhurt
       #
       # @param filename [String] the file to remove
       # @param output [true,false] whether to log it to stdout
-      def rm_exist(filename,output=true)
+      def rm_exist(filename,output = true)
         return unless File.exist?(filename)
 
         puts "[#{filename}]: - Deleted" if output
@@ -77,12 +73,12 @@ module YardGhurt
       # This is used for checking the YARD version internally,
       # so needs to be very flexible.
       #
-      # @param  str [String,Object] the object to parse; +to_s()+ will be called on it
+      # @param str [String,Object] the object to parse; +to_s()+ will be called on it
       # @return [Hash] the Semantic Version parts: +{:major, :minor, :patch}+
       #                defaults all values to +0+ if the version cannot be parsed
-      # @see    SEM_VER_REGEX
-      # @see    #yard_sem_ver
-      # @since  1.2.1
+      # @see SEM_VER_REGEX
+      # @see #yard_sem_ver
+      # @since 1.2.1
       def parse_sem_ver(str)
         sem_ver = {
           major: 0,minor: 0,patch: 0,
@@ -109,20 +105,16 @@ module YardGhurt
       # On subsequent calls, it will return the stored value.
       #
       # @return [Hash] YARD's version parts
-      # @see    parse_sem_ver
-      # @since  1.2.1
+      # @see parse_sem_ver
+      # @since 1.2.1
       def yard_sem_ver
         return @yard_sem_ver unless @yard_sem_ver.nil?
 
         require 'yard'
 
-        if defined?(YARD::VERSION)
-          ver = YARD::VERSION
-        else
-          ver = ''
-        end
+        @yard_sem_ver = parse_sem_ver(defined?(YARD::VERSION) ? YARD::VERSION : '')
 
-        return(@yard_sem_ver = parse_sem_ver(ver))
+        return @yard_sem_ver
       end
     end
 

data/lib/yard_ghurt/version.rb

@@ -3,12 +3,11 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 module YardGhurt
-  VERSION = '1.2.1'
+  VERSION = '1.2.2'
 end

data/lib/yard_ghurt.rb

@@ -3,12 +3,11 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2021 Jonathan Bradley Whited
+# Copyright (c) 2019 Bradley Whited
 #
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
-
 require 'optparse'
 require 'yard_ghurt/anchor_links'
 require 'yard_ghurt/gfm_fix_task'
@@ -16,30 +15,23 @@ require 'yard_ghurt/ghp_sync_task'
 require 'yard_ghurt/util'
 require 'yard_ghurt/version'
 
-
-###
 # YARDoc GitHub Rake Tasks
 #
-# @author Jonathan Bradley Whited
-# @since  1.0.0
-###
+# @since 1.0.0
 module YardGhurt
   # Internal code should use +Util.+!
   # See {Util} for details.
   include Util
 
-  ###
   # A simple CLI app used in file +bin/yard_ghurt+.
   #
   # Mainly for getting GitHub/YARDoc anchor link IDs.
   #
-  # @author Jonathan Bradley Whited
-  # @since  1.2.0
-  ###
+  # @since 1.2.0
   class App
     attr_reader :args
 
-    def initialize(args=ARGV)
+    def initialize(args = ARGV)
       super()
 
       @args = args
@@ -69,20 +61,20 @@ module YardGhurt
           exit
         end
 
-        op.separator op.summary_indent + '---'
+        op.separator("#{op.summary_indent}---")
 
-        op.on_tail('-h','--help','Print this help') do
+        op.on_tail('-h','--help','Show help') do
           puts op
           exit
         end
-        op.on_tail('-v','--version','Print the version') do
+        op.on_tail('-v','--version','Show version') do
           puts "#{op.program_name} v#{op.version}"
           exit
         end
       end
 
       parser.parse!(@args)
-      puts parser # Print help if nothing was parsed
+      puts parser # Print help if nothing was parsed.
     end
   end
 end