mp-utils 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eaca69fbff0b08c6113af4c650ce37b158779bd260457fcd6e8b125dd4b4fee5
-  data.tar.gz: db821389f518caaaf4e4c130f92e8bf01e4ca2482f94683727f515363b332970
+  metadata.gz: 472fb772fc669be45aee52e5f931823934e59cb5f36974536dbfea782024ac9d
+  data.tar.gz: 9c5079304a471c97261ec621457575b1b79c9454a8a60f7d19ee9b0a51a7c777
 SHA512:
-  metadata.gz: ac347a457eb76b4cec8fd440e69fa37503e463f23c30570b5cb6aae8647b52f6327dd4b2c48734ce6132d0d4ebf322582100aac39f6ed79bab495f85b059fc76
-  data.tar.gz: 5137278119e0ce6b5c6f54a838526eedee624eec8bb4b45f9e0bcfa4f74546f0a460863af489b880edee14231947e89d606426870944a696f090ec0e4062e4b8
+  metadata.gz: 79864c2f162bb4d136ae0762d4196c868e0ce4136a31bb873ce79289478734f442acfc18e882d942b53b15e26c570a8b4d18c144f88d1ceae4573c01121583d8
+  data.tar.gz: cd1ed6a8fdb3c724d1953c0df5107468936b5a4800b537097ca32d3f134123c93f39c45ee327a347037e6246fe23600030128fe12f7371034d11bca9fb347204

data/lib/mp_utils.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
-require 'utils/key'
-require 'utils/array'
-require 'utils/message'
-require 'utils/question'
-require 'resources/path_helper'
+require_relative 'utils/key'
+require_relative 'utils/ansi'
+require_relative 'utils/array'
+require_relative 'utils/message'
+require_relative 'utils/question'
+require_relative 'utils/version_manager'
+require_relative 'utils/ansi_style_manager'
+require_relative 'resources/path_helper'

data/lib/resources/path_helper.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 # The Resources module manages and provides access to file system paths used by a script or application.
+#
 # It facilitates the definition and retrieval of a default library path, alongside a customizable path
-# that can be set at runtime either programmatically using the {define} method or through the environment
-# variable "SCRIPT_CUSTOM_RESOURCES". This flexibility allows applications to dynamically access resources
-# stored in various locations, depending on execution environment or user-defined settings.
+# that can be set at runtime either programmatically using the {define} method or through the
+# environment variable "SCRIPT_CUSTOM_RESOURCES".
+#
+# This flexibility allows applications to dynamically access resources stored in various locations,
+# depending on execution environment or user-defined settings.
 module Resources
   # Retrieves the path to the directory containing this module, which serves as the default library path.
   #

