sinlog 0.0.5 → 0.0.7

data/lib/sinlog/03_module_fn.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Sinlog
+  module_function
+
+  # @param level [Integer, String, Symbol, nil] Log Level.
+  #
+  # @return [Integer] the log level as an integer.
+  #
+  # @note If `level` is `nil`, returns `Sinlog.logger.level`.
+  #
+  # @example
+  #
+  #     require 'sinlog'
+  #
+  #     # optional values:
+  #     #    'debug', 'info', 'warn', 'error', 'fatal', 'unknown',
+  #     #    'dbg', 'information', 'warning', 'err', 'unk',
+  #     #    '0', '1', '2', '3', '4', '5'
+  #
+  #     Sinlog.as_log_level(:dbg) #=> LV[:debug] => 0
+  #     Sinlog.as_log_level('info') #=> LV[:info] => 1
+  def as_log_level(level = nil) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+    level = Sinlog.logger.level if level.nil?
+    case level
+      when 0..5
+        level
+      when '0', '1', '2', '3', '4', '5'
+        level.to_i
+      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
+
+  # @return [<Sinlog::Logger>] `=> Sinlog::Logger.instance`
+  def instance
+    Sinlog::Logger.instance
+  end
+
+  # Configures and returns the `Sinlog.instance.logger`.
+  #
+  # @param level [Integer, String, Symbol, nil]  Log Level.
+  # @param env_name [#to_s]  Name of the environment variable.
+  # @return [StdLogger]
+  #
+  # ## English
+  #
+  #
+  # You can configure the log level through parameters.
+  #
+  # - env_name
+  #   - 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
+  #   - 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.
+  #
+  # ## 中文
+  #
+  # 配置并获取 `Sinlog.instance.logger`。
+  #
+  # 我们可以通过参数来配置日志级别。
+  #
+  # - env_name
+  #   - 指定特定的环境变量名称
+  #   - 当其为 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
+  #   - level 的优先级要高于 env_name
+  #     - 若 level 和 env_name 都不为 nil, 则程序会优先解析 level，并提前 return。
+  #
+  # @see Sinlog::Logger.logger
+  #
+  # @example
+  #
+  #     require 'sinlog'
+  #
+  #     # optional level values:
+  #     #   - "debug"
+  #     #   - "dbg"
+  #     #   - "info"
+  #     #   - "warn"
+  #     #   - "error"
+  #     #   - "err"
+  #     #   - "fatal"
+  #     #   - "unknown"
+  #     #   - "unk"
+  #     #   - Integer (e.g., Sinlog::LV[:debug])
+  #
+  #     log = Sinlog.logger(level: "dbg")
+  #     log.level == Sinlog::LV[:debug]  #=> true
+  #     a = "Foo"
+  #     log.debug "a=#{a}"
+  #
+  #     using Sinlog::Refin
+  #     Sinlog.logger(level: 'warn')
+  #     log.level == Sinlog::LV[:warn]  #=> true
+  #     "Bar".log_warn
+  #
+  #     ENV["CUSTOM_LOG"] = 'info'
+  #     log = Sinlog.logger(env_name: "CUSTOM_LOG")
+  #     log.level == Sinlog::LV[:info]  #=> true
+  #     "Baz".log_info
+  #
+  #     log = Sinlog.logger(level: "error", env_name: "CUSTOM_LOG")
+  #     log.level == Sinlog::LV[:error]  #=> true
+  #     "foobar".log_err
+  #
+  def logger(level: nil, env_name: nil)
+    std_logger = instance.logger
+
+    # if level != nil
+    return std_logger.tap { _1.level = as_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/04_log_ext.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Sinlog
+  # @private
+  #
+  # == Methods
+  #
+  # - `#log_dbg`   – DEBUG
+  # - `#log_info`  – INFO
+  # - `#log_warn`  – WARN
+  # - `#log_err`   – ERROR
+  # - `#log_fatal` – FATAL
+  # - `#log_unk`   – UNKNOWN
+  module LogExt
+    def log_dbg
+      Sinlog.logger.debug(self)
+    end
+
+    def log_info
+      Sinlog.logger.info(self)
+    end
+
+    def log_warn
+      Sinlog.logger.warn(self)
+    end
+
+    def log_err
+      Sinlog.logger.error(self)
+    end
+
+    def log_fatal
+      Sinlog.logger.fatal(self)
+    end
+
+    def log_unk
+      Sinlog.logger.unknown(self)
+    end
+  end
+  # -----
+  private_constant :LogExt
+end

data/lib/sinlog/05_short_ext.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Sinlog
+  # @private
+  #
+  # 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`
+  #
+  #
+  # == Methods
+  #
+  # - `#dbg`   – DEBUG
+  # - `#info`  – INFO
+  # - `#warn`  – WARN
+  # - `#err`   – ERROR
+  # - `#fatal` – FATAL
+  # - `#unk`   – UNKNOWN
+  module LogShortExt
+    def dbg
+      Sinlog.logger.debug(self)
+    end
+
+    def info
+      Sinlog.logger.info(self)
+    end
+
+    def warn
+      Sinlog.logger.warn(self)
+    end
+
+    def err
+      Sinlog.logger.error(self)
+    end
+
+    def fatal
+      Sinlog.logger.fatal(self)
+    end
+
+    def unk
+      Sinlog.logger.unknown(self)
+    end
+    # -----
+  end
+  private_constant :LogShortExt
+end

data/lib/sinlog/06_loggable.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Sinlog
+  # Provides logging helpers for any object.
+  #
+  # @see Sinlog::Refin
+  # @see Sinlog::ShortMixin
+  #
+  # ## Methods
+  #
+  #   - `Object#log_dbg`   – DEBUG
+  #   - `Object#log_info`  – INFO
+  #   - `Object#log_warn`  – WARN
+  #   - `Object#log_err`   – ERROR
+  #   - `Object#log_fatal` – FATAL
+  #   - `Object#log_unk`   – UNKNOWN
+  #
+  # @example
+  #
+  #     require 'sinlog'
+  #
+  #     include Sinlog::Mixin
+  #
+  #     "A debug message".log_dbg
+  #     "Hello, world".log_info
+  #
+  #     Object.method_defined?(:log_warn) #=> true
+  #
+  module Mixin
+    def self.included(_host) = ::Object.include(LogExt)
+  end
+
+  # @see Sinlog::Mixin
+  # @see Sinlog::ShortRefin
+  #
+  # @note 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 }
+  #
+  # ## Methods
+  #
+  # - `#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
+
+  # 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 }
+  #
+  # ## Methods
+  #
+  # - `#dbg`   – DEBUG
+  # - `#info`  – INFO
+  # - `#warn`  – WARN
+  # - `#err`   – ERROR
+  # - `#fatal` – FATAL
+  # - `#unk`   – UNKNOWN
+  #
+  # @see Sinlog::Refin
+  # @see Sinlog::ShortMixin
+  #
+  # @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
+
+  # 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.
+  #
+  # @see Sinlog::Mixin
+  # @see Sinlog::ShortRefin
+  #
+  # ## Methods
+  #
+  # - `Object#dbg`   – DEBUG
+  # - `Object#info`  – INFO
+  # - `Object#warn`  – WARN
+  # - `Object#err`   – ERROR
+  # - `Object#fatal` – FATAL
+  # - `Object#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

data/lib/sinlog/07_proc.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Provides a set of reusable **unary lambdas**.
+#
+# @note  Each function is implemented using `Kernel.lambda(&:log_xxx)`
+#
+# @example
+#
+#     Log = Sinlog::Proc
+#     'debug'.tap &Log.dbg
+#     'information'.tap &Log.info
+#     'warning'.tap &Log.warn
+#     'error'.tap &Log.err
+#     'fatal'.tap &Log.fatal
+#     'unknown'.tap &Log.unk
+#
+module Sinlog::Proc
+  module_function
+
+  # + Object#log_*
+  using Sinlog::Refin
+
+  # Returns a lambda that calls `log_dbg` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example Basic usage
+  #
+  #   Log = Sinlog::Proc
+  #
+  #   "debug message".tap &Log.dbg
+  #   # OR: Log.dbg["debug message"]
+  #   # OR: Log.dbg.call("debug message")
+  #
+  def dbg
+    Kernel.lambda(&:log_dbg)
+  end
+
+  # Returns a lambda that calls `log_info` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example
+  #
+  #     "info message".tap &Sinlog::Proc.info
+  def info
+    Kernel.lambda(&:log_info)
+  end
+
+  # Returns a lambda that calls `log_warn` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example
+  #
+  #     "warning message".tap &Sinlog::Proc.warn
+  def warn
+    Kernel.lambda(&:log_warn)
+  end
+
+  # Returns a lambda that calls `log_err` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example
+  #
+  #     "Error message".tap &Sinlog::Proc.err
+  def err
+    Kernel.lambda(&:log_err)
+  end
+
+  # Returns a lambda that calls `log_fatal` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example
+  #
+  #     "Fatal Error message".tap &Sinlog::Proc.fatal
+  def fatal
+    Kernel.lambda(&:log_fatal)
+  end
+
+  # Returns a lambda that calls `log_unk` on the given object.
+  #
+  # @return [::Proc] `.call(Object)` => Boolean
+  #
+  # @example
+  #
+  #     "Unknown Level".tap &Sinlog::Proc.unk
+  def unk
+    Kernel.lambda(&:log_unk)
+  end
+end

data/lib/sinlog/08_module_short_ext.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Provides a set of reusable **unary functions** that call logging methods.
+#
+# - `dbg`   – DEBUG
+# - `info`  – INFO
+# - `warn`  – WARN
+# - `err`   – ERROR
+# - `fatal` – FATAL
+# - `unk`   – UNKNOWN
+#
+# -------------
+#
+# @example
+#
+#     Sinlog.dbg 'debug'
+#     Sinlog.info 'information'
+#     Sinlog.warn 'warning'
+#     Sinlog.err 'error'
+#     Sinlog.fatal 'fatal'
+#     Sinlog.unk 'unknown'
+#
+module Sinlog
+  module_function
+
+  # + Object#log_*
+  using Sinlog::Refin
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example Basic usage
+  #
+  #   Sinlog.dbg "This is a debug message"
+  #
+  def dbg(obj)
+    obj.log_dbg
+  end
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #     Sinlog.info "info message"
+  def info(obj)
+    obj.log_info
+  end
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #     Sinlog.warn "warning message"
+  def warn(obj)
+    obj.log_warn
+  end
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #     Sinlog.err "Error message"
+  def err(obj)
+    obj.log_err
+  end
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #     Sinlog.fatal "Fatal Error message"
+  def fatal(obj)
+    obj.log_fatal
+  end
+
+  # @param obj [Object]
+  # @return [Boolean]
+  #
+  # @example
+  #
+  #     Sinlog.unk "Unknown Level"
+  def unk(obj)
+    obj.log_unk
+  end
+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.7'
 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,33 @@
 # === 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/log_ext'
-require_relative 'sinlog/log_short_ext'
+require_relative 'sinlog/01_consts'
+require_relative 'sinlog/02_logger'
+require_relative 'sinlog/03_module_fn'
+
+require_relative 'sinlog/04_log_ext'
+require_relative 'sinlog/05_short_ext'
+
+require_relative 'sinlog/06_loggable'
+require_relative 'sinlog/07_proc'
+require_relative 'sinlog/08_module_short_ext'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sinlog
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - 2moe
@@ -15,19 +15,19 @@ extensions: []
 extra_rdoc_files: []
 files:
 - License
+- docs/Changelog.md
 - docs/Readme-zh.md
 - docs/Readme.md
 - lib/sinlog.rb
-- lib/sinlog/init.rb
-- lib/sinlog/log_ext.rb
-- lib/sinlog/log_short_ext.rb
-- lib/sinlog/loggable.rb
+- lib/sinlog/01_consts.rb
+- lib/sinlog/02_logger.rb
+- lib/sinlog/03_module_fn.rb
+- lib/sinlog/04_log_ext.rb
+- lib/sinlog/05_short_ext.rb
+- lib/sinlog/06_loggable.rb
+- lib/sinlog/07_proc.rb
+- lib/sinlog/08_module_short_ext.rb
 - lib/sinlog/version.rb
-- rbi/sinlog/init.rbi
-- rbi/sinlog/log_ext.rbi
-- rbi/sinlog/log_short_ext.rbi
-- rbi/sinlog/loggable.rbi
-- rbi/sinlog/version.rbi
 homepage: https://github.com/2moe/sinlog-gem
 licenses:
 - MIT