gem_hadar 2.10.0 → 2.11.0

data/lib/gem_hadar/utils.rb

@@ -1,67 +1,107 @@
 require 'pathname'
 
-# A module that provides utility methods for handling XDG Base Directory
-# specification compliance.
+# A module that provides utility methods for GemHadar
 #
-# This module offers functionality to determine the appropriate configuration
-# directory based on the XDG Base Directory specification, construct paths for
-# configuration files, and retrieve configuration data from those files. It
-# helps ensure consistent and standardized handling of user configuration files
-# across different operating systems.
-#
-# @example Determining the XDG configuration directory
-#   config_dir = GemHadar::Utils.xdg_config_home
-#
-# @example Retrieving configuration file contents
-#   config_content = GemHadar::Utils.xdg_config('myapp', 'default_value')
+# This module contains helper methods for common operations within the GemHadar
+# framework, including XDG configuration directory handling, user input
+# prompts, and memoization capabilities. It serves as a collection of reusable
+# utilities that support various aspects of gem automation and configuration
+# management.
 module GemHadar::Utils
-  # The xdg_config_home method determines the path to the XDG configuration
-  # directory.
+  # The xdg_config_home method determines the XDG configuration directory path.
   #
-  # It first checks if the XDG_CONFIG_HOME environment variable is set and not
-  # empty. If it is set, the method returns the value as a Pathname object. If
-  # XDG_CONFIG_HOME is not set, it defaults to using the HOME environment
-  # variable to construct the path within the standard .config directory.
+  # This method returns the path to the XDG configuration directory, which is used
+  # to store user-specific configuration files for applications. It first checks
+  # the XDG_CONFIG_HOME environment variable and returns its value if set.
+  # If the environment variable is not set, it falls back to the default
+  # configuration directory within the user's home directory, typically
+  # ~/.config.
   #
-  # @return [ Pathname ] the Pathname object representing the XDG configuration directory
+  # @return [ Pathname ] the Pathname object representing the XDG configuration
+  #   directory path
   def xdg_config_home
     ENV['XDG_CONFIG_HOME'].full? { Pathname.new(_1) } ||
       Pathname.new(ENV.fetch('HOME')) + '.config'
   end
 
+  # The xdg_config_dir method constructs the path to the XDG configuration
+  # directory for a specific application.
+  #
+  # This method takes an application name and returns the full path to the
+  # configuration directory for that application within the XDG configuration
+  # home directory.
+  #
+  # @param app [ String ] the name of the application to get the configuration
+  #   directory for
+  #
+  # @return [ Pathname ] the Pathname object representing the application's
+  #   configuration directory path
+  def xdg_config_dir(app)
+    xdg_config_home + app
+  end
+
   # The xdg_config_filename method constructs the full path to a configuration
-  # file based on the XDG Base Directory specification.
+  # file within the XDG configuration directory for a specific application.
   #
-  # It first checks if the XDG_CONFIG_HOME environment variable is set and not
-  # empty. If it is set, the method joins this directory with the provided
-  # filename to form the complete path. If XDG_CONFIG_HOME is not set, it
-  # defaults to using the HOME environment variable to construct the path
-  # within the standard .config directory.
+  # This method takes an application name and a filename, then combines them
+  # with the XDG configuration directory path to create the full path to a
+  # configuration file.
   #
+  # @param app [ String ] the name of the application to get the configuration
+  #   directory for
   # @param name [ String ] the name of the configuration file
   #
-  # @return [ String ] the full path to the configuration file
-  def xdg_config_filename(name)
-    xdg_config_home + name
+  # @return [ Pathname ] the Pathname object representing the full path to the
+  #   configuration file
+  def xdg_config_filename(app, name)
+    xdg_config_dir(app) + name
   end
 
-  memoize method:
-  # The xdg_config method retrieves configuration data from a file following
-  # the XDG Base Directory specification.
+  # The xdg_config method retrieves configuration content from XDG
+  # configuration directories
   #
-  # It checks for the existence of a configuration file using the
-  # xdg_config_filename method and returns its contents if found. If the file
-  # does not exist, it returns the provided default value instead.
+  # This method checks for the existence of a configuration file within the XDG
+  # configuration directory structure for the specified application. If the
+  # file exists, it reads and returns the file's content. If the file does not
+  # exist, it returns the provided default value instead.
   #
-  # @param name [ String ] the name of the configuration file to retrieve
-  # @param default [ Object ] the default value to return if the configuration file is not found
+  # @param app [ String ] the name of the application to get the configuration
+  #   directory for
+  # @param name [ String ] the name of the configuration file
+  # @param default [ String ] the default value to return if the configuration
+  #   file does not exist
   #
-  # @return [ String ] the content of the configuration file or the default value
-  def xdg_config(name, default)
-    if File.exist?(xdg_config_filename(name))
-      File.read(xdg_config_filename(name))
+  # @return [ String ] the content of the configuration file or the default
+  #   value if the file does not exist
+  def xdg_config(app, name, default)
+    if xdg_config_filename(app, name).exist?
+      File.read(xdg_config_filename(app, name))
     else
       default
     end
   end
+  memoize method: :xdg_config
+
+  # The ask? method prompts the user with a message and reads their input It
+  # returns a MatchData object if the input matches the provided pattern.
+  #
+  # @param prompt [ String ] the message to display to the user
+  # @param pattern [ Regexp ] the regular expression to match against the input
+  #
+  # @return [ MatchData, nil ] the result of the pattern match or nil if no match
+  def ask?(prompt, pattern, default: nil)
+    if prompt.include?('%{default}')
+      if default.present?
+        prompt = prompt % { default: ", default is #{default.inspect}" }
+      else
+        prompt = prompt % { default: '' }
+      end
+    end
+    STDOUT.print prompt
+    answer = STDIN.gets.chomp
+    default.present? && answer.blank? and answer = default
+    if answer =~ pattern
+      $~
+    end
+  end
 end