data/lib/utils/ansi.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+
+# The ANSI class is responsible for generating ANSI codes for text styling in terminals.
+# It allows the combination of multiple style and color codes.
+#
+# @example
+#   ansi = ANSI.new(:bold)
+#   puts ansi.to_s # => "\e[1m"
+#
+# @example
+#   ansi = ANSI.new([:bold, :red])
+#   puts ansi.to_s # => "\e[1;31m"
+class ANSI
+  # Hash that maps style and color names to their respective ANSI codes.
+  CODES_HASH = {
+    reset_all: 0,
+
+    # Effects
+    bold: 1,
+    faint: 2,
+    italic: 3,
+    underlined: 4,
+    blinking: 5,
+    inverse: 7,
+    hidden: 8,
+    strike: 9,
+    plain: 21,
+
+    # Remove Effects
+    remove_bold: 22,
+    remove_faint: 22,
+    remove_italic: 23,
+    remove_underlined: 24,
+    remove_blinking: 25,
+    remove_inverse: 27,
+    remove_hidden: 28,
+    remove_strike: 29,
+    remove_plain: 24,
+
+    # Colors
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    reset_color: 39,
+    rgb_format: [38, 2],
+    numeric_format: [38, 5],
+
+    # Background Colors
+    background_black: 40,
+    background_red: 41,
+    background_green: 42,
+    background_yellow: 43,
+    background_blue: 44,
+    background_magenta: 45,
+    background_cyan: 46,
+    background_white: 47,
+    background_rgb_format: [48, 2],
+    background_numeric_format: [48, 5],
+    reset_background: 49
+  }.freeze
+
+  # @return [Array<Integer>] the ANSI codes stored in the instance.
+  attr_reader :codes
+
+  # Initializes a new instance of the ANSI class.
+  #
+  # @param code [Array<Symbol>, Symbol, String] One or more ANSI codes represented as symbols, integers, or strings.
+  def initialize(code)
+    @codes = if code.is_a?(Array)
+               ANSI.normalize_array_codes(code)
+             elsif code.is_a?(Symbol)
+               [CODES_HASH[code]]
+             else
+               ANSI.normalize_array_codes(code.split(';'))
+             end
+  end
+
+  # Adds ANSI codes from another instance of the ANSI class.
+  #
+  # @param ansi [ANSI] The instance of the ANSI class whose codes will be added.
+  # @return [ANSI] A new instance of the ANSI class with the combined codes.
+  # @raise [RuntimeError] If the argument is not an instance of the ANSI class.
+  def append(ansi)
+    raise 'Needs be an instance of ANSI' unless ansi.is_a?(ANSI)
+
+    ANSI.new(@codes.union(ansi.codes))
+  end
+
+  # Adds ANSI codes from another instance of the ANSI class and updates the current instance.
+  #
+  # @param ansi [ANSI] The instance of the ANSI class whose codes will be added.
+  # @return [void]
+  def append!(ansi)
+    @codes = append(ansi).codes
+  end
+
+  # Converts the ANSI codes stored in the instance to a formatted string.
+  #
+  # @return [String] The formatted string with the ANSI codes.
+  def to_s
+    "\e[#{@codes.flatten.join(';')}m"
+  end
+
+  # Normalizes an array of codes, converting symbols and strings to their respective ANSI codes.
+  #
+  # @param array [Array<Symbol, String, Integer>] An array of codes to be normalized.
+  # @return [Array<Integer>] The normalized array of ANSI codes.
+  def self.normalize_array_codes(array)
+    array.map do |value|
+      next normalize_array_codes(value) if value.is_a?(Array)
+      next value if value.is_a?(Integer)
+      next CODES_HASH[value] if value.is_a?(Symbol)
+      next value.to_i if value.match?(CONSTANTS::ONLY_DIGITS_REGEX)
+
+      CODES_HASH[value.to_sym]
+    end
+  end
+end

