kolor 1.0.0

data/lib/kolor/internal/logger.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'thread'
+
+module Kolor
+  # Kolor::Logger provides styled, leveled logging for terminal output.
+  #
+  # It supports five log levels: `:info`, `:warn`, `:error`, `:success`, and `:debug`.
+  # Each level has a default ANSI style, which can be overridden per message.
+  #
+  # Logging behavior is controlled by environment variables:
+  #   - `KOLOR_DEBUG` enables debug output
+  #   - `KOLOR_VERBOSE` enables info output
+  #
+  # Warnings and errors are always shown unless suppressed via `suppress!`.
+  #
+  # @example Log a warning
+  #   Kolor::Logger.warn("Something went wrong")
+  #
+  # @example Suppress warnings
+  #   Kolor::Logger.suppress!
+  module Logger
+    DEBUG_ENV_KEY = :KOLOR_DEBUG
+    INFO_ENV_KEY = :KOLOR_VERBOSE
+
+    # Default ANSI styles for each log level
+    #
+    # @return [Hash{Symbol => Array<Symbol>}]
+    DEFAULT_STYLES = {
+      info:    [:cyan],
+      warn:    [:yellow, :bold],
+      error:   [:red, :bold],
+      success: [:green],
+      debug:   [:magenta]
+    }.freeze
+
+    # Display tags for each log level
+    #
+    # @return [Hash{Symbol => String}]
+    LEVEL_TAGS = {
+      info:    'INFO',
+      warn:    'WARN',
+      error:   'ERROR',
+      success: 'OK',
+      debug:   'DEBUG'
+    }.freeze
+
+    @suppress_warnings = false
+    @mutex = Mutex.new
+
+    class << self
+      # Checks if debug output is enabled via ENV
+      #
+      # @return [Boolean]
+      def show_debug? = !ENV[DEBUG_ENV_KEY.to_s].nil?
+
+      # Checks if info output is enabled via ENV
+      #
+      # @return [Boolean]
+      def show_info?  = !ENV[INFO_ENV_KEY.to_s].nil?
+
+      # Logs an info-level message if verbose mode is enabled
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def info(message, styles = nil)
+        log(:info, message, styles) if show_info?
+      end
+
+      # Logs a debug-level message if debug mode is enabled
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def debug(message, styles = nil)
+        log(:debug, message, styles) if show_debug?
+      end
+
+      # Logs a warning message
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def warn(message, styles = nil)    log(:warn, message, styles)    end
+
+      # Logs an error message
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def error(message, styles = nil)   log(:error, message, styles)   end
+
+      # Logs a success message
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def success(message, styles = nil) log(:success, message, styles) end
+
+      # Suppresses all warnings and errors
+      #
+      # @return [void]
+      def suppress! = @suppress_warnings = true
+
+      # Enables warnings and errors
+      #
+      # @return [void]
+      def enable!   = @suppress_warnings = false
+
+      # Checks if warnings are currently suppressed
+      #
+      # @return [Boolean]
+      def suppress_warnings? = @suppress_warnings
+
+      private
+
+      # Internal log method used by all levels
+      #
+      # @param level [Symbol] log level
+      # @param message [String]
+      # @param styles [Array<Symbol>, nil]
+      # @return [void]
+      def log(level, message, styles)
+        return if @suppress_warnings
+
+        timestamp = Time.now.strftime('%Y-%m-%d %H:%M:%S')
+        tag = LEVEL_TAGS[level] || level.to_s.upcase
+        prefix = "[#{timestamp}] #{tag}: "
+
+        full = prefix + message.to_s
+        styled = apply_styles(full, styles || DEFAULT_STYLES[level])
+
+        @mutex.synchronize { $stderr.puts(styled) }
+      end
+
+      # Applies ANSI styles to a message
+      #
+      # @param message [String]
+      # @param styles [Array<Symbol>]
+      # @return [String]
+      def apply_styles(message, styles)
+        return message unless styles && message.respond_to?(:dup)
+
+        styles.reduce(message.dup) do |msg, style|
+          msg.respond_to?(style) ? msg.public_send(style) : msg
+        end
+      end
+    end
+  end
+end

data/lib/kolor/internal/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Kolor
+  VERSION = '1.0.0'
+end

data/lib/kolor.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+# @!parse
+#   class String
+#     include Kolor
+#   end
+
+
+# noinspection RubyResolve
+require 'win32/console/ansi' if Gem.win_platform?
+require_relative 'kolor/internal/version'
+require_relative 'kolor/internal/enum'
+require_relative 'kolor/enum/foreground'
+require_relative 'kolor/enum/background'
+require_relative 'kolor/enum/style'
+
+
+# Kolor provides terminal text styling using ANSI escape codes.
+#
+# Available colors (foreground and background):
+#   black, red, green, yellow, blue, magenta, cyan, white
+#
+# Available styles:
+#   bold, underline, reversed
+#
+# @example Basic usage
+#   "this is red".red
+#   "this is red with a blue background".red.on_blue
+#   "this is red with an underline".red.underline
+#   "this is really bold and really blue".bold.blue
+#
+# @example Chaining styles
+#   "complex styling".red.on_white.bold.underline
+#
+# @example All color methods
+#   string.black / string.on_black
+#   string.red / string.on_red
+#   string.green / string.on_green
+#   string.yellow / string.on_yellow
+#   string.blue / string.on_blue
+#   string.magenta / string.on_magenta
+#   string.cyan / string.on_cyan
+#   string.white / string.on_white
+#
+# @example Disabling colors (for CI/CD environments)
+#   Kolor.disable!
+#   "text".red # => "text" (no ANSI codes)
+#   Kolor.enable!
+#
+# @example Stripping ANSI codes
+#   Kolor.strip("text".red.bold) # => "text"
+module Kolor
+  # Regex to match ANSI escape codes
+  ANSI_REGEX = /\e\[[\d;]*m/.freeze
+
+  class << self
+    # Check if colorization is enabled
+    # @return [Boolean]
+    attr_reader :enabled
+    alias enabled? enabled
+
+    # Returns list of available colors
+    # @return [Array<Symbol>] sorted list of color names
+    def colors
+      @colors ||= Kolor::Enum::Foreground.keys.sort
+    end
+
+    # Enables colorization (default state)
+    # @return [Boolean] true
+    def enable!
+      @enabled = true
+    end
+
+    # Disables colorization (useful for CI/CD, logging to files, etc.)
+    # @return [Boolean] false
+    def disable!
+      @enabled = false
+    end
+
+    # Strips all ANSI escape codes from a string
+    # @param string [String] string with ANSI codes
+    # @return [String] clean string without ANSI codes
+    def strip(string)
+      result = string.to_s
+      result.gsub(ANSI_REGEX, '')
+    end
+
+    # Generates ANSI escape code for a style enum
+    # @param style_name [Symbol] symbolic name of the style (e.g. :bold, :underline)
+    # @return [String] ANSI escape code (e.g. "\e[1m") or empty string if disabled or unknown
+    def style_code(style_name)
+      return '' unless @enabled
+
+      style = Kolor::Enum::Style[style_name]
+      style ? "\e[#{style.value}m" : ''
+    end
+
+    # Generates ANSI escape code for a foreground color
+    # @param color_name [Symbol] name of the foreground color
+    # @return [String] ANSI escape code or empty string if disabled or unknown
+    def foreground_code(color_name)
+      return '' unless @enabled
+
+      color = Kolor::Enum::Foreground[color_name]
+      color ? "\e[#{color.value}m" : ''
+    end
+
+    # Generates ANSI escape code for a background color
+    # @param color_name [Symbol] name of the background color
+    # @return [String] ANSI escape code or empty string if disabled or unknown
+    def background_code(color_name)
+      return '' unless @enabled
+
+      color = Kolor::Enum::Background[color_name]
+      color ? "\e[#{color.value}m" : ''
+    end
+
+
+    # Clears all ANSI formatting
+    # @return [String] ANSI clear code or empty string if disabled
+    def clear_code
+      @enabled ? "\e[0m" : ''
+    end
+  end
+
+  # Enable by default but disable if NO_COLOR env var is set
+  @enabled = !ENV['NO_COLOR'] && !ENV['NO_COLORS']
+
+  # Wrapper class to enable method chaining with ANSI codes
+  class ColorizedString
+    attr_reader :string, :codes
+
+    def initialize(string, codes = [])
+      @string = string
+      @codes = codes
+    end
+
+    # Returns the fully colorized string
+    # @return [String] string with all ANSI codes applied
+    def to_s
+      return @string unless Kolor.enabled?
+
+      "#{@codes.join}#{@string}#{Kolor.clear_code}"
+    end
+
+    # Allow implicit string conversion
+    alias to_str to_s
+
+    # Clears all formatting and returns plain string
+    # @return [String] plain string without ANSI codes
+    def clear
+      @string
+    end
+
+    # Adds a new ANSI code to the chain
+    # @param code [String] ANSI escape code to add
+    # @return [ColorizedString] new ColorizedString with the added code
+    def add_code(code)
+      return self unless Kolor.enabled? && code
+
+      ColorizedString.new(@string, @codes + [code])
+    end
+
+    # Delegate string methods to the underlying string
+    def method_missing(method_name, *args, &block)
+      if @string.respond_to?(method_name)
+        result = @string.public_send(method_name, *args, &block)
+        result.is_a?(String) ? self.class.new(result, @codes) : result
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @string.respond_to?(method_name, include_private) || super
+    end
+
+    # Include Kolor module to get all color/style methods
+    include Kolor
+
+    private
+
+    # Override to use add_code for ColorizedString
+    def create_colorized_string(code)
+      add_code(code)
+    end
+  end
+
+  # Clears the line to the end (useful for dynamic terminal output)
+  # @return [String] string with clear-to-end-of-line code
+  def to_eol
+    return to_s unless Kolor.enabled?
+
+    str = to_s
+    modified = str.sub(/^(\e\[[\d;]*m)/, "\\1\e[0K")
+    modified == str ? "\e[0K#{str}" : modified
+  end
+
+  # Clears all ANSI formatting from the string
+  # @return [String] plain string without ANSI codes
+  def uncolorize
+    Kolor.strip(to_s)
+  end
+
+  alias decolorize uncolorize
+
+  private
+
+  # Creates a ColorizedString with the given ANSI code
+  # @param code [String] ANSI escape code to apply
+  # @return [String, ColorizedString] colorized string or self if disabled
+  def create_colorized_string(code)
+    return to_s unless Kolor.enabled?
+
+    if is_a?(ColorizedString)
+      add_code(code)
+    else
+      ColorizedString.new(self, [code])
+    end
+  end
+
+  public
+  # Generate foreground color methods
+  Kolor::Enum::Foreground.keys.each do |color|
+    define_method(color) do
+      create_colorized_string(Kolor.foreground_code(color))
+    end
+  end
+
+  # Generate background color methods (on_*)
+  Kolor::Enum::Background.keys.each do |color|
+    define_method("on_#{color}") do
+      create_colorized_string(Kolor.background_code(color))
+    end
+  end
+
+  # Generate style methods
+  Kolor::Enum::Style.keys.each do |style|
+    next if style == :clear
+
+    define_method(style) do
+      create_colorized_string(Kolor.style_code(style))
+    end
+  end
+end
+
+# Extend String class with Kolor methods
+String.include(Kolor)

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: kolor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Łasačka
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Ruby library for terminal text styling using ANSI escape codes. Supports
+  basic colors, 256-color palette, RGB/true colors, gradients, themes, and CLI.
+email:
+- saikinmirai@gmail.com
+executables:
+- kolor
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- bin/kolor
+- lib/kolor.rb
+- lib/kolor/cli.rb
+- lib/kolor/enum/background.rb
+- lib/kolor/enum/foreground.rb
+- lib/kolor/enum/style.rb
+- lib/kolor/enum/theme.rb
+- lib/kolor/extra.rb
+- lib/kolor/internal/config.rb
+- lib/kolor/internal/enum.rb
+- lib/kolor/internal/logger.rb
+- lib/kolor/internal/version.rb
+homepage: https://github.com/lasaczka/kolor
+licenses:
+- BSD-3-Clause-Attribution
+metadata:
+  homepage_uri: https://github.com/lasaczka/kolor
+  source_code_uri: https://github.com/lasaczka/kolor
+  changelog_uri: https://github.com/lasaczka/kolor/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/lasaczka/kolor/issues
+  documentation_uri: https://rubydoc.info/gems/kolor/1.0.0
+  kolor:extra_status: experimental
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Modern terminal text styling with ANSI codes
+test_files: []