yard_ghurt 1.2.0 → 1.2.1

data/lib/yard_ghurt/ghp_sync_task.rb

@@ -1,23 +1,11 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019-2021 Jonathan Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 
@@ -30,13 +18,13 @@ 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|
   #     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|
@@ -48,68 +36,70 @@ module YardGhurt
   #     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 (@esotericpig)
+  #
+  # @author Jonathan Bradley Whited
   # @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+
     attr_accessor :after
-    
+
     # @note +:deploy+ will be added no matter what (cannot be deleted)
-    # 
+    #
     # @return [Array<Symbol>,Symbol] the custom arg(s) for this task; default: +[:deploy]+
     attr_accessor :arg_names
-    
+
     # @return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the beginning of this task or +nil+;
     #                    default: +nil+
     attr_accessor :before
-    
+
     # @example
     #   task.deps = :yard
     #   # or...
     #   task.deps = [:yard,:yard_gfm_fix]
-    # 
+    #
     # @return [Array<Symbol>,Symbol] the custom dependencies for this task; default: +[]+
     attr_accessor :deps
-    
+
     # @return [String] the description of this task (customizable)
     attr_accessor :description
-    
+
     # @return [String] the source directory of generated YARDoc files; default: +doc+
     attr_accessor :doc_dir
-    
+
     # @note You must set this, else an error is thrown.
-    # 
+    #
     # @return [String] the destination directory to sync {doc_dir} to
     attr_accessor :ghp_dir
-    
+
     # @return [String] the name of this task (customizable); default: +yard_ghp_sync+
     attr_accessor :name
-    
+
     # If you want to use a non-local {doc_dir} (a remote host), set this to +false+.
-    # 
+    #
     # @return [true,false] whether to throw an error if {doc_dir} does not exist; default: +true+
     attr_accessor :strict
-    
+
     # @note You should pass in multi-args separately: +['--exclude','*~']+
     # @note You should not single/double quote the args; +['"*~"']+ is unnecessary.
-    # 
+    #
     # @return [Array<String>] the args to pass to the {sync_cmd}; default: +['-ahv','--progress']+
     attr_accessor :sync_args
-    
+
     # @return [String] the sync command to use on the command line; default: +rsync+
     attr_accessor :sync_cmd
-    
+
     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)
+      super()
+
       @after = nil
       @arg_names = []
       @before = nil
@@ -121,22 +111,22 @@ module YardGhurt
       @strict = true
       @sync_args = ['-ahv','--progress']
       @sync_cmd = 'rsync'
-      
-      yield self if block_given?()
-      define()
+
+      yield self if block_given?
+      define
     end
-    
+
     # Define the Rake task and description using the instance variables.
-    def define()
+    def define
       @arg_names = *@arg_names
       @arg_names.unshift(:deploy) unless @arg_names.include?(:deploy)
-      
+
       desc @description
       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.
@@ -145,38 +135,38 @@ module YardGhurt
           end
         end
         # Do not check if ghp_dir exists because rsync may create it.
-        if @ghp_dir.nil?() || @ghp_dir.to_s().strip().empty?()
+        if @ghp_dir.nil? || @ghp_dir.to_s.strip.empty?
           raise ArgumentError,"#{self.class}.ghp_dir must be set"
         end
-        
+
         sh(*build_sh_cmd(deploy))
