sinlog 0.0.6 → 0.0.7

data/lib/sinlog/{module_fn.rb → 03_module_fn.rb}

@@ -3,20 +3,30 @@
 module Sinlog
   module_function
 
-  # => Integer
+  # @param level [Integer, String, Symbol, nil] Log Level.
   #
-  # == Example
+  # @return [Integer] the log level as an integer.
+  #
+  # @note If `level` is `nil`, returns `Sinlog.logger.level`.
+  #
+  # @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
+  #     # optional values:
+  #     #    'debug', 'info', 'warn', 'error', 'fatal', 'unknown',
+  #     #    'dbg', 'information', 'warning', 'err', 'unk',
+  #     #    '0', '1', '2', '3', '4', '5'
   #
-  def to_log_level(level) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+  #     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'
@@ -36,21 +46,23 @@ module Sinlog
     end
   end
 
-  # => Sinlog::Logger.instance
+  # @return [<Sinlog::Logger>] `=> Sinlog::Logger.instance`
   def instance
     Sinlog::Logger.instance
   end
 
-  # => ::Logger
+  # Configures and returns the `Sinlog.instance.logger`.
   #
-  # == English
+  # @param level [Integer, String, Symbol, nil]  Log Level.
+  # @param env_name [#to_s]  Name of the environment variable.
+  # @return [StdLogger]
+  #
+  # ## 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)
@@ -61,36 +73,35 @@ module Sinlog
   #       - 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 实例。
+  # 配置并获取 `Sinlog.instance.logger`。
   #
   # 我们可以通过参数来配置日志级别。
   #
   # - env_name
-  #   - 类型: String
   #   - 指定特定的环境变量名称
   #   - 当其为 nil 时，程序默认会尝试获取 RUBY_LOG 的值，并设置日志级别。
   #     - 假设 logger(env_name: nil)
   #       - 若用户调用 `RUBY_LOG=debug ./[your-script].rb`
-  #       - 则日志级别为 debug。
+  #       - 则日志级别为 debug
   #     - 假设 logger(env_name: "XX_CLI_LOG")
   #       - 若用户调用 `XX_CLI_LOG=warn ./[your-script].rb`
-  #       - 则日志级别为 warn。
+  #       - 则日志级别为 warn
   # - level
-  #   - 类型: Integer OR String OR Symbol
   #   - level 的优先级要高于 env_name
   #     - 若 level 和 env_name 都不为 nil, 则程序会优先解析 level，并提前 return。
   #
-  # == Example
+  # @see Sinlog::Logger.logger
+  #
+  # @example
   #
   #     require 'sinlog'
   #
-  #     # level values:
+  #     # optional level values:
   #     #   - "debug"
   #     #   - "dbg"
   #     #   - "info"
@@ -98,29 +109,34 @@ module Sinlog
   #     #   - "error"
   #     #   - "err"
   #     #   - "fatal"
+  #     #   - "unknown"
+  #     #   - "unk"
   #     #   - Integer (e.g., Sinlog::LV[:debug])
   #
   #     log = Sinlog.logger(level: "dbg")
   #     log.level == Sinlog::LV[:debug]  #=> true
-  #     a = 3
+  #     a = "Foo"
   #     log.debug "a=#{a}"
   #
-  #     log = Sinlog.logger(level: 'warn')
+  #     using Sinlog::Refin
+  #     Sinlog.logger(level: 'warn')
   #     log.level == Sinlog::LV[:warn]  #=> true
-  #     log.error "Failed to open file."
+  #     "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(env_name: "CUSTOM_LOG", level: "error")
+  #     log = Sinlog.logger(level: "error", env_name: "CUSTOM_LOG")
   #     log.level == Sinlog::LV[:error]  #=> true
+  #     "foobar".log_err
   #
-  def logger(env_name: nil, level: nil)
+  def logger(level: nil, env_name: nil)
     std_logger = instance.logger
 
     # if level != nil
-    return std_logger.tap { _1.level = to_log_level(level) } unless 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?

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/{loggable.rb → 06_loggable.rb}

@@ -3,16 +3,19 @@
 module Sinlog
   # Provides logging helpers for any object.
   #
-  # == Overview
+  # @see Sinlog::Refin
+  # @see Sinlog::ShortMixin
   #
-  # * `log_dbg`   – DEBUG
-  # * `log_info`  – INFO
-  # * `log_warn`  – WARN
-  # * `log_err`   – ERROR
-  # * `log_fatal` – FATAL
-  # * `log_unk`   – UNKNOWN
+  # ## Methods
   #
-  # == Example
+  #   - `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'
   #
@@ -24,31 +27,31 @@ module Sinlog
   #     Object.method_defined?(:log_warn) #=> true
   #
   module Mixin
-    def self.included(_host)
-      ::Object.include(LogExt)
-    end
+    def self.included(_host) = ::Object.include(LogExt)
   end
 
-  # Provides logging helpers for any object.
+  # @see Sinlog::Mixin
+  # @see Sinlog::ShortRefin
+  #
+  # @note The main difference from {Sinlog::Mixin} is that `Refin` uses Refinements instead of Mixins.
   #
