mp-utils 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e35a3d445a73ca931a0503b2d162c1a54a40b8b3bc04f4961884c607a6c6dfde
+  data.tar.gz: 510838aa718f0475e7ad846b0913325b89a711050566ee2778a655e29ec2fdc4
+SHA512:
+  metadata.gz: a3e48fb89f3505cc381529c052e26fbd61ed490674216fdd8ffe121f8849ce931e0432ac8d02b0ab88e3ce5353ab7424ff656069057575f64e3793636d3ba854
+  data.tar.gz: de22e7695b09793b51aaa80205b036c4b2e2e7adba46a2c41c29543cfe6798795ffc8e93bbd037b43757472a294da817fe2c4b478e61d541333980623dc99452

data/lib/mp_utils.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'utils/key'
+require 'utils/message'
+require 'resources/path_helper'

data/lib/resources/messages/hellow_world.txt

@@ -0,0 +1 @@
+Hellow World from MPUtils!

data/lib/resources/path_helper.rb

@@ -0,0 +1,36 @@
+# 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.
+module Resources
+  # Retrieves the path to the directory containing this module, which serves as the default library path.
+  #
+  # @return [String] the directory path of this module, used as the default library path.
+  def self.library_path
+    __dir__
+  end
+
+  # Returns the custom path for resources as defined by the user. This path can be set at runtime
+  # through the use of the environment variable "SCRIPT_CUSTOM_RESOURCES" or programmatically via the
+  # {define} method. This method allows for easy retrieval of the custom path, facilitating flexible
+  # resource management.
+  #
+  # @return [String, nil] the custom resources path as defined by the environment variable, or nil if it hasn't been set.
+  def self.custom_path
+    ENV['SCRIPT_CUSTOM_RESOURCES']
+  end
+
+  # Provides a means to programmatically define a custom resources path at runtime. This method updates
+  # the "SCRIPT_CUSTOM_RESOURCES" environment variable to store the custom path, making it retrievable
+  # through the {custom_path} method. This allows for dynamic setting of resource paths based on runtime
+  # conditions or user preferences.
+  #
+  # @param custom_path [String] the custom path to be set for resource access.
+  # @return [void]
+  def self.define(custom_path:)
+    ENV['SCRIPT_CUSTOM_RESOURCES'] = custom_path
+  end
+end

data/lib/utils/key.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# The Key class is designed to encapsulate strings within a specific prefix and suffix,
+# allowing for easy identification and manipulation of placeholders within messages.
+# This can be particularly useful in templating systems where placeholders need
+# to be dynamically replaced with actual content.
+#
+# @example Creating a new Key and converting it to a string
+#   key = Key.new("username")
+#   key.to_s # => "<||username||>"
+#
+# @example Finding keys within a string
+#   keys = Key.find_keys_in("Hello, <||username||>! Your code is <||code||>.")
+#   keys.map(&:to_s) # => ["<||username||>", "<||code||>"]
+class Key
+  # @!attribute [r] value
+  #   @return [String] the value of the key without the prefix and suffix.
+  attr_reader :value
+
+  # Initializes a new Key with the given value.
+  #
+  # @param value [#to_s] the value to be encapsulated by the Key.
+  def initialize(value)
+    @value = value.to_s
+  end
+
+  # Checks equality of two Key objects based on their value.
+  #
+  # @param other [Key] the other Key object to compare with.
+  # @return [Boolean] true if both Keys have the same value, false otherwise.
+  def ==(other)
+    self.class == other.class && @value == other.value
+  end
+
+  # Returns the string representation of the Key, including its prefix and suffix.
+  #
+  # @return [String] the string representation of the Key.
+  def to_s
+    "#{Key.prefix}#{@value}#{Key.suffix}"
+  end
+
+  # Returns the escaped Regexp representation of the Key.to_s return.
+  #
+  # @return [Regexp] the escaped regexp representation of the Key.to_s return.
+  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.
+  # @return [Array<Key>] an array of Key instances found within the given string.
+  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})/, ''))
+    end
+  end
+
+  # Returns the prefix used to identify the start of a Key in a string.
+  #
+  # @return [String] the prefix.
+  def self.prefix
+    '<||'
+  end
+
+  # Returns the suffix used to identify the end of a Key in a string.
+  #
+  # @return [String] the suffix.
+  def self.suffix
+    '||>'
+  end
+end