data/lib/utils/ansi_style_manager.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+require_relative 'ansi'
+
+# The ANSIStyleManager class is responsible for managing and applying ANSI styles to a given string.
+#
+# It can replace tokens in the string with corresponding ANSI codes for colors, backgrounds and effects.
+#
+# ## Effects
+# Effects can be used by adding `<effect:effect_name>` at the beginning and `</effect>` at the end of
+# the sequence of characters to which you want the effect to be applied.
+#
+# Example:
+# ```ruby
+# manager = ANSIStyleManager.new('The text <effect:bold>Potato</effect> will be bold.')
+# puts manager
+# ```
+# Output:
+#
+# ![bold output](./.resources/images/bold_effect_example.png)
+#
+# Below is the table with all available effects:
+#
+# | Effect Name   | Description                |
+# |---------------|----------------------------|
+# | bold          | set bold mode.             |
+# | faint         | set dim/faint mode.        |
+# | italic        | set italic mode.           |
+# | underline     | set underline mode.        |
+# | blinking      | set blinking mode.         |
+# | inverse       | set inverse/reverse mode.  |
+# | hidden        | set hidden/invisible mode. |
+# | strike        | set strikethrough mode.    |
+# | plain         | set double underline mode. |
+#
+# > **Note:** Some terminals may not support some of the effects listed above.
+#
+# ## Colors
+# The ANSIStyleManager supports 3 types of coloring: Named Colors, RGB Colors, or 256 Colors.
+#
+# The foreground color can be changed by adding `<color:color_type>` at the beginning and `</color>`
+# at the end of the character sequence you want to color.
+#
+# Example:
+# ```ruby
+# text  = 'A <color:green>colorful <color:red>world <color:yellow>is <color:blue>much '
+# text += '</color>more </color>beautiful</color>!</color> ;)'
+# manager = ANSIStyleManager.new(text)
+# puts manager
+# ```
+# Output:
+#
+# ![colored output](./.resources/images/foreground_colored_example.png)
+#
+# It is also possible to set the background color of a text.
+#
+# The background color can be changed by adding `<color:color_type:color_type>` at the
+# beginning and `</color>` at the end of the character sequence you want to color.
+#
+# Example:
+# ```ruby
+# text  = 'A <color:green:white>colorful <color:196>world <color:yellow:111>is <color:blue:255;255;255>much '
+# text += '</color>more </color>beautiful</color>!</color> ;)'
+# manager = ANSIStyleManager.new(text)
+# puts manager
+# ```
+#
+# Output:
+#
+# ![colored output](./.resources/images/background_colored_exemple.png)
+#
+# Below is the table with all available color type patterns:
+#
+# |Color Type   |Pattern |Description                                                                                  |
+# |-------------|--------|---------------------------------------------------------------------------------------------|
+# |Reset colors |reset   |Resets to the terminal's default color.                                                      |
+# |256 Colors   |number  |Accepts numbers between 0 and 255.                                                           |
+# |RGB Colors   |R;G;B   |R, G, and B accept values between 0 and 255.                                                 |
+# |Named Colors |name    |Accepts the following color names: black, red, green, yellow, blue, magenta, cyan and white. |
+#
+class ANSIStyleManager
+  # @return [String] the string to which ANSI styles will be applied.
+  attr_reader :string
+
+  # Initializes a new instance of the ANSIStyleManager class.
+  #
+  # @param string [String] The string to which ANSI styles will be applied.
+  # @raise [RuntimeError] If the argument is not a string.
+  def initialize(string)
+    raise 'Need initialize with a string' unless string.is_a?(String)
+
+    @string = String.new(string)
+  end
+
+  # Replaces all color and effect tokens in the string with corresponding ANSI codes.
+  #
+  # @return [void]
+  def replace_all_tokens!
+    replace_color_tokens!
+    replace_effect_tokens!
+  end
+
+  # Replaces all color tokens in the string with corresponding ANSI codes.
+  #
+  # @return [void]
+  def replace_color_tokens!
+    scan_while_find(CONSTANTS::ANSI::COLORS) do |value|
+      colors = value.first.split(':')
+
+      replace_tokens_with!(
+        ansi_token: color_prefix(color: colors[0], background: colors[1]),
+        ansi_reset_token: ANSI.new(%i[reset_background reset_color]),
+        to_replace: "<color:#{value.first}>#{value.last}</color>",
+        preserve_reset_token: false,
+        text: value.last
+      )
+    end
+  end
+
+  # Replaces all effect tokens in the string with corresponding ANSI codes.
+  #
+  # @return [void]
+  def replace_effect_tokens!
+    scan_while_find(CONSTANTS::ANSI::EFFECTS) do |value|
+      replace_tokens_with!(
+        ansi_reset_token: ANSI.new("remove_#{value.first.downcase}"),
+        to_replace: "<effect:#{value.first}>#{value.last}</effect>",
+        ansi_token: ANSI.new(value.first.downcase),
+        preserve_reset_token: true,
+        text: value.last
+      )
+    end
+  end
+
+  # Converts the string with all tokens replaced by corresponding ANSI codes.
+  #
+  # @return [String] The string with ANSI codes applied.
+  def to_s
+    replace_all_tokens!
+    @string
+  end
+
+  private
+
+  # Generates the ANSI prefix for a given color and background.
+  #
+  # @param color [String] The color name or code.
+  # @param background [String, nil] The background color name or code.
+  # @return [ANSI] The ANSI instance representing the color and background.
+  def color_prefix(color:, background:)
+    color_ansi = generate_color_ansi(color, is_background: false)
+    return color_ansi.to_s if background.nil?
+
+    generate_color_ansi(background, is_background: true).append(color_ansi)
+  end
+
+  # Generates the ANSI instance for a given color.
+  #
+  # @param color [String] The color name or code.
+  # @param is_background [Boolean] Whether the color is for the background.
+  # @return [ANSI] The ANSI instance representing the color.
+  def generate_color_ansi(color, is_background:)
+    digit_values = color.scan(CONSTANTS::ANSI::COLOR_DIGITS_REGEX).flatten.compact
+
+    if [1, 3].include?(digit_values.count)
+      format = "#{digit_values.count == 1 ? 'numeric' : 'rgb'}_format"
+      format = "#{is_background ? 'background_' : ''}#{format}"
+
+      return ANSI.new([format, digit_values])
+    elsif color.match?(/^reset$/)
+      return ANSI.new(is_background ? :reset_background : :reset_color)
+    end
+
+    ANSI.new(is_background ? "background_#{color}" : color)
+  end
+
+  # Replaces tokens in the string with corresponding ANSI codes.
+  #
+  # @param text [String] The text to be styled.
+  # @param to_replace [String] The token to be replaced.
+  # @param ansi_token [ANSI] The ANSI instance representing the style.
+  # @param ansi_reset_token [ANSI] The ANSI instance representing the reset style.
+  # @param preserve_reset_token [Boolean] Whether to preserve the reset token in the text.
+  # @return [void]
+  def replace_tokens_with!(text:, to_replace:, ansi_token:, ansi_reset_token:, preserve_reset_token:)
+    colored_text = text.gsub(ansi_reset_token.to_s, "#{ansi_reset_token}#{ansi_token}") if preserve_reset_token
+    colored_text = text.gsub(ansi_reset_token.to_s, ansi_token.to_s) unless preserve_reset_token
+    @string.gsub!(to_replace, "#{ansi_token}#{colored_text}#{ansi_reset_token}")
+  end
+
+  # Scans the string for tokens matching the given regex and processes them with the provided block.
+  #
+  # @param scan_regex [Regexp] The regex to scan for tokens.
+  # @yieldparam value [Array<String>] The matched tokens.
+  # @return [void]
+  def scan_while_find(scan_regex, &block)
+    result = @string.scan(scan_regex)
+    while result.count.positive?
+      result.each do |value|
+        block.call(value)
+      end
+
+      result = @string.scan(scan_regex)
+    end
+  end
+end

