mp-utils 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f99dcd4e1535b4b1777fd10c0659634b4687ac24c47ba7a0c2c967f77beb9a3
-  data.tar.gz: c2af79547fa099dba14ffdadb49bcf5892a30fab76f02f98aff3aa048a256336
+  metadata.gz: bd4e848d53092d07f0ffe66865c1dd718fec86eac82143a3c487e7163755d86a
+  data.tar.gz: cd14a3a2876dd20e67591a3da7f1da71ffb79ce6267647a6453884e47724b87e
 SHA512:
-  metadata.gz: 0c35d7a60dcf86f0c908c2b9f2380ae4bb41ff5e73d1e42315f919646c77f1471b43ecf679aaece84182922cef639c21f75ce88320f60a94a70ce126b2ddf540
-  data.tar.gz: ff1a0de07a11334ac444eaf9328c482d45b8b7271dd13e9df622fc4528753cf5c0d1a0e556eaab50ee458e24118d3c6ae1a3bb8bf76ab97318c4effb9a4287f4
+  metadata.gz: c43bbb206cd8778bfef333f1ac572b8d1cb5daadf2bda9c179849aaf8d39e2b77fb7507a165e57308e2b78e6ef8c77bb3025a502011a11a4f32b81a9ed88298c
+  data.tar.gz: 4dd356d68a6304642c639ecc8f82a6e5da7583876d507e726425fcec4fa80cf5b062047412aac2637e07b82a2d0dc6c1678332465eb377f10243a29d779ab9c2

data/lib/mp_utils.rb

@@ -7,4 +7,5 @@ require_relative 'utils/message'
 require_relative 'utils/question'
 require_relative 'utils/version_manager'
 require_relative 'utils/ansi_style_manager'
+require_relative 'utils/directory_structure'
 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_style_manager.rb

@@ -4,11 +4,81 @@ 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 and effects.
 #
-# @example
-#   manager = ANSIStyleManager.new("Hello <color:red>World</color>")
-#   puts manager.to_s # => "Hello \e[31mWorld\e[39m"
+# 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