data/lib/gem_hadar/version.rb

@@ -1,6 +1,6 @@
 class GemHadar
   # GemHadar version
-  VERSION         = '2.10.0'
+  VERSION         = '2.11.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/lib/gem_hadar/version_spec.rb

@@ -0,0 +1,144 @@
+# A class that represents a version specification for a gem.
+#
+# This class provides functionality to parse and manipulate version strings,
+# including handling of semantic versioning formats and optional 'v' prefixes.
+# It supports creating version specifications from various input formats and
+# provides methods to access the underlying version information and string
+# representation.
+#
+# @example Creating a version specification
+#   version_spec = GemHadar::VersionSpec['1.2.3']
+#
+# @example Checking if a version is a HEAD reference
+#   version_spec = GemHadar::VersionSpec['HEAD']
+#   version_spec.head? # => true
+#
+# @example Getting the version tag with appropriate prefixing
+#   version_spec = GemHadar::VersionSpec['1.2.3']
+#   version_spec.tag # => 'v1.2.3'
+#
+# @example Comparing versions
+#   version1 = GemHadar::VersionSpec['1.2.3']
+#   version2 = GemHadar::VersionSpec['1.2.4']
+#   version1.version < version2.version # => true
+class GemHadar::VersionSpec
+  class << self
+    # The [] method creates a new VersionSpec instance from a specification.
+    #
+    # This factory method attempts to extract version information from the
+    # provided specification, handling both gem specifications and version
+    # strings. It supports optional prefix handling for the resulting version
+    # string.
+    #
+    # @param spec [Object] the specification to parse, typically a String or Gem::Specification
+    #
+    # @param with_prefix [Boolean] if true, ensures the version string has a 'v' prefix
+    #
+    # @param without_prefix [Boolean] if true, ensures the version string does not have a 'v' prefix
+    #
+    # @return [GemHadar::VersionSpec] a new VersionSpec instance
+    #
+    # @raise [ArgumentError] if both with_prefix and without_prefix are specified simultaneously
+    def [](spec, with_prefix: nil, without_prefix: nil)
+      !(with_prefix && without_prefix) or
+        raise ArgumentError, 'with_prefix and without_prefix is invalid'
+      spec.is_a?(self) and return spec
+      obj, version = nil, (spec.version rescue nil)
+      if version
+        ;
+      elsif /\Av?(\d+\.\d+\.\d+)\z/ =~ spec
+        begin
+          version = Tins::StringVersion::Version.new($1)
+        rescue ArgumentError
+        end
+      end
+      spec = spec.to_s
+      if version
+        if with_prefix
+          spec = spec.sub(/\A(?!v)/, 'v')
+        elsif without_prefix
+          spec = spec.sub(/\Av?/, '')
+        end
+      end
+      obj = new(spec, version)
+      obj.freeze
+    end
+
+    private_class_method :new
+  end
+
+  # Initializes a new VersionSpec instance.
+  #
+  # @param string [String] the original string representation of the version
+  # @param version [Tins::StringVersion::Version, nil] the parsed version object or nil if parsing failed
+  def initialize(string, version)
+    @string, @version = string, version
+  end
+
+  # Retrieves the parsed version object.
+  #
+  # @return [Tins::StringVersion::Version, nil] the parsed version object or nil if parsing failed
+  attr_reader :version
+
+  # Checks if a version object was successfully parsed.
+  #
+  # @return [Boolean] true if version was parsed successfully, false otherwise
+  def version?
+    !!@version
+  end
+
+  # The head? method checks if the version string represents a HEAD reference.
+  #
+  # This method returns true if the internal string representation of the version
+  # spec is exactly 'HEAD', indicating that it refers to the latest commit
+  # rather than a specific tagged version.
+  #
+  # @return [ Boolean ] true if the version string is 'HEAD', false otherwise
+  def head?
+    @string == 'HEAD'
+  end
+
+  # The tag method returns the version tag string with appropriate prefixing.
+  #
+  # This method checks if the version represents a HEAD reference and returns
+  # the raw string representation if so. Otherwise, it returns the version
+  # string with a 'v' prefix added to it.
+  #
+  # @return [ String ] the version tag string, either as-is for HEAD or with 'v' prefix added
+  def tag
+    head? ? to_s : with_prefix
+  end
+
+  # The untag method returns the version string without a 'v' prefix.
+  #
+  # This method checks if the version represents a HEAD reference and returns
+  # the raw string representation if so. Otherwise, it returns the version
+  # string with the 'v' prefix removed.
+  #
+  # @return [ String ] the version string without 'v' prefix or the raw string
+  #                    if it represents a HEAD reference
+  def untag
+    head? ? to_s : without_prefix
+  end
+
+  # Returns the original string representation.
+  #
+  # @return [String] the original version string
+  def to_s
+    @string.to_s
+  end
+
+  # Removes the 'v' prefix from the version string if present.
+  #
+  # @return [String] the version string without 'v' prefix
+  def without_prefix
+    to_s.sub(/\Av/, '')
+  end
+
+  # Adds a 'v' prefix to the version string if not already present.
+  #
+  # @return [String] the version string with 'v' prefix
+  def with_prefix
+    to_s.sub(/\A(?!v)/, 'v')
+  end
+end

data/lib/gem_hadar/warn.rb

@@ -43,8 +43,6 @@ class GemHadar
     # within this method itself.
     #
     # @param msgs [ Array<Object> ] the array of message objects to display as failures
-    #
-    # @return [ void ]
     def fail(*msgs)
       msgs.map! do |a|
         a.respond_to?(:to_str) ? color(196) { a.to_str } : a