data/lib/utils/message.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+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.
+#
+# @example Creating a new Message instance and formatting it
+#   # Assuming "hellow_world" is a file that says "Hello, world!"
+#   message = Message.new("hellow_world")
+#   puts message.to_s # => "Hello, world!"
+class Message
+  attr_reader :message
+
+  # Initializes a new instance of the Message class with a given message template.
+  #
+  # @param message [String] The message template to be used.
+  # @param replaces [String] The replaces Hash used to change key finded in @message by custom values.
+  def initialize(message, replaces: nil)
+    raise 'Messsage replaces content need be a Hash' if !replaces.nil? && !replaces.is_a?(Hash)
+    @replaces = replaces
+    @message = message
+  end
+
+  # Compares two Message instances for equality based on their message content.
+  #
+  # @param other [Message] The other Message instance to compare with.
+  # @return [Boolean] True if the messages are equal, otherwise false.
+  def ==(other)
+    self.class == other.class && @message == other.message
+  end
+
+  # Converts the message template into a string, replacing any placeholders with actual data.
+  # This method searches for keys within the message and replaces them with corresponding
+  # content from message files located in either the custom path or the library path and appling
+  # the given replaces.
+  #
+  # @return [String] The formatted message with placeholders substituted with actual content.
+  def to_s
+    new_message = String.new(@message)
+    keys = Key.find_keys_in(@message)
+
+    if keys.count.positive?
+      keys.each do |key|
+        message = recover_message_with(key.value)
+        new_message.gsub!(key.to_s, message) if message != key.value
+      end
+    else
+      new_message = recover_message_with(new_message)
+    end
+
+    if !@replaces.nil?
+      @replaces.each do |key, value|
+        if key.is_a?(Key)
+          new_message.gsub!(key.to_regexp, value.to_s)
+        else
+          new_message.gsub!(/#{Regexp.escape(key.to_s)}/, value.to_s)
+        end
+      end
+    end
+
+    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.
+  #
+  # @return [String, nil] The custom path for message files, or nil if not set.
+  def custom_path
+    path = Resources.custom_path
+    return nil if path.nil?
+
+    File.join(path, 'messages')
+  end
+
+  # Provides the default library path for message files. This path is used as a fallback
+  # when a message file is not found in the custom path.
+  #
+  # @return [String] The path to the default library of message files.
+  def library_path
+    File.join(Resources.library_path, 'messages')
+  end
+
+  # Attempts to recover and return the content of a message file identified by the file_name parameter.
+  # It first looks in the custom path (if defined) and then in the library path.
+  #
+  # @param file_name [String] The name of the file containing the message content to be recovered.
+  # @return [String] The content of the message file, or the file_name itself if the file cannot be found.
+  def recover_message_with(file_name)
+    path = custom_path
+    unless path.nil?
+      message = recover_content_with(path, file_name)
+      return message unless message.nil?
+    end
+
+    message = recover_content_with(library_path, file_name)
+    return message unless message.nil?
+
+    file_name
+  end
+
+  # Reads and returns the content of a message file located at a specific path.
+  #
+  # @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)
+    file_path = File.join(path, "#{file_name}.txt")
+    return nil unless File.exist?(file_path)
+
+    File.read(file_path)
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: mp-utils
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Marcio F Paludo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-02-10 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Helpers to facilitate scripts Writing.
+  It can centralize messages in files and also add facilitators for the recovery and manipulation of some contents.
+email:
+- marciof.paludo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mp_utils.rb
+- lib/resources/messages/hellow_world.txt
+- lib/resources/path_helper.rb
+- lib/utils/key.rb
+- lib/utils/message.rb
+homepage: https://github.com/MarcioFPaludo/ruby-mp-utils
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/MarcioFPaludo/ruby-mp-utils
+  source_code_uri: https://github.com/MarcioFPaludo/ruby-mp-utils
+  changelog_uri: https://github.com/MarcioFPaludo/ruby-mp-utils/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.10
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: The MP-Utils library aims to facilitate the writing of daily scripts
+test_files: []