data/lib/utils/directory_structure.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# Class to represent and process a directory structure.
+# It can be initialized with a hash or a YAML file.
+#
+# ## Using HASH
+#
+# The following example shows how to use DirectoryStructure with a hash.
+# ```ruby
+# hash = {
+#   'lib' => {
+#     'version.rb' => nil,
+#     'source' => [
+#       'file_1.rb',
+#       'file_2.rb',
+#       'file_3.rb'
+#     ],
+#     'resource' => {
+#       'images' => [
+#         'potato.png',
+#         'fries.jpeg',
+#         'franch_fries.png'
+#       ],
+#       'scripts' => {
+#         validation: 'teste.rb',
+#         sorting: [
+#           'shellsort.rb',
+#           'quicksort.rb'
+#         ],
+#         'build.rb' => nil
+#       }
+#     },
+#     generated: 'file.generated.rb'
+#   }
+# }
+# directory_structure = DirectoryStructure.new(hash)
+# puts "That is my directory structure:\n#{directory_structure}"
+# # Output:
+# # That is my directory structure:
+# # lib
+# # ╠═ version.rb
+# # ╠═ source
+# # ║  ╠═ file_1.rb
+# # ║  ╠═ file_2.rb
+# # ║  ╚═ file_3.rb
+# # ╠═ resource
+# # ║  ╠═ images
+# # ║  ║  ╠═ potato.png
+# # ║  ║  ╠═ fries.jpeg
+# # ║  ║  ╚═ franch_fries.png
+# # ║  ╚═ scripts
+# # ║     ╠═ validation
+# # ║     ║  ╚═ teste.rb
+# # ║     ╠═ sorting
+# # ║     ║  ╠═ shellsort.rb
+# # ║     ║  ╚═ quicksort.rb
+# # ║     ╚═ build.rb
+# # ╚═ generated
+# #    ╚═ file.generated.rb
+# ```
+#
+# ## Using a YAML/YML File
+#
+# First, you need to create a yml file.
+#
+# Example:
+# ```yml
+# lib:
+#   version.rb:
+#   source:
+#   - file_1.rb
+#   - file_2.rb
+#   - file_3.rb
+#   resource:
+#     images:
+#     - potato.png
+#     - fries.jpeg
+#     - franch_fries.png
+#     scripts:
+#       validation: teste.rb
+#       sorting:
+#       - shellsort.rb
+#       - quicksort.rb
+#       build.rb:
+#   generated: file.generated.rb
+# ```
+#
+# Considering that the file path is passed as a reference.
+#
+# You can initialize the class as in the example below:
+#
+# ```ruby
+# path = 'Replace/By/Your/YAML/FILE/PATH'
+# directory_structure = DirectoryStructure.new(path)
+# puts "That is my directory structure:\n#{directory_structure}"
+# # Output:
+# # That is my directory structure:
+# # lib
+# # ╠═ version.rb
+# # ╠═ source
+# # ║  ╠═ file_1.rb
+# # ║  ╠═ file_2.rb
+# # ║  ╚═ file_3.rb
+# # ╠═ resource
+# # ║  ╠═ images
+# # ║  ║  ╠═ potato.png
+# # ║  ║  ╠═ fries.jpeg
+# # ║  ║  ╚═ franch_fries.png
+# # ║  ╚═ scripts
+# # ║     ╠═ validation
+# # ║     ║  ╚═ teste.rb
+# # ║     ╠═ sorting
+# # ║     ║  ╠═ shellsort.rb
+# # ║     ║  ╚═ quicksort.rb
+# # ║     ╚═ build.rb
+# # ╚═ generated
+# #    ╚═ file.generated.rb
+# ```
+class DirectoryStructure
+  # Initializes the DirectoryStructure object.
+  #
+  # @param content [Hash, String] A hash representing the directory structure or a path to a YAML file.
+  # @raise [RuntimeError] If the content is not a Hash or a valid YAML file path.
+  def initialize(content)
+    if content.is_a?(Hash)
+      @dir_hash = content
+    elsif File.exist?(content)
+      @dir_hash = YAML.load_file(content)
+    else
+      raise 'Need be initialized with a Hash or yaml file path'
+    end
+  end
+
+  # Converts the directory structure to a string representation.
+  #
+  # @return [String] The string representation of the directory structure.
+  def to_s
+    @output = String.new('')
+    process_node(@dir_hash)
+    @output
+  end
+
+  private
+
+  # Generates the indentation string based on the key.
+  #
+  # @param key [Symbol] The key indicating the type of indentation.
+  # @return [String] The indentation string.
+  def generate_indent(key)
+    { middle: '║  ', last: '   ' }[key] || ''
+  end
+
+  # Concatenates the node to the output string with the given prefix and indentation.
+  #
+  # @param node [String] The node to be concatenated.
+  # @param prefix [Symbol] The prefix indicating the type of node.
+  # @param indent [Array<Symbol>] The array of indentation keys.
+  # @return [void]
+  def concant(node, prefix:, indent:)
+    prefix_string = { middle: '╠═ ', last: '╚═ ' }[prefix] || ''
+    indent_string = indent.map { |i| generate_indent(i) }.join
+    @output << "#{indent_string}#{prefix_string}#{node}\n"
+  end
+
+  # Processes an array of nodes and concatenates them to the output string.
+  #
+  # @param array [Array] The array of nodes to be processed.
+  # @param indent [Array<Symbol>] The array of indentation keys.
+  # @return [void]
+  def process_array(array, indent:)
+    array.each_with_index do |item, index|
+      prefix = index == array.size - 1 ? :last : :middle
+      concant(item, prefix: prefix, indent: indent)
+    end
+  end
+
+  # Processes a hash of nodes and concatenates them to the output string.
+  #
+  # @param hash [Hash] The hash of nodes to be processed.
+  # @param level [Integer] The current level of indentation.
+  # @param indent [Array<Symbol>] The array of indentation keys.
+  # @return [void]
+  def process_hash(hash, level:, indent:)
+    hash.each_with_index do |(key, value), index|
+      new_indent = indent.dup
+      prefix = :empty
+
+      if level > new_indent.size
+        prefix = index == hash.size - 1 ? :last : :middle
+        new_indent = indent + [prefix]
+      end
+
+      concant(key, prefix: prefix, indent: indent)
+      process_node(value, indent: new_indent, level: level)
+    end
+  end
+
+  # Processes a node (hash, array, or other) and concatenates it to the output string.
+  #
+  # @param node [Object] The node to be processed.
+  # @param level [Integer] The current level of indentation.
+  # @param indent [Array<Symbol>] The array of indentation keys.
+  # @return [void]
+  def process_node(node, level: 0, indent: [''])
+    if node.is_a?(Hash)
+      process_hash(node, indent: indent, level: level + 1)
+    elsif node.is_a?(Array)
+      process_array(node, indent: indent)
+    elsif !node.nil?
+      concant(node, prefix: :last, indent: indent)
+    end
+  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.

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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mp-utils
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Marcio F Paludo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-30 00:00:00.000000000 Z
+date: 2024-07-07 00:00:00.000000000 Z
 dependencies: []
 description: |
   Helpers to facilitate scripts Writing.
@@ -32,6 +32,7 @@ files:
 - lib/utils/ansi_style_manager.rb
 - lib/utils/array.rb
 - lib/utils/constants.rb
+- lib/utils/directory_structure.rb
 - lib/utils/key.rb
 - lib/utils/message.rb
 - lib/utils/question.rb
@@ -42,6 +43,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/MarcioFPaludo/ruby-mp-utils
   source_code_uri: https://github.com/MarcioFPaludo/ruby-mp-utils
+  documentation_uri: https://marciofpaludo.github.io/ruby-mp-utils
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []