sinlog 0.0.5 → 0.0.6

data/lib/sinlog/log_ext.rb

@@ -1,62 +1,46 @@
 # frozen_string_literal: true
 
-class Sinlog
-  # LogExt is a Refinement that adds convenient logging methods to all objects.
-  #
-  # When activated with `using Sinlog::LogExt`, any object can call:
-  #
+module Sinlog
   # == Overview
   #
-  # * `log_dbg`   – Logs the object at DEBUG level
-  # * `log_info`  – Logs the object at INFO level
-  # * `log_warn`  – Logs the object at WARN level
-  # * `log_err`   – Logs the object at ERROR level
-  # * `log_fatal` – Logs the object at FATAL level
-  # * `log_unk`   – Logs the object at UNKNOWN level
-  #
-  # == Example
-  #
-  #     require 'sinlog'
-  #
-  #     class A
-  #       using Sinlog::LogExt
-  #       def demo
-  #         "Something happened".log_warn
-  #       end
-  #     end
+  # * `log_dbg`   – DEBUG
+  # * `log_info`  – INFO
+  # * `log_warn`  – WARN
+  # * `log_err`   – ERROR
+  # * `log_fatal` – FATAL
+  # * `log_unk`   – UNKNOWN
   #
   module LogExt
-    refine Object do
-      # Logs the current object at *debug* level using Sinlog.logger
-      def log_dbg
-        Sinlog.logger.debug(self)
-      end
+    # Logs the current object at *debug* level using Sinlog.logger
+    def log_dbg
+      Sinlog.logger.debug(self)
+    end
 
-      # Logs the current object at *information* level using Sinlog.logger
-      def log_info
-        Sinlog.logger.info(self)
-      end
+    # Logs the current object at *information* level using Sinlog.logger
+    def log_info
+      Sinlog.logger.info(self)
+    end
 
-      # Logs the current object at *warning* level using Sinlog.logger
-      def log_warn
-        Sinlog.logger.warn(self)
-      end
+    # Logs the current object at *warning* level using Sinlog.logger
+    def log_warn
+      Sinlog.logger.warn(self)
+    end
 
-      # Logs the current object at *error* level using Sinlog.logger
-      def log_err
-        Sinlog.logger.error(self)
-      end
+    # Logs the current object at *error* level using Sinlog.logger
+    def log_err
+      Sinlog.logger.error(self)
+    end
 
-      # Logs the current object at *fatal* level using Sinlog.logger
-      def log_fatal
-        Sinlog.logger.fatal(self)
-      end
+    # Logs the current object at *fatal* level using Sinlog.logger
+    def log_fatal
+      Sinlog.logger.fatal(self)
+    end
 
-      # Logs the current object at *unknown* level using Sinlog.logger
-      def log_unk
-        Sinlog.logger.unknown(self)
-      end
-      # -----
+    # Logs the current object at *unknown* level using Sinlog.logger
+    def log_unk
+      Sinlog.logger.unknown(self)
     end
   end
+  # -----
+  private_constant :LogExt
 end

data/lib/sinlog/loggable.rb

@@ -1,57 +1,153 @@
 # frozen_string_literal: true
 
-class Sinlog
+module Sinlog
   # Provides logging helpers for any object.
   #
   # == Overview
   #
-  # * `log_dbg`   – Logs the object at DEBUG level
-  # * `log_info`  – Logs the object at INFO level
-  # * `log_warn`  – Logs the object at WARN level
-  # * `log_err`   – Logs the object at ERROR level
-  # * `log_fatal` – Logs the object at FATAL level
-  # * `log_unk`   – Logs the object at UNKNOWN level
+  # * `log_dbg`   – DEBUG
+  # * `log_info`  – INFO
+  # * `log_warn`  – WARN
+  # * `log_err`   – ERROR
+  # * `log_fatal` – FATAL
+  # * `log_unk`   – UNKNOWN
   #
   # == Example
   #
   #     require 'sinlog'
   #
-  #     include Sinlog::Loggable
+  #     include Sinlog::Mixin
   #
   #     "A debug message".log_dbg
   #     "Hello, world".log_info
   #