-        
+
         if !deploy
           puts
           puts %Q(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
         end
-        
+
         @after.call(self,args) if @after.respond_to?(:call)
       end
-      
+
       return self
     end
-    
+
     # Build the sync command to use on the command line.
-    # 
+    #
     # @param deploy [true,false] whether to actually deploy (+true+) or to run a dry-run (+false+)
-    # 
+    #
     # @return [Array<String>] the sync command and its args
     def build_sh_cmd(deploy)
       sh_cmd = [@sync_cmd]
-      
+
       sh_cmd << '--dry-run' unless deploy
       sh_cmd.push(*@sync_args)
-      
+
       # File.join() to add a trailing '/' if not present
       sh_cmd << File.join(@doc_dir,'')
       sh_cmd << File.join(@ghp_dir,'')
-      
+
       return sh_cmd
     end
   end

data/lib/yard_ghurt/util.rb

@@ -1,23 +1,11 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019-2021 Jonathan Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 
@@ -26,56 +14,118 @@ 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'
-  # 
+  #
   # Else, programmers would be required to always require/load the entire +yard_ghurt+ module:
   #   require 'yard_ghurt'
-  # 
+  #
   # All internal code should use this module.
-  # 
+  #
   # External code can either use this module or {YardGhurt},
   # which includes this module as a mixin.
-  # 
-  # @author Jonathan Bradley Whited (@esotericpig)
+  #
+  # @author Jonathan Bradley Whited
   # @since  1.0.0
   ###
   module Util
     # @return [Array<String>] the lower-case Strings that will equal to +true+
-    TRUE_BOOLS = ['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
+    SEM_VER_REGEX = /(?<major>\d+)(?:\.(?<minor>\d+))?(?:\.(?<patch>\d+))?/.freeze
+
     # If +include Util+ is called, extend {ClassMethods}.
-    # 
+    #
     # @param mod [Module] the module to extend
     def self.included(mod)
       mod.extend ClassMethods
     end
-    
+
     module ClassMethods
+      @yard_sem_ver = nil
+
       # If +filename+ exists, delete it, and if +output+ is +true+, log it to stdout.
-      # 
+      #
       # @param filename [String] the file to remove
       # @param output [true,false] whether to log it to stdout
       def rm_exist(filename,output=true)
         return unless File.exist?(filename)
-        
+
         puts "[#{filename}]: - Deleted" if output
         File.delete(filename)
       end
-      
+
       # Convert +str+ to +true+ or +false+.
-      # 
+      #
       # Even if +str+ is not a String, +to_s()+ will be called, so should be safe.
-      # 
+      #
       # @param str [String,Object] the String (or Object) to convert
-      # 
+      #
       # @return [true,false] the boolean value of +str+
-      # 
+      #
       # @see TRUE_BOOLS
       # @see GHPSyncTask#arg_names
       def to_bool(str)
-        return TRUE_BOOLS.include?(str.to_s().downcase())
+        return TRUE_BOOLS.include?(str.to_s.downcase)
+      end
+
+      # Parse +str+ as a non-strict Semantic Version:
+      #   \d+.\d+.\d+
+      #
+      # Unlike the specification, minor and patch are optional.
+      # Also, pre-release and build metadata are ignored.
+      # 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
+      # @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
+      def parse_sem_ver(str)
+        sem_ver = {
+          major: 0,minor: 0,patch: 0,
+        }
+
+        match = SEM_VER_REGEX.match(str.to_s.gsub(/\s+/u,''))
+
+        return sem_ver unless match
+
+        sem_ver[:major] = match[:major].to_i
+        sem_ver[:minor] = match[:minor].to_i unless match[:minor].nil?
+        sem_ver[:patch] = match[:patch].to_i unless match[:patch].nil?
+
+        return sem_ver
+      end
+
+      # Returns YARD's version as a +Hash+ of parts:
+      #   { major: 0, minor: 0, patch: 0 }
+      #
+      # If the version can not be parsed, it will return the exact
+      # same +Hash+ as above with all values to +0+.
+      #
+      # On initial call, it will parse it and store it.
+      # On subsequent calls, it will return the stored value.
+      #
+      # @return [Hash] YARD's version parts
+      # @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
+
+        return(@yard_sem_ver = parse_sem_ver(ver))
       end
     end
-    
+
     extend ClassMethods
   end
 end

data/lib/yard_ghurt/version.rb

@@ -1,26 +1,14 @@
-#!/usr/bin/env ruby
 # encoding: UTF-8
 # frozen_string_literal: true
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019-2021 Jonathan Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 
 module YardGhurt
-  VERSION = '1.2.0'
+  VERSION = '1.2.1'
 end

data/yard_ghurt.gemspec

@@ -3,20 +3,9 @@
 
 #--
 # This file is part of YardGhurt.
-# Copyright (c) 2019-2020 Jonathan Bradley Whited (@esotericpig)
-# 
-# YardGhurt is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-# 
-# YardGhurt is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Lesser General Public License for more details.
-# 
-# You should have received a copy of the GNU Lesser General Public License
-# along with YardGhurt.  If not, see <https://www.gnu.org/licenses/>.
+# Copyright (c) 2019-2021 Jonathan Bradley Whited
+#
+# SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
 
@@ -25,16 +14,16 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require 'yard_ghurt/version'
 
-Gem::Specification.new() do |spec|
+Gem::Specification.new do |spec|
   spec.name        = 'yard_ghurt'
   spec.version     = YardGhurt::VERSION
-  spec.authors     = ['Jonathan Bradley Whited (@esotericpig)']
-  spec.email       = ['bradley@esotericpig.com']
+  spec.authors     = ['Jonathan Bradley Whited']
+  spec.email       = ['code@esotericpig.com']
   spec.licenses    = ['LGPL-3.0-or-later']
   spec.homepage    = 'https://github.com/esotericpig/yard_ghurt'
   spec.summary     = 'YARDoc GitHub Rake Tasks'
   spec.description = "#{spec.summary}. Fix GitHub Flavored Markdown (GFM) files."
-  
+
   spec.metadata = {
     'bug_tracker_uri'   => 'https://github.com/esotericpig/yard_ghurt/issues',
     'changelog_uri'     => 'https://github.com/esotericpig/yard_ghurt/blob/master/CHANGELOG.md',
@@ -42,23 +31,23 @@ Gem::Specification.new() do |spec|
     'homepage_uri'      => 'https://github.com/esotericpig/yard_ghurt',
     'source_code_uri'   => 'https://github.com/esotericpig/yard_ghurt'
   }
-  
+
   spec.require_paths = ['lib']
   spec.bindir        = 'bin'
   spec.executables   = [spec.name]
-  
+
   spec.files = Dir.glob(File.join("{#{spec.require_paths.join(',')}}",'**','*.{erb,rb}')) +
                Dir.glob(File.join(spec.bindir,'**',"{#{spec.executables.join(',')}}")) +
                Dir.glob(File.join('{test,yard}','**','*.{erb,rb}')) +
-               %W( Gemfile #{spec.name}.gemspec Rakefile ) +
-               %w( CHANGELOG.md LICENSE.txt README.md )
-  
+               %W[ Gemfile #{spec.name}.gemspec Rakefile ] +
+               %w[ CHANGELOG.md LICENSE.txt README.md ]
+
   spec.required_ruby_version = '>= 2.1.10'
-  
-  spec.add_runtime_dependency 'rake' #,'~> 12.3'
-  
-  spec.add_development_dependency 'bundler'  ,'~> 1.17'
-  spec.add_development_dependency 'rdoc'     ,'~> 6.1'  # For RDoc for YARD (*.rb)
+
+  spec.add_runtime_dependency 'rake' # 13.0.3
+  spec.add_runtime_dependency 'yard' # 0.9.26, 0.9.24 (diff)
+
+  spec.add_development_dependency 'bundler'  ,'~> 2.2'
+  spec.add_development_dependency 'rdoc'     ,'~> 6.3'  # For RDoc for YARD (*.rb)
   spec.add_development_dependency 'redcarpet','~> 3.5'  # For Markdown for YARD (*.md)
-  spec.add_development_dependency 'yard'     ,'~> 0.9'
 end