kolor 1.0.0

data/lib/kolor/extra.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+# @!parse
+#   class String
+#     include Kolor::Extra
+#   end
+require_relative '../kolor'
+require_relative 'internal/enum'
+require_relative 'internal/logger'
+require_relative 'enum/foreground'
+require_relative 'enum/theme'
+# Kolor::Extra provides advanced terminal styling features.
+#
+# Features:
+#   - 256 color palette
+#   - RGB/True color support
+#   - Color gradients
+#   - Named themes
+#
+# @example 256 colors
+#   "text".color(196)           # foreground
+#   "text".on_color(196)        # background
+#
+# @example RGB colors
+#   "text".rgb(255, 0, 0)       # foreground
+#   "text".on_rgb(255, 0, 0)    # background
+#
+# @example Gradients
+#   "Hello World".gradient(:red, :blue)
+#   "Rainbow".rainbow
+#
+# @example Themes
+#   Kolor::Extra.theme(:success, :green, :bold)
+#   "Done!".success
+module Kolor
+  # Extended functionality for Kolor including RGB colors, gradients, and themes
+  module Extra
+    # 256-color palette support
+    # @param code [Integer] color code (0-255)
+    # @return [String, ColorizedString] colorized string
+    def color(code)
+      create_colorized_string("\e[38;5;#{code}m")
+    end
+
+    # 256-color background palette support
+    # @param code [Integer] color code (0-255)
+    # @return [String, ColorizedString] colorized string
+    def on_color(code)
+      create_colorized_string("\e[48;5;#{code}m")
+    end
+
+    # RGB / True color support (foreground)
+    # @param red [Integer] red component (0-255)
+    # @param green [Integer] green component (0-255)
+    # @param blue [Integer] blue component (0-255)
+    # @return [String, ColorizedString] colorized string
+    def rgb(red, green, blue)
+      return to_s unless Kolor.enabled?
+      return to_s unless [red, green, blue].all? { |v| v.between?(0, 255) }
+      create_colorized_string("\e[38;2;#{red};#{green};#{blue}m")
+    end
+
+    # RGB / True color support (background)
+    # @param red [Integer] red component (0-255)
+    # @param green [Integer] green component (0-255)
+    # @param blue [Integer] blue component (0-255)
+    # @return [String, ColorizedString] colorized string
+    def on_rgb(red, green, blue)
+      return to_s unless Kolor.enabled?
+      return to_s unless [red, green, blue].all? { |v| v.between?(0, 255) }
+      create_colorized_string("\e[48;2;#{red};#{green};#{blue}m")
+    end
+
+    # Hex color support (foreground)
+    # @param hex_color [String] with_hex color code (with or without #)
+    # @return [String, ColorizedString] colorized string
+    def with_hex(hex_color)
+      return to_s unless Kolor.enabled?
+
+      hex_color = hex_color.delete('#')
+      return to_s unless hex_color.match?(/^[0-9A-Fa-f]{6}$/)
+
+      r = hex_color[0..1].to_i(16)
+      g = hex_color[2..3].to_i(16)
+      b = hex_color[4..5].to_i(16)
+      rgb(r, g, b)
+    end
+
+    # Hex color support (background)
+    # @param hex_color [String] with_hex color code (with or without #)
+    # @return [String, ColorizedString] colorized string
+    def on_hex(hex_color)
+      return to_s unless Kolor.enabled?
+
+      hex_color = hex_color.delete('#')
+      return to_s unless hex_color.match?(/^[0-9A-Fa-f]{6}$/)
+
+      r = hex_color[0..1].to_i(16)
+      g = hex_color[2..3].to_i(16)
+      b = hex_color[4..5].to_i(16)
+      on_rgb(r, g, b)
+    end
+
+    # Gradient between two colors
+    # @param start_color [Symbol] starting color name
+    # @param end_color [Symbol] ending color name
+    # @return [String] string with gradient effect
+    def gradient(start_color, end_color)
+      return to_s unless Kolor.enabled?
+
+      start_enum = Kolor::Enum::Foreground[start_color]
+      end_enum = Kolor::Enum::Foreground[end_color]
+
+      return to_s unless start_enum && end_enum
+
+      start_code = start_enum.value
+      end_code = end_enum.value
+
+      chars = to_s.chars
+      return Kolor.clear_code if chars.empty?
+
+      result = chars.map.with_index do |char, i|
+        progress = chars.length > 1 ? i.to_f / (chars.length - 1) : 0
+        color_code = start_code + ((end_code - start_code) * progress).round
+        "\e[#{color_code}m#{char}"
+      end
+
+      result.join + Kolor.clear_code
+    end
+
+    # Rainbow colors
+    # @return [String] string with rainbow effect
+    def rainbow
+      return to_s unless Kolor.enabled?
+
+      colors = %i[red yellow green cyan blue magenta]
+      chars = to_s.chars
+
+      return Kolor.clear_code if chars.empty?
+
+      result = chars.map.with_index do |char, i|
+        color = colors[i % colors.length]
+        enum = Kolor::Enum::Foreground[color]
+        code = enum.value
+        "\e[#{code}m#{char}"
+      end
+
+      result.join + Kolor.clear_code
+    end
+
+    # Define a custom theme
+    # @param name [Symbol] theme name
+    # @param styles [Array<Symbol>] list of color and style names to apply
+    # @example
+    #   Kolor::Extra.theme(:error, :white, :on_red, :bold)
+    #   "Error!".error # => white text on red background, bold
+    def self.theme(name, *styles)
+      begin
+        Kolor::Enum::Theme.entry(name, normalize_styles(styles))
+        define_theme_method(name, styles)
+      rescue ArgumentError => e
+        if e.message =~ /already assigned to (\w+)/
+          existing = Regexp.last_match(1)
+          Kolor::Logger.warn("Theme value already registered as :#{existing}. Skipping :#{name}.")
+        else
+          Kolor::Logger.error("Theme registration failed for #{name}: #{e.message}")
+        end
+      rescue TypeError => e
+        Kolor::Logger.error("Theme registration failed for #{name}: #{e.message}")
+      end
+    end
+
+
+
+    # Defines a theme method on String and ColorizedString
+    # @param name [Symbol] theme name
+    # @param styles [Array<Symbol>] list of style methods to apply
+    # @return [void]
+    def self.define_theme_method(name, styles)
+      # Define the method on both String and ColorizedString
+      [String, Kolor::ColorizedString].each do |klass|
+        klass.class_eval do
+          # Remove existing method if present to avoid warnings
+          remove_method(name) if method_defined?(name)
+
+          # Define the theme method
+          define_method(name) do
+            # Return plain string if colors are disabled
+            return to_s unless Kolor.enabled?
+
+            # Apply each style in sequence
+            result = self
+            styles.each do |style|
+              # Verify the style method exists before calling it
+              if result.respond_to?(style)
+                result = result.public_send(style)
+              else
+                # Log warning but continue with other styles
+                Kolor::Logger.debug "Style '#{style}' not found for theme '#{name}'"
+              end
+            end
+
+            result
+          end
+        end
+      end
+
+      Kolor::Logger.debug "Defined theme method '#{name}' with styles #{styles.inspect}"
+    end
+
+    # Normalizes a list of style symbols into a structured theme hash.
+    # Extracts foreground, background, and remaining styles.
+    #
+    # @param styles [Array<Symbol>] list of style names (e.g., :green, :on_red, :bold)
+    # @return [Hash{Symbol=>Symbol, Array<Symbol>}] normalized theme structure
+    #   - :foreground → foreground color (Symbol or nil)
+    #   - :background → background color (Symbol or nil)
+    #   - :styles     → remaining style modifiers (Array<Symbol>)
+    def self.normalize_styles(styles)
+      fg = styles.find { |s| Kolor::Enum::Foreground.keys.include?(s) }
+      bg = styles.find { |s| s.to_s.start_with?('on_') }
+      rest = styles - [fg, bg].compact
+      {
+        foreground: fg,
+        background: bg&.to_s&.sub(/^on_/, '')&.to_sym,
+        styles: rest
+      }
+    end
+
+    # Returns the list of all registered theme names.
+    #
+    # @return [Array<Symbol>] list of theme keys
+    def self.themes
+      Kolor::Enum::Theme.keys
+    end
+
+    # Retrieves the configuration object for a given theme.
+    #
+    # @param name [Symbol] theme name
+    # @return [Object, nil] theme configuration or nil if not found or invalid
+    #   Expected keys:
+    #     - :foreground → foreground color (Symbol or nil)
+    #     - :background → background color (Symbol or nil)
+    #     - :styles     → style modifiers (Array<Symbol>)
+    def self.get_theme(name)
+      Kolor::Enum::Theme[name]&.value.then { |v| v.is_a?(Hash) ? v : nil }
+    end
+
+    def self.remove_theme(name)
+      theme = Kolor::Enum::Theme[name]
+      raise ArgumentError, "Theme #{name} not found" unless theme
+
+      built_in = %i[success error warning info debug]
+      raise ArgumentError, "Cannot remove built-in theme #{name}" if built_in.include?(name)
+
+      Kolor::Logger.info("Removing theme #{name}")
+      Kolor::Enum::Theme.remove(name)
+
+      [String, Kolor::ColorizedString].each do |klass|
+        klass.class_eval do
+          remove_method(name) if method_defined?(name)
+        end
+      end
+    end
+
+    # Defines all built-in themes from Kolor::Enum::Theme
+    # @return [void]
+    def self.define_all_themes
+      return if @themes_initialized
+      Kolor::Logger.info('Built-in themes initialized') unless @themes_initialized
+      @themes_initialized = true
+
+      Kolor::Enum::Theme.keys.each do |name|
+        config = Kolor::Enum::Theme[name].value
+        next unless config.is_a?(Hash)
+
+        styles = []
+        styles << config[:foreground] if config[:foreground]
+        styles << "on_#{config[:background]}".to_sym if config[:background]
+        styles += config[:styles] if config[:styles].is_a?(Array)
+
+        define_theme_method(name, styles)
+      end
+    end
+
+    # Check if a theme method is defined
+    # @param name [Symbol] theme name
+    # @return [Boolean] true if the method exists on String
+    def self.theme_defined?(name)
+      String.method_defined?(name.to_sym)
+    end
+
+    # Init built-in themes
+    self.define_all_themes
+  end
+end
+
+# Extend String class with Extra methods
+String.include(Kolor::Extra)
+Kolor::ColorizedString.include(Kolor::Extra)
+
+# Init built-in themes
+Kolor::Extra.define_all_themes