-  module Loggable
-    # Logs the current object at *debug* level using Sinlog.logger
-    def log_dbg
-      Sinlog.logger.debug(self)
-    end
-
-    # Logs the current object at *information* level using Sinlog.logger
-    # logger.info
-    def log_info
-      Sinlog.logger.info(self)
-    end
-
-    # Logs the current object at *warning* level using Sinlog.logger
-    def log_warn
-      Sinlog.logger.warn(self)
+  #     Object.method_defined?(:log_warn) #=> true
+  #
+  module Mixin
+    def self.included(_host)
+      ::Object.include(LogExt)
     end
+  end
 
-    # Logs the current object at *error* level using Sinlog.logger
-    def log_err
-      Sinlog.logger.error(self)
+  # Provides logging helpers for any object.
+  #
+  # - The main difference from `Sinlog::Mixin` is that `Refin` uses Refinements instead of Mixins.
+  #   - You need to activate it with `using Sinlog::Refin`
+  #   - rather than `include Sinlog::Mixin`.
+  #
+  # == Source
+  #
+  #     refine ::Object { import_methods LogExt }
+  #
+  # == Overview
+  #
+  # * `log_dbg`   – DEBUG
+  # * `log_info`  – INFO
+  # * `log_warn`  – WARN
+  # * `log_err`   – ERROR
+  # * `log_fatal` – FATAL
+  # * `log_unk`   – UNKNOWN
+  #
+  # == Example
+  #
+  #     require 'sinlog'
+  #
+  #     module A
+  #       module_function
+  #       using Sinlog::Refin
+  #
+  #       def demo = "Something happened".log_warn
+  #       def respon_to_log_dbg? = [].respond_to? :log_dbg
+  #     end
+  #
+  #     A.demo
+  #       # => [WARN] 11:17:38.024 Something happened
+  #       # => (WARN is displayed in yellow highlight; 11:17:38.024 is the current time and may vary)
+  #
+  #     A.respon_to_log_dbg?  # => true
+  #     [].respond_to? :log_dbg #=> false
+  #
+  module Refin
+    refine ::Object do
+      import_methods LogExt
     end
+  end
 
-    # Logs the current object at *fatal* level using Sinlog.logger
-    def log_fatal
-      Sinlog.logger.fatal(self)
+  # Provids convenient logging methods.
+  #
+  # Similar to `Sinlog::Refin`, but methods omit the `log_` prefix.
+  #
+  # For example:
+  #   * `"msg".err` instead of `"msg".log_err`;
+  #   * `"msg".warn` instead of `"msg".log_warn`
+  #
+  # == Source
+  #
+  #     refine ::Object { import_methods LogShortExt }
+  #
+  # == Overview
+  #
+  # * `dbg`   – DEBUG
+  # * `info`  – INFO
+  # * `warn`  – WARN
+  # * `err`   – ERROR
+  # * `fatal` – FATAL
+  # * `unk`   – UNKNOWN
+  #
+  # == Example
+  #
+  #     require 'sinlog'
+  #
+  #     module A
+  #       module_function
+  #       using Sinlog::ShortRefin
+  #
+  #       def demo = "Something happened".warn
+  #       def respon_to_dbg? = [].respond_to? :dbg
+  #     end
+  #
+  #     A.demo
+  #       # => [WARN] 11:17:38.024 Something happened
+  #       # => (WARN is displayed in yellow highlight; 11:17:38.024 is the current time and may vary)
+  #
+  #     A.respon_to_dbg?  # => true
+  #     [].respond_to? :dbg #=> false
+  #
+  module ShortRefin
+    refine ::Object do
+      import_methods LogShortExt
     end
+  end
 
-    # Logs the current object at *unknown* level using Sinlog.logger
-    def log_unk
-      Sinlog.logger.unknown(self)
+  # Provids convenient logging methods.
+  #
+  # Similar to `Sinlog::Mixin`, but methods omit the `log_` prefix.
+  #
+  # Note: Since mixin monkey patching pollutes the global scope, use `include Sinlog::ShortMixin` with caution.
+  #
+  # == Overview
+  #
+  # * `dbg`   – DEBUG
+  # * `info`  – INFO
+  # * `warn`  – WARN
+  # * `err`   – ERROR
+  # * `fatal` – FATAL
+  # * `unk`   – UNKNOWN
+  #
+  # == Example
+  #
+  #     require 'sinlog'
+  #
+  #     include Sinlog::ShortMixin
+  #
+  #     "A debug message".dbg
+  #     "Hello, world".info
+  #
+  #     Object.method_defined?(:err) #=> true
+  #
+  module ShortMixin
+    def self.included(_host)
+      ::Object.include(LogShortExt)
     end