-  # - 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`.
+  #   - rather than `include Sinlog::Mixin`
   #
-  # == Source
+  # ## Source
   #
   #     refine ::Object { import_methods LogExt }
   #
-  # == Overview
+  # ## Methods
   #
-  # * `log_dbg`   – DEBUG
-  # * `log_info`  – INFO
-  # * `log_warn`  – WARN
-  # * `log_err`   – ERROR
-  # * `log_fatal` – FATAL
-  # * `log_unk`   – UNKNOWN
+  # - `#log_dbg`   – DEBUG
+  # - `#log_info`  – INFO
+  # - `#log_warn`  – WARN
+  # - `#log_err`   – ERROR
+  # - `#log_fatal` – FATAL
+  # - `#log_unk`   – UNKNOWN
   #
-  # == Example
+  # @example
   #
   #     require 'sinlog'
   #
@@ -62,7 +65,7 @@ module Sinlog
   #
   #     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)
+  #       # // (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
@@ -75,26 +78,30 @@ module Sinlog
 
   # Provids convenient logging methods.
   #
-  # Similar to `Sinlog::Refin`, but methods omit the `log_` prefix.
+  # 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
+  #   - `"msg".err` instead of `"msg".log_err`;
+  #   - `"msg".warn` instead of `"msg".log_warn`
+  #
+  # ## Source
   #
   #     refine ::Object { import_methods LogShortExt }
   #
-  # == Overview
+  # ## Methods
   #
-  # * `dbg`   – DEBUG
-  # * `info`  – INFO
-  # * `warn`  – WARN
-  # * `err`   – ERROR
-  # * `fatal` – FATAL
-  # * `unk`   – UNKNOWN
+  # - `#dbg`   – DEBUG
+  # - `#info`  – INFO
+  # - `#warn`  – WARN
+  # - `#err`   – ERROR
+  # - `#fatal` – FATAL
+  # - `#unk`   – UNKNOWN
   #
-  # == Example
+  # @see Sinlog::Refin
+  # @see Sinlog::ShortMixin
+  #
+  # @example
   #
   #     require 'sinlog'
   #
@@ -108,11 +115,10 @@ module Sinlog
   #
   #     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)
+  #       # // (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
@@ -121,20 +127,23 @@ module Sinlog
 
   # Provids convenient logging methods.
   #
-  # Similar to `Sinlog::Mixin`, but methods omit the `log_` prefix.
+  # 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.
+  # @note Since mixin monkey patching pollutes the global scope, use `include Sinlog::ShortMixin` with caution.
   #
-  # == Overview
+  # @see Sinlog::Mixin
+  # @see Sinlog::ShortRefin
   #
-  # * `dbg`   – DEBUG
-  # * `info`  – INFO
-  # * `warn`  – WARN
-  # * `err`   – ERROR
-  # * `fatal` – FATAL
-  # * `unk`   – UNKNOWN
+  # ## Methods
   #
-  # == Example
+  # - `Object#dbg`   – DEBUG
+  # - `Object#info`  – INFO
+  # - `Object#warn`  – WARN
+  # - `Object#err`   – ERROR
+  # - `Object#fatal` – FATAL
+  # - `Object#unk`   – UNKNOWN
+  #
+  # @example
   #
   #     require 'sinlog'
   #
@@ -146,8 +155,6 @@ module Sinlog
   #     Object.method_defined?(:err) #=> true
   #
   module ShortMixin
-    def self.included(_host)
-      ::Object.include(LogShortExt)
-    end
+    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
 
 module Sinlog
-  VERSION = '0.0.6'
+  VERSION = '0.0.7'
 end

data/lib/sinlog.rb

@@ -51,11 +51,13 @@ module Sinlog; end
 
 require_relative 'sinlog/version'
 
-require_relative 'sinlog/consts'
-require_relative 'sinlog/logger'
-require_relative 'sinlog/module_fn'
+require_relative 'sinlog/01_consts'
+require_relative 'sinlog/02_logger'
+require_relative 'sinlog/03_module_fn'
 
-require_relative 'sinlog/log_ext'
-require_relative 'sinlog/short_ext'
+require_relative 'sinlog/04_log_ext'
+require_relative 'sinlog/05_short_ext'
 
-require_relative 'sinlog/loggable'
+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.6
+  version: 0.0.7
 platform: ruby
 authors:
 - 2moe
@@ -14,19 +14,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rubocop.yml"
 - License
+- docs/Changelog.md
 - docs/Readme-zh.md
 - docs/Readme.md
 - lib/sinlog.rb
-- lib/sinlog/consts.rb
-- lib/sinlog/log_ext.rb
-- lib/sinlog/loggable.rb
-- lib/sinlog/logger.rb
-- lib/sinlog/module_fn.rb
-- lib/sinlog/short_ext.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.rbi
 homepage: https://github.com/2moe/sinlog-gem
 licenses:
 - MIT