data/lib/kolor/internal/config.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+require 'fileutils'
+require_relative 'logger'
+
+module Kolor
+  # Kolor::Config handles configuration loading and initialization for Kolor.
+  #
+  # It supports Ruby-based config files located in the user's home directory:
+  #   - `.kolorrc.rb` — preferred format
+  #   - `.kolorrc` — optional alias
+  #
+  # The config file can define themes using `Kolor::Extra.theme`.
+  # If no config is found, a default file is created automatically.
+  #
+  # @example Initialize and load config
+  #   Kolor::Config.init
+  #
+  # @example Reload config manually
+  #   Kolor::Config.reload!
+  #
+  # @example Access loaded themes
+  #   Kolor::Config.themes_from_config
+  #
+  # @example Describe a theme
+  #   Kolor::Config.describe_theme(:success)
+  module Config
+    HOME_PATH = ENV['HOME'] || ENV['USERPROFILE']
+    CONFIG_FILE_RB = HOME_PATH ? File.expand_path("#{HOME_PATH}/.kolorrc.rb") : nil
+    CONFIG_FILE_ALIAS = HOME_PATH ? File.expand_path("#{HOME_PATH}/.kolorrc") : nil
+
+    class << self
+      # Initializes configuration.
+      # Creates a default config file if none exists, then loads it.
+      #
+      # @return [void]
+      def init
+        create_default_config unless config_exists?
+        load_config
+      end
+
+      # Checks whether any supported config file exists.
+      #
+      # @return [Boolean] true if a config file is found, false otherwise
+      def config_exists?
+        !config_file_path.nil?
+      end
+
+      # Creates a default Ruby config file in the user's home directory.
+      # Skips creation if a config already exists.
+      # Logs warnings if HOME is missing or creation fails.
+      #
+      # @return [void]
+      def create_default_config
+        unless HOME_PATH
+          Kolor::Logger.warn 'No home directory found'
+          return
+        end
+
+        return unless find_existing_config_file.nil?
+
+        begin
+          if CONFIG_FILE_RB.nil?
+            raise LoadError, 'Config path is invalid'
+          end
+          FileUtils.cp(default_config_path, CONFIG_FILE_RB)
+          Kolor::Logger.warn "Created default configuration file at #{CONFIG_FILE_RB}"
+        rescue StandardError, LoadError => e
+          Kolor::Logger.warn "Failed to create default config file: #{e.message}" if e.is_a?(StandardError)
+          Kolor::Logger.warn e.message if e.is_a?(LoadError)
+        end
+      end
+
+      # Loads configuration from disk.
+      # Supports only Ruby-based config files (.rb or .kolorrc).
+      # Logs info and warnings during the process.
+      #
+      # @return [void]
+      def load_config
+        config_path = config_file_path
+
+        Kolor::Logger.info "load_config called, config_path: #{config_path.inspect}"
+
+        return unless config_path
+
+        Kolor::Logger.info "Loading config from: #{config_path}"
+
+        if config_path.end_with?('.rb') || config_path.end_with?('.kolorrc')
+          Kolor::Logger.info "Detected Ruby config"
+          load_ruby_config(config_path)
+        else
+          Kolor::Logger.warn "Unknown config file type: #{config_path}"
+        end
+      rescue StandardError => e
+        Kolor::Logger.warn "Error loading config file #{config_path}: #{e.message}"
+      end
+
+      # Reloads configuration from disk.
+      #
+      # @return [void]
+      def reload!
+        load_config
+      end
+
+      # Returns the theme configuration as a hash.
+      #
+      # @param name [Symbol, String] theme name
+      # @return [Hash{Symbol => Object}, nil] theme config or nil if not found
+      def describe_theme(name)
+        Kolor::Extra.get_theme(name.to_sym)
+      end
+
+      # Returns all theme names loaded from config.
+      #
+      # @return [Array<Symbol>] list of theme keys
+      def themes_from_config
+        Kolor::Extra.themes
+      end
+
+      private
+
+      # Returns the absolute path to the default config template.
+      #
+      # @return [String] path to default .kolorrc.rb file
+      def default_config_path
+        File.expand_path('../../../default_config/.kolorrc.rb', __dir__)
+      end
+
+      # Returns the path to the first existing config file.
+      #
+      # @return [String, nil] path to config file or nil if none found
+      def config_file_path
+        find_existing_config_file
+      end
+
+      # Finds the first existing config file among supported formats.
+      #
+      # @return [String, nil] path to config file or nil
+      def find_existing_config_file
+        return CONFIG_FILE_RB if !CONFIG_FILE_RB.nil? && File.exist?(CONFIG_FILE_RB)
+        return CONFIG_FILE_ALIAS if !CONFIG_FILE_ALIAS.nil? && File.exist?(CONFIG_FILE_ALIAS)
+
+        nil
+      end
+
+      # Loads and executes a Ruby config file.
+      # Ensures Kolor::Extra is loaded before execution.
+      #
+      # @param path [String] absolute path to config file
+      # @return [void]
+      def load_ruby_config(path)
+        ensure_extra_loaded
+        load path
+      rescue SyntaxError, LoadError => e
+        raise StandardError, e.message
+      end
+
+      # Ensures Kolor::Extra is loaded and included in String and ColorizedString.
+      # This method is idempotent and safe to call multiple times.
+      #
+      # @return [void]
+      def ensure_extra_loaded
+        unless defined?(Kolor::Extra)
+          require 'kolor/extra'
+          return
+        end
+
+        String.include(Kolor::Extra) unless String.included_modules.include?(Kolor::Extra)
+
+        if defined?(Kolor::ColorizedString)
+          unless Kolor::ColorizedString.included_modules.include?(Kolor::Extra)
+            Kolor::ColorizedString.include(Kolor::Extra)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kolor/internal/enum.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# Kolor::Enum provides a declarative, type-safe registry for named values.
+# Each entry is unique by both name and value. Values can be of any type,
+# but you may optionally declare a type constraint using `type`.
+#
+# Enum entries are registered via `.entry(name, value)` and accessed via `.name` or `[]`.
+# Each entry becomes a singleton method of the class and returns an instance of the enum.
+#
+# @example Define an enum
+#   class MyEnum < Kolor::Enum
+#     type Integer
+#     entry :low, 1
+#     entry :high, 2
+#   end
+#
+# @example Access values
+#   MyEnum[:low].value        # => 1
+#   MyEnum.high.to_sym        # => :high
+#   MyEnum.low == MyEnum[:low] # => true
+module Kolor
+  class Enum
+    # @return [Object] the value associated with the enum entry
+    attr_reader :value
+
+    # Initializes a new enum instance with a given value
+    #
+    # @param value [Object] the raw value of the enum
+    def initialize(value)
+      @value = value
+    end
+
+    # Returns the symbolic name of the value as a string
+    #
+    # @return [String]
+    def to_s     = self.class.name_for(value).to_s
+
+    # Returns the symbolic name of the value as a symbol
+    #
+    # @return [Symbol]
+    def to_sym   = self.class.name_for(value)
+
+    # Returns a debug-friendly string representation
+    #
+    # @return [String]
+    def inspect  = "#<#{self.class.name} #{to_sym.inspect}:#{value.inspect}>"
+
+    # Equality based on class and value
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && other.value == value
+    end
+
+    # Alias for `==`
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    alias eql? ==
+
+    # Hash code based on value
+    #
+    # @return [Integer]
+    def hash = value.hash
+
+    class << self
+      # Declares the expected type of all enum values
+      #
+      # @param klass [Class] the type constraint for values
+      # @return [void]
+      def type(klass)
+        @value_type = klass
+      end
+
+      # Registers a new enum entry with a unique name and value
+      #
+      # @param name [Symbol, String] symbolic name of the entry
+      # @param value [Object] value of the entry
+      # @raise [ArgumentError] if name or value is already registered
+      # @raise [TypeError] if value does not match declared type
+      # @return [void]
+      def entry(name, value)
+        name = name.to_sym
+        @registry ||= {}
+        @values ||= {}
+
+        if defined?(@value_type) && !value.is_a?(@value_type)
+          raise TypeError, "Invalid value type for #{name}: expected #{@value_type}, got #{value.class}"
+        end
+
+        if @values.key?(value)
+          existing = @values[value]
+          raise ArgumentError, "Duplicate value #{value.inspect} for #{name}; already assigned to #{existing}"
+        end
+
+        if @registry.key?(name)
+          raise ArgumentError, "Duplicate name #{name}; already registered with value #{@registry[name].value.inspect}"
+        end
+
+        instance = new(value)
+        @registry[name] = instance
+        @values[value] = name
+
+        define_singleton_method(name) { instance }
+      end
+
+      # Retrieves an enum instance by name
+      #
+      # @param name [Symbol, String]
+      # @return [Kolor::Enum, nil]
+      def [](name)
+        @registry[name.to_sym]
+      end
+
+      # Resolves the symbolic name for a given value
+      #
+      # @param value [Object]
+      # @return [Symbol] name or :unknown
+      def name_for(value)
+        @values[value] || :unknown
+      end
+
+      # Returns all registered enum instances
+      #
+      # @return [Array<Kolor::Enum>]
+      def all
+        @registry.values
+      end
+
+      # Returns all registered names
+      #
+      # @return [Array<Symbol>]
+      def keys
+        @registry.keys
+      end
+
+      # Returns all raw values
+      #
+      # @return [Array<Object>]
+      def values
+        @registry.values.map(&:value)
+      end
+
+      # Removes an enum entry by name
+      #
+      # @param name [Symbol, String]
+      # @return [Kolor::Enum, nil] the removed entry or nil
+      def remove(name)
+        name = name.to_sym
+        entry = @registry.delete(name)
+        if entry
+          @values.delete_if { |_, v| v == name }
+          singleton_class.undef_method(name) if respond_to?(name)
+        end
+        entry
+      end
+    end
+  end
+end