-    # -----
   end
 end

data/lib/sinlog/logger.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Logger Singleton Class
+module Sinlog
+  class Logger
+    require 'singleton'
+
+    include Singleton
+    attr_reader :logger
+
+    # Example:
+    #
+    #     logger = Sinlog::Logger.instance.logger
+    #     logger.info "Information"
+    #     logger.debug "This is a debug message"
+    #
+    # The log output format will be similar to:
+    #
+    #   [INFO] 21:29:22.004  Information
+    #   [DEBUG] 21:29:22.005  This is a debug message
+    #
+    # Where "INFO" is highlighted in cyan and "DEBUG" is highlighted in blue.
+    #
+    # The default log level is set based on the RUBY_LOG environment variable.
+    # If this variable is not set, the default level is DEBUG.
+    def initialize
+      @logger = StdLogger.new($stderr)
+      set_level_from_env!
+      @logger.formatter = Kernel.proc do |severity, datetime, progname, msg|
+        color = COLORS[severity.downcase.to_sym]
+        reset = COLORS[:unknown]
+        formatted_datetime = datetime.strftime('%H:%M:%S.%L')
+        prog = format_prog_name(progname)
+        "[#{color}#{severity}#{reset}] #{formatted_datetime} #{prog}#{msg}\n"
+      end
+    end
+
+    def self.logger
+      instance.logger
+    end
+
+    # Set the `@logger.level` (**log level**) based on the value of an environment variable.
+    #
+    # If env_name is not specified, it reads the value of the `RUBY_LOG` environment variable.
+    #
+    # - If the value exists, it is converted to lowercase, then to a symbol, and looked up in the LV hash;
+    # - If it does not exist, the default level is DEBUG(0);
+    # - If the lookup result is invalid, the level is set to ERROR(3);
+    # - If the environment variable value is empty, the lookup result will be invalid,
+    #   and the level will be set to ERROR(3).
+    #
+    # Example:
+    #
+    #     ENV["XX_LOG"] = "info" # or setenv in posix-sh: export XX_LOG=info
+    #     logger = Sinlog::Logger.instance.tap { it.set_level_from_env!("XX_LOG") }.logger
+    #
+    #     logger.debug "This message will not be displayed because the current log level is info"
+    #     logger.info "Hello!"
+    def set_level_from_env!(env_name = 'RUBY_LOG')
+      env_str = ENV[env_name]&.downcase || 'debug'
+
+      Sinlog
+        .to_log_level(env_str)
+        .then { @logger.level = _1 }
+    end
+
+    private
+
+    def format_prog_name(progname)
+      return '' if progname.to_s.empty?
+
+      green = "\e[32m"
+      reset = "\e[0m"
+      space = ' '
+      "<#{green}#{progname}#{reset}>#{space}"
+    end
+  end
+end