data/lib/utils/constants.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# @!visibility private
+module CONSTANTS
+  ONLY_DIGITS_REGEX = /^\d+$/.freeze
+
+  # @!visibility private
+  module ANSI
+    COLOR_DIGITS_REGEX = /^(\d+);(\d+);(\d+)|(\d+)$/.freeze
+    COLOR_TOKEN_VALUE = '(?:[\w|\d]+|\d+\;\d+\;\d+)(?::[\w|\d]+|:\d+;\d+;\d+)?'
+    COLORS = %r{<color:(#{COLOR_TOKEN_VALUE})>((?:(?!<color:#{COLOR_TOKEN_VALUE}>|</color>).)*)</color>}m.freeze
+    EFFECTS = %r{<effect:(\w+)>((?:(?!<effect:\w+>|</effect>).)*)</effect>}m.freeze
+  end
+end

data/lib/utils/key.rb

@@ -45,10 +45,7 @@ class Key
   def to_regexp
     /#{Regexp.escape(to_s)}/
   end
-end
 
-# Static Methods
-class Key
   # Finds and returns all Key instances within the given string.
   #
   # @param value [#to_s] the string to search for keys.
@@ -56,8 +53,8 @@ class Key
   def self.find_keys_in(value)
     ep = Regexp.escape(prefix)
     es = Regexp.escape(suffix)
-    value.to_s.scan(/#{ep}[^#{ep}#{es}]+#{es}/).map do |key|
-      Key.new(key.gsub(/(#{ep})|(#{es})/, ''))
+    value.to_s.scan(/#{ep}([^#{ep}#{es}]+)#{es}/).map do |key|
+      Key.new(key.first)
     end
   end
 

data/lib/utils/message.rb

@@ -4,11 +4,15 @@ require_relative File.join('..', 'resources', 'path_helper')
 require_relative 'key'
 
 # The Message class represents a mechanism for dynamically handling and formatting messages.
+#
 # It supports the substitution of placeholders within a message template with actual data.
-# The class leverages file-based message templates, allowing for easy localization or customization
-# of messages. It integrates seamlessly with the Resources module to access these templates from
-# a customizable path set via the "SCRIPT_CUSTOM_RESOURCES" environment variable or from a default
-# library path.
+#
+# The class leverages file-based message templates, allowing for easy localization or
+# customization of messages.
+#
+# It integrates seamlessly with the Resources module to access these templates from
+# a customizable path set via the "SCRIPT_CUSTOM_RESOURCES" environment variable or
+# from a default library path.
 #
 # @example Creating a new Message instance and formatting it
 #   # Assuming "hellow_world" is a file that says "Hello, world!"
@@ -46,10 +50,7 @@ class Message
     new_message = replace_message_keys(String.new(@message))
     replace_all_to_replace_elements(new_message)
   end
-end
 
-# Private Methods
-class Message
   private
 
   # Determines the custom path for message files, if set through the "SCRIPT_CUSTOM_RESOURCES" environment variable.
@@ -123,11 +124,18 @@ class Message
   end
 
   # Reads and returns the content of a message file located at a specific path.
+  # If the file name have the suffix ".aas.txt", the ANSIStyleManager will be applied to the file.
   #
   # @param path [String] The path where the message file is located.
   # @param file_name [String] The name of the file to be read.
   # @return [String, nil] The content of the message file, or nil if the file does not exist.
   def recover_content_with(path, file_name)
+    aas_file_path = File.join(path, "#{file_name}.aas.txt")
+    if File.exist?(aas_file_path)
+      content = File.read(aas_file_path)
+      return ANSIStyleManager.new(content).to_s
+    end
+
     file_path = File.join(path, "#{file_name}.txt")
     return nil unless File.exist?(file_path)
 

data/lib/utils/version_manager.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Manages software versions with Major, Minor, and Patch components.
+class VersionManager
+  attr_reader :major, :minor, :patch
+
+  # Initializes a new instance of VersionManager.
+  #
+  # @param major [Integer, String] The major version or a string in the format "major.minor.patch".
+  # @param minor [Integer] The minor version (optional if major is a string).
+  # @param patch [Integer] The patch version (optional if major is a string).
+  def initialize(major = 0, minor = 0, patch = 0)
+    if major.is_a?(String)
+      parse_version_string(major)
+    else
+      @major = major
+      @minor = minor
+      @patch = patch
+    end
+  end
+
+  # Increments the major version and resets minor and patch to 0.
+  def increment_major
+    @major += 1
+    @minor = 0
+    @patch = 0
+  end
+
+  # Increments the minor version and resets patch to 0.
+  def increment_minor
+    @minor += 1
+    @patch = 0
+  end
+
+  # Increments the patch version.
+  def increment_patch
+    @patch += 1
+  end
+
+  # Returns the version as a string in the format "major.minor.patch".
+  #
+  # @return [String] The formatted version.
+  def to_s
+    "#{@major}.#{@minor}.#{@patch}"
+  end
+
+  private
+
+  # Parses a version string in the format "major.minor.patch".
+  #
+  # @param version_string [String] The version string.
+  def parse_version_string(version_string)
+    parts = version_string.split('.')
+    @major = parts[0].to_i
+    @minor = parts[1].to_i
+    @patch = parts[2].to_i
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mp-utils
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Marcio F Paludo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-16 00:00:00.000000000 Z
+date: 2024-07-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Helpers to facilitate scripts Writing.
@@ -28,10 +28,14 @@ files:
 - lib/resources/messages/question/error/integer.txt
 - lib/resources/messages/question/error/regex.txt
 - lib/resources/path_helper.rb
+- lib/utils/ansi.rb
+- lib/utils/ansi_style_manager.rb
 - lib/utils/array.rb
+- lib/utils/constants.rb
 - lib/utils/key.rb
 - lib/utils/message.rb
 - lib/utils/question.rb
+- lib/utils/version_manager.rb
 homepage: https://github.com/MarcioFPaludo/ruby-mp-utils
 licenses:
 - MIT