data/lib/sinlog/module_fn.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Sinlog
+  module_function
+
+  # => Integer
+  #
+  # == Example
+  #
+  #     require 'sinlog'
+  #
+  #     # values: 'debug', 'info', 'warn', 'error', 'fatal', 'unknown'
+  #     Sinlog.to_log_level('dbg') #=> LV[:debug] => 0
+  #     Sinlog.to_log_level('info') #=> LV[:info] => 1
+  #
+  def to_log_level(level) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+    case level
+      when 0..5
+        level
+      when 'debug', 'dbg', :dbg
+        LV[:debug]
+      when 'info', 'information'
+        LV[:info]
+      when 'warn', 'warning'
+        LV[:warn]
+      when 'err', 'error', :err
+        LV[:error]
+      when 'fatal'
+        LV[:fatal]
+      when 'unk', 'unknown', :unk
+        LV[:unknown]
+      when Symbol
+        LV.fetch(level, LV[:error])
+      else
+        LV[:error]
+    end
+  end
+
+  # => Sinlog::Logger.instance
+  def instance
+    Sinlog::Logger.instance
+  end
+
+  # => ::Logger
+  #
+  # == English
+  #
+  # Creates a new ::Logger instance.
+  #
+  # You can configure the log level through parameters.
+  #
+  # - env_name
+  #   - Type: String
+  #   - Specifies the name of an environment variable.
+  #   - If set to nil, the program will attempt to read `RUBY_LOG` and set the log level accordingly.
+  #     - Example: logger(env_name: nil)
+  #       - If the user runs `RUBY_LOG=debug ./[your-script].rb`
+  #       - The log level will be set to `debug`.
+  #     - Example: logger(env_name: "XX_CLI_LOG")
+  #       - If the user runs `XX_CLI_LOG=warn ./[your-script].rb`
+  #       - The log level will be set to `warn`.
+  #
+  # - level
+  #   - Type: Integer OR String OR Symbol
+  #   - The level parameter takes precedence over env_name.
+  #     - If both level and env_name are provided, the program will parse level first and return early.
+  #
+  # == 中文
+  #
+  # 创建一个新的 ::Logger 实例。
+  #
+  # 我们可以通过参数来配置日志级别。
+  #
+  # - env_name
+  #   - 类型: String
+  #   - 指定特定的环境变量名称
+  #   - 当其为 nil 时，程序默认会尝试获取 RUBY_LOG 的值，并设置日志级别。
+  #     - 假设 logger(env_name: nil)
+  #       - 若用户调用 `RUBY_LOG=debug ./[your-script].rb`
+  #       - 则日志级别为 debug。
+  #     - 假设 logger(env_name: "XX_CLI_LOG")
+  #       - 若用户调用 `XX_CLI_LOG=warn ./[your-script].rb`
+  #       - 则日志级别为 warn。
+  # - level
+  #   - 类型: Integer OR String OR Symbol
+  #   - level 的优先级要高于 env_name
+  #     - 若 level 和 env_name 都不为 nil, 则程序会优先解析 level，并提前 return。
+  #
+  # == Example
+  #
+  #     require 'sinlog'
+  #
+  #     # level values:
+  #     #   - "debug"
+  #     #   - "dbg"
+  #     #   - "info"
+  #     #   - "warn"
+  #     #   - "error"
+  #     #   - "err"
+  #     #   - "fatal"
+  #     #   - Integer (e.g., Sinlog::LV[:debug])
+  #
+  #     log = Sinlog.logger(level: "dbg")
+  #     log.level == Sinlog::LV[:debug]  #=> true
+  #     a = 3
+  #     log.debug "a=#{a}"
+  #
+  #     log = Sinlog.logger(level: 'warn')
+  #     log.level == Sinlog::LV[:warn]  #=> true
+  #     log.error "Failed to open file."
+  #
+  #     ENV["CUSTOM_LOG"] = 'info'
+  #     log = Sinlog.logger(env_name: "CUSTOM_LOG")
+  #     log.level == Sinlog::LV[:info]  #=> true
+  #
+  #     log = Sinlog.logger(env_name: "CUSTOM_LOG", level: "error")
+  #     log.level == Sinlog::LV[:error]  #=> true
+  #
+  def logger(env_name: nil, level: nil)
+    std_logger = instance.logger
+
+    # if level != nil
+    return std_logger.tap { _1.level = to_log_level(level) } unless level.nil?
+
+    # if env_name != nil
+    instance.set_level_from_env!(env_name) unless env_name.nil?
+
+    std_logger
+  end
+end

data/lib/sinlog/short_ext.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sinlog
+  # LogShortExt is a module that adds convenient logging methods.
+  #
+  # Similar to LogExt, but methods omit the `log_` prefix.
+  #
+  # For example:
+  #   * `"msg".err` instead of `"msg".log_err`;
+  #   * `"msg".warn` instead of `"msg".log_warn`
+  #
+  # We can activate it with `using Sinlog::ShortRefin`
+  #
+  # == Overview
+  #
+  # * `dbg`   – DEBUG
+  # * `info`  – INFO
+  # * `warn`  – WARN
+  # * `err`   – ERROR
+  # * `fatal` – FATAL
+  # * `unk`   – UNKNOWN
+  module LogShortExt
+    # Logs the current object at *debug* level using Sinlog.logger
+    def dbg
+      Sinlog.logger.debug(self)
+    end
+
+    # Logs the current object at *information* level using Sinlog.logger
+    def info
+      Sinlog.logger.info(self)
+    end
+
+    # Logs the current object at *warning* level using Sinlog.logger
+    def warn
+      Sinlog.logger.warn(self)
+    end
+
+    # Logs the current object at *error* level using Sinlog.logger
+    def err
+      Sinlog.logger.error(self)
+    end
+
+    # Logs the current object at *fatal* level using Sinlog.logger
+    def fatal
+      Sinlog.logger.fatal(self)
+    end
+
+    # Logs the current object at *unknown* level using Sinlog.logger
+    def unk
+      Sinlog.logger.unknown(self)
+    end
+    # -----
+  end
+  private_constant :LogShortExt
+end

data/lib/sinlog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-class Sinlog
-  VERSION = '0.0.5'
+module Sinlog
+  VERSION = '0.0.6'
 end

data/lib/sinlog.rb

@@ -4,17 +4,19 @@
 #
 # The following modules provide different ways to add logging capabilities:
 #
-# * Loggable      : A mixin module. Include it in your class to add logging methods with the `log_` prefix.
-# * LogExt        : A refinement. Activate it with `using` to add logging methods with the `log_` prefix.
-# * LogShortExt   : A refinement. Similar to LogExt, but methods omit the `log_` prefix.
+# * Refin        : A refinement. Activate it with `using` to add logging methods with the `log_` prefix.
+# * ShortRefin   : A refinement. Similar to `Sinlog::Refin`, but methods omit the `log_` prefix.
+# * Mixin        : A mixin module. It's a global object monkey patch, use `include Sinlog::Mixin` with caution.
+# * ShortMixin   : A mixin module. Similar to `Sinlog::Mixin`, but methods omit the `log_` prefix.
 #
-# === Comparison Table
+# === Comparison Table (Monkey Patching)
 #
-#  Module         | Type        | Activation    | Method Naming
-#  -------------- | ----------  | ------------  | -------------------------
-#  Loggable       | Mixin       | include       | log_dbg, log_info, etc.
-#  LogExt         | Refinement  | using         | log_dbg, log_info, etc.
-#  LogShortExt    | Refinement  | using         | dbg, info, warn, err, fatal, unk
+# | Module     | Type       | Activation | Method Naming                                            |
+# | ---------- | ---------- | ---------- | -------------------------------------------------------- |
+# | Mixin      | Mixin      | include    | log_dbg, log_info, log_warn, log_err, log_fatal, log_unk |
+# | Refin      | Refinement | using      | log_dbg, log_info, log_warn, log_err, log_fatal, log_unk |
+# | ShortMixin | Mixin      | include    | dbg, info, warn, err, fatal, unk                         |
+# | ShortRefin | Refinement | using      | dbg, info, warn, err, fatal, unk                         |
 #
 # == Examples
 #
@@ -29,21 +31,31 @@
 # === Mixin
 #
 #     require 'sinlog'
-#     include Sinlog::Loggable
+#     include Sinlog::Mixin
+#
 #     "Hello".log_info
+#     "World".log_dbg
 #
 # === Refinement
 #
 #     require 'sinlog'
-#     using Sinlog::LogShortExt
-#     "Hello".info
+#
+#     using Sinlog::Refin
+#     "Foo".log_info
+#
+#     using Sinlog::ShortRefin
+#     "Bar".warn
 #
 # Read more: https://github.com/2moe/sinlog-gem
-class Sinlog; end
+module Sinlog; end
 
 require_relative 'sinlog/version'
 
-require_relative 'sinlog/init'
-require_relative 'sinlog/loggable'
+require_relative 'sinlog/consts'
+require_relative 'sinlog/logger'
+require_relative 'sinlog/module_fn'
+
 require_relative 'sinlog/log_ext'
-require_relative 'sinlog/log_short_ext'
+require_relative 'sinlog/short_ext'
+
+require_relative 'sinlog/loggable'