sinlog 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34c532f5dee51480976b05ef2257a4cbd6555c8ef7af54430a26890f57510bf
-  data.tar.gz: 36abd9cb6265627faf12bde9cdf3a8ccce0fde6c904032b15dd05f235bdab916
+  metadata.gz: e0d59d9821dd32f8ecb824c2b1cb3440c67c740f7787c657ca3afeba24f0d985
+  data.tar.gz: 4068166e9411404ddeb6bbade61ae85044a729f328ac82ebf8f9089cdb3be988
 SHA512:
-  metadata.gz: 0c2274a0d751ede93a7d022a4099cb2b53e842905d71d96ed56c45dc6f001d3767805c71c20c6a8713ab2ef2114c2a253cba2c10f9aeb12364809de682babbd7
-  data.tar.gz: 9fd628020647f1f341aaf747033eeb94d00f7624491a59078a4bc3a931b45536fc21083c14cf44f4a4d0ab1f1c7cbcbe68cc915f97cb657e2c60869ceb1deabd
+  metadata.gz: 30d849c4dcabd26f801f3e12c779eb36ced2d07e5459770f956d7950a44acddfc5465a795df607235376685f24ef25c7b5cb5c3277bd49088da4abe6424862ac
+  data.tar.gz: 0cd703e33418be0d051a9ad896cf62dc94759c6edba81784836951ad99e21dadd1c40be11f91d9dc027592dd4b40c7d13cde001d28556af36e2e4c42880d3456

data/.rubocop.yml

@@ -0,0 +1,33 @@
+# ln ~/.config/rubocop/config.yml .rubocop.yml
+AllCops:
+  TargetRubyVersion: 3.1
+
+Lint/MissingCopEnableDirective:
+  Enabled: false
+Lint/RedundantCopDisableDirective:
+  Enabled: false
+Lint/EmptyExpression:
+  # disabled => allow ()
+  Enabled: false
+
+# https://docs.rubocop.org/rubocop/cops_style.html
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyle: diff_comma
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyle: diff_comma
+Style/Lambda:
+  EnforcedStyle: literal
+Style/ModuleFunction:
+  # EnforcedStyle: extend_self
+  EnforcedStyle: module_function
+Style/BlockDelimiters:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+
+# https://docs.rubocop.org/rubocop/cops_layout.html
+Layout/CaseIndentation:
+  EnforcedStyle: end
+  IndentOneStep: true
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver

data/docs/Readme-zh.md

@@ -24,14 +24,14 @@
 
 - [快速上手](#快速上手)
 - [安装](#安装)
-  - [对比](#对比)
+  - [Monkey Patching 模块对照表](#monkey-patching-模块对照表)
   - [方法列表](#方法列表)
-    - [Loggable \& LogExt](#loggable--logext)
-    - [LogShortExt](#logshortext)
+    - [Mixin \& Refin](#mixin--refin)
+    - [ShortMixin \& ShortRefin](#shortmixin--shortrefin)
   - [例子](#例子)
     - [经典方法调用 (非 mixin，亦非 refinement)](#经典方法调用-非-mixin亦非-refinement)
-    - [Mixin](#mixin)
     - [Refinement](#refinement)
+    - [Mixin](#mixin)
 - [Learn Sinlog API By Example](#learn-sinlog-api-by-example)
   - [Classic Method Call](#classic-method-call)
 - [进阶](#进阶)
@@ -56,18 +56,18 @@
 gem install sinlog
 ```
 
-### 对比
-
-| 模块        | 类型       | 方法                                         |
-| ----------- | ---------- | -------------------------------------------- |
-| Loggable    | Mixin      | `log_dbg`, `log_info`, etc.                  |
-| LogExt      | Refinement | `log_dbg`, `log_info`, etc.                  |
-| LogShortExt | Refinement | `dbg`, `info`, `warn`, `err`, `fatal`, `unk` |
+### Monkey Patching 模块对照表
 
+| 模块       | Type       | Activation | 方法                                                     |
+| ---------- | ---------- | ---------- | -------------------------------------------------------- |
+| 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                         |
 
 ### 方法列表
 
-#### Loggable & LogExt
+#### Mixin & Refin
 
 - `log_dbg`   – DEBUG
 - `log_info`  – INFO
@@ -76,14 +76,17 @@ gem install sinlog
 - `log_fatal` – FATAL
 - `log_unk`   – UNKNOWN
 
-#### LogShortExt
-
-LogShortExt 类似于 LogExt。
+#### ShortMixin & ShortRefin
 
-除了方法的命名不同外，二者的内部实现没有任何区别。
+- ShortRefin 类似于 Refin
+  - 除了方法的命名不同外，二者的内部实现没有任何区别。
+    - Refin 的方法带有 `log_` 前缀
+    - ShortRefin 没有
 
-- LogExt 的方法带有 `log_` 前缀
-- LogShortExt 没有
+- ShortMixin 类似于 Mixin
+  - 二者的区别只是命名不同
+    - Mixin 的方法带有 `log_` 前缀
+    - ShortMixin 没有
 
 ---
 
@@ -94,10 +97,10 @@ LogShortExt 类似于 LogExt。
 - `fatal` – FATAL
 - `unk`   – UNKNOWN
 
-> ⚠️ 由于 LogShortExt 带有 warn 方法，因此会覆盖 warn。
-> 对于 ruby 代码中的 `warn "msg"`，您可能需要手动将其修改为 `Kernel.warn "msg"`
+> ⚠️ 由于 ShortMixin & ShortRefin 带有 warn 方法，因此会覆盖 warn。
+> 对于 ruby 代码中的 `warn "msg"` (输出到 stderr 而非输出为日志格式)，您可能需要手动将其修改为 `Kernel.warn "msg"`。
 >
-> 如果介意的话，那就使用 `using Sinlog::LogExt` 而不是 `using Sinlog::LogShortExt`。
+> 如果介意的话，那就使用 `using Sinlog::Refin` 而不是 `using Sinlog::ShortRefin`。
 
 ### 例子
 
@@ -111,35 +114,49 @@ log.info "Information"
 log.debug "This is a debug message"
 ```
 
+#### Refinement
+
+```ruby
+require 'sinlog'
+using Sinlog::Refin
+{ dir: "/path/to/xx" }.log_info
+```
+
+```ruby
+require 'sinlog'
+using Sinlog::ShortRefin
+{ dir: "/path/to/xx" }.info
+```
+
 #### Mixin
 
 ```ruby
 require 'sinlog'
-include Sinlog::Loggable
+include Sinlog::Mixin
 "Hello".log_info
 ```
-#### Refinement
 
 ```ruby
 require 'sinlog'
-using Sinlog::LogExt
-{ dir: "/path/to/xx" }.log_info
+include Sinlog::ShortMixin
+"Hello".info
 ```
 
 ## Learn Sinlog API By Example
 
-<img src="../assets/img/预览.png" alt="预览">
+<img src="../assets/img/预览.webp" alt="预览">
 
 ```ruby
 require 'sinlog'
 
-class A
-  using Sinlog::LogShortExt
+module A
+  module_function
+  using Sinlog::ShortRefin
 
-  def self.log
-    '您好，我是一条调试消息。
-    您可能会觉得我有点啰嗦，哈哈哈！'.dbg
-    '神经，害我笑了一下'.info
+  def log
+    ['喂喂喂123，能看到这条调试消息吗？',
+    '您可能会觉得我有点啰嗦，哈哈哈！'].dbg
+    '神经，害我笑了一下。'.info
 
     '开门！查水表。'.warn
     { error: "IO", type: "输入数据无效" }.err
@@ -148,10 +165,12 @@ class A
   end
 end
 
-Sinlog::LV[:info].then do
-  Sinlog.logger_with_level it
-end
 
+A.log
+
+# 修改日志级别为 error
+Sinlog.logger(level: 'err')
+Kernel.warn 'Logger.level => error'
 A.log
 ```
 
@@ -162,7 +181,9 @@ A.log
 ```ruby
 require 'sinlog'
 
-log = Sinlog.logger
+ENV["CUSTOM_LOG"] = 'info'
+
+log = Sinlog.logger(env_name: "CUSTOM_LOG")
 
 log.debug 'debug'
 log.info 'information'
@@ -200,7 +221,8 @@ require 'sinlog'
 class EpubProcessor
   def initialize(epub_file, logger = nil)
     @epub = epub_file
-    @logger = logger || Sinlog.instance.tap { it.set_level_from_env!("XX_LOG") }.logger
+    logger ||= Sinlog::logger(env_name: "XX_LOG")
+    @logger = logger
     @logger.debug "EpubProcessor class 初始化完成。"
   end
 end
@@ -223,17 +245,18 @@ end
 - fatal = 4
 - unknown = 5
 
+> 有意思的一点是： ruby 的标准库的 logger 的日志级别与 rust 的 [log::Level](https://docs.rs/log/latest/log/enum.Level.html) 是相反的。
+
 ```ruby
 p Sinlog::LV
 # => {debug: 0, info: 1, warn: 2, error: 3, fatal: 4, unknown: 5}
 
 # 将日志级别修改为 warn
-log = Sinlog.logger_with_level(Sinlog::LV[:warn])
+log = Sinlog.logger(level: 'warn')
 # OR:
-#   log = Sinlog.logger.tap { it.level = Sinlog::LV[:warn] }
+#   log = Sinlog.logger(level: Sinlog::LV[:warn])
 # OR:
-#   log = Sinlog.instance.logger.tap { it.level = 2 }
-
+#   log = Sinlog.logger.tap { it.level = 2 }
 
 log.error "这条消息会显示出来！低级别 WARN（2）会显示高级别 ERROR(3) 的日志。"
 log.info "这条消息不会显示出来！高级别 WARN(2) 不会显示低级别 INFO(1) 的日志。"
@@ -250,13 +273,11 @@ log.info "这条消息不会显示出来！高级别 WARN(2) 不会显示低级
 
 > 使用环境变量足够简单也足够高效。
 
-Sinlog 在默认情况下，会尝试读取环境变量 RUBY_LOG 的值。
-
-本质上调用了 `set_level_from_env!(env_name = 'RUBY_LOG')` 函数。
+`Sinlog::Logger` 在初始化时，会尝试读取环境变量 `RUBY_LOG` 的值。
 
 - 若该环境变量不存在，则使用 debug(0)。
-- 若该环境变量存在，且其值为空，则使用 unknown(5)。
-- 若该环境变量的值无效，则使用 unknown(5)。
+- 若该环境变量存在，且其值为空，则使用 error(3)。
+- 若该环境变量的值无效，则使用 error(3)。
 
 我们可以用 POSIX-sh 设置环境变量，然后 logger 在初始化的时候，就会自动将日志级别设置为（RUBY_LOG的值）warn。
 
@@ -276,7 +297,7 @@ export XX_CLI_LOG=info
 ruby:
 
 ```ruby
-logger = Sinlog.instance.tap { it.set_level_from_env!("XX_CLI_LOG") }.logger
+logger = Sinlog.logger(env_name:"XX_CLI_LOG")
 
 logger.debug "由于当前日志级别为 INFO(1)，因此不会显示此消息 DEBUG(0)。"
 logger.info "Hello!"
@@ -284,7 +305,7 @@ logger.info "Hello!"
 
 ### 日志输出设备/路径
 
-默认情况下，Sinlog 会输出到 STDERR。
+默认情况下，Sinlog 会输出到 `STDERR`。
 
 您如果需要自定义日志输出路径的话，那可以调用 logger 的 reopen 方法。
 
@@ -310,9 +331,9 @@ log.error "发生甚么事了！QuQ"
 
 ### 注意事项
 
-Sinlog 用的是 Singleton 单例模式，整个程序会共享同一个实例（日志记录器）。
+`Sinlog::Logger` 用的是 Singleton 单例模式，整个程序会共享同一个实例（日志记录器）。
 
-在同一个程序的 class A 中修改 Sinlog 后，会影响到 class B 的 Sinlog。
+在同一个程序的 class A 中修改 `Sinlog.logger` (a.k.a. `Sinlog::Logger.instance.logger`) 后，会影响到 class B 的 `Sinlog::Logger`。
 
 ## 题外话
 

data/docs/Readme.md

@@ -24,14 +24,14 @@ Table of Contents (click to expand)
 
 - [Quick Start](#quick-start)
 - [Installation](#installation)
-  - [Comparison](#comparison)
+  - [Comparison Table (Monkey Patching)](#comparison-table-monkey-patching)
   - [Method List](#method-list)
-    - [Loggable \& LogExt](#loggable--logext)
-    - [LogShortExt](#logshortext)
+    - [Mixin \& Refin](#mixin--refin)
+    - [ShortMixin \& ShortRefin](#shortmixin--shortrefin)
   - [Examples](#examples)
     - [Classic Method Call (Neither Mixin nor Refinement)](#classic-method-call-neither-mixin-nor-refinement)
-    - [Mixin](#mixin)
     - [Refinement](#refinement)
+    - [Mixin](#mixin)
 - [Learn Sinlog API by Example](#learn-sinlog-api-by-example)
   - [Classic Method Call](#classic-method-call)
 - [Advanced](#advanced)
@@ -44,6 +44,7 @@ Table of Contents (click to expand)
 - [Side Note](#side-note)
 - [Changelog](#changelog)
   - [0.0.3](#003)
+  - [0.0.6](#006)
 - [License](#license)
 
 </details>
@@ -58,31 +59,38 @@ Table of Contents (click to expand)
 gem install sinlog
 ```
 
-### Comparison
+### Comparison Table (Monkey Patching)
 
-| Module      | Type       | Methods                                      |
-| ----------- | ---------- | -------------------------------------------- |
-| Loggable    | Mixin      | `log_dbg`, `log_info`, etc.                  |
-| LogExt      | Refinement | `log_dbg`, `log_info`, etc.                  |
-| LogShortExt | Refinement | `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                         |
 
 ### Method List
 
-#### Loggable & LogExt
+#### Mixin & Refin
 
-*   `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
 
-#### LogShortExt
+#### ShortMixin & ShortRefin
 
-`LogShortExt` works the same way as `LogExt`, except for method naming:
 
-  - `LogExt` methods use the `log_` prefix.
-  - `LogShortExt` methods do not.
+- **ShortRefin** is similar to **Refin**
+  - Apart from the difference in method naming, their internal implementations are identical.
+    - Methods in **Refin** have the `log_` prefix
+    - **ShortRefin** does not
+
+- **ShortMixin** is similar to **Mixin**
+  - The only difference is in naming
+    - Methods in **Mixin** have the `log_` prefix
+    - **ShortMixin** does not
 
 ---
 
@@ -93,10 +101,10 @@ gem install sinlog
 - `fatal` – FATAL
 - `unk`   – UNKNOWN
 
-> ⚠️ Note: `LogShortExt` defines a `warn` method, which overrides Ruby’s built-in `warn`.
-> If you need to call the original `warn "msg"`, use `Kernel.warn "msg"` instead.
+> ⚠️ Since **ShortMixin** and **ShortRefin** define a `warn` method, they will override the default `warn`.
+> For Ruby code that uses `warn "msg"` (which outputs to **stderr** rather than using a log format), you may need to manually change it to `Kernel.warn "msg"`.
 >
-> If this is a concern, use `using Sinlog::LogExt` instead of `using Sinlog::LogShortExt`.
+> If this bothers you, then use `using Sinlog::Refin` instead of `using Sinlog::ShortRefin`.
 
 ### Examples
 
@@ -110,34 +118,48 @@ log.info "Information"
 log.debug "This is a debug message"
 ```
 
+#### Refinement
+
+```ruby
+require 'sinlog'
+using Sinlog::Refin
+{ dir: "/path/to/xx" }.log_info
+```
+
+```ruby
+require 'sinlog'
+using Sinlog::ShortRefin
+{ dir: "/path/to/xx" }.info
+```
+
 #### Mixin
 
 ```ruby
 require 'sinlog'
-include Sinlog::Loggable
+include Sinlog::Mixin
 "Hello".log_info
 ```
 
-#### Refinement
-
 ```ruby
 require 'sinlog'
-using Sinlog::LogExt
-{ dir: "/path/to/xx" }.log_info
+include Sinlog::ShortMixin
+"Hello".info
 ```
 
 ## Learn Sinlog API by Example
 
-<img src="../assets/img/preview.png" alt="preview">
+<img src="../assets/img/preview.webp" alt="preview">
 
 ```ruby
 require 'sinlog'
 
-class A
-  using Sinlog::LogShortExt
+module A
+  module_function
+  using Sinlog::ShortRefin
 
-  def self.log
-    'Hello, this is a debug message.'.dbg
+  def log
+    ['Hey hey hey, could you see this debug message?',
+     'You might find it a bit verbose, hahaha!'].dbg
     'Just some info.'.info
 
     'FBI, open the door!'.warn
@@ -147,10 +169,11 @@ class A
   end
 end
 
-Sinlog::LV[:info].then do
-  Sinlog.logger_with_level it
-end
+A.log
 
+# update the log level to error
+Sinlog.logger(level: 'err')
+Kernel.warn 'Logger.level => error'
 A.log
 ```
 
@@ -161,7 +184,9 @@ If you prefer the traditional style (`log.info(msg)` instead of `msg.info`):
 ```ruby
 require 'sinlog'
 
-log = Sinlog.logger
+ENV["CUSTOM_LOG"] = 'info'
+
+log = Sinlog.logger(env_name: "CUSTOM_LOG")
 
 log.debug 'debug'
 log.info 'information'
@@ -200,7 +225,8 @@ require 'sinlog'
 class EpubProcessor
   def initialize(epub_file, logger = nil)
     @epub = epub_file
-    @logger = logger || Sinlog.instance.tap { it.set_level_from_env!("XX_LOG") }.logger
+    logger ||= Sinlog::logger(env_name: "XX_LOG")
+    @logger = logger
     @logger.debug "EpubProcessor class initialization completed."
   end
 end
@@ -223,16 +249,18 @@ Log levels from low to high are:
 - fatal = 4
 - unknown = 5
 
+> Interestingly, the log levels in Ruby’s standard library `Logger` are the opposite of Rust’s [log::Level](https://docs.rs/log/latest/log/enum.Level.html).
+
 ```ruby
 p Sinlog::LV
 # => {debug: 0, info: 1, warn: 2, error: 3, fatal: 4, unknown: 5}
 
 # Change the log level to warn
-log = Sinlog.logger_with_level(Sinlog::LV[:warn])
+log = Sinlog.logger(level: 'warn')
 # OR:
-#   log = Sinlog.logger.tap { it.level = Sinlog::LV[:warn] }
+#   log = Sinlog.logger(level: Sinlog::LV[:warn])
 # OR:
-#   log = Sinlog.instance.logger.tap { it.level = 2 }
+#   log = Sinlog.logger.tap { it.level = 2 }
 
 log.error "This message will be displayed! Lower level WARN (2) will display higher level ERROR (3) logs."
 log.info "This message will not be displayed! Higher level WARN (2) will not display lower level INFO (1) logs."
@@ -249,13 +277,11 @@ To allow them to configure `log.level` directly, we can use environment variable
 
 > Using environment variables is simple and efficient.
 
-By default, Sinlog will attempt to read the value of the environment variable `RUBY_LOG`.
-
-It essentially calls the function `set_level_from_env!(env_name = 'RUBY_LOG')`.
+By default, `Sinlog::Logger` will attempt to read the value of the environment variable `RUBY_LOG`.
 
 - If the environment variable does not exist, it uses `debug(0)`.
-- If the environment variable exists but is empty, it uses `unknown(5)`.
-- If the environment variable's value is invalid, it uses `unknown(5)`.
+- If the environment variable exists but is empty, it uses `error(3)`.
+- If the environment variable's value is invalid, it uses `error(3)`.
 
 We can set the environment variable using POSIX-sh, and then the logger will automatically set the log level to `warn` (the value of `RUBY_LOG`) during initialization.
 
@@ -275,7 +301,7 @@ export XX_CLI_LOG=info
 Ruby:
 
 ```ruby
-logger = Sinlog.instance.tap { it.set_level_from_env!("XX_CLI_LOG") }.logger
+logger = Sinlog.logger(env_name:"XX_CLI_LOG")
 
 logger.debug "This message will not be displayed because the current log level is INFO(1)."
 logger.info "Hello!"
@@ -305,13 +331,13 @@ log.error "What happened! QuQ"
 
 ### Other Logger Methods
 
-In addition to `.reopen` and `.level`, we can also call other methods from Ruby's standard library logger on `Sinlog.instance.logger`.
+In addition to `.reopen` and `.level`, we can also call other methods from Ruby's standard library logger on `Sinlog.logger`.
 
 ### Notes
 
-Sinlog uses the Singleton pattern, meaning the entire program will share the same instance (logger).
+`Sinlog::Logger` uses the Singleton pattern, meaning the entire program will share the same instance (logger).
 
-Modifying Sinlog in class A of the same program will affect Sinlog in class B.
+Modifying `Sinlog.logger` (a.k.a. `Sinlog::Logger.instance.logger`) in class A of the same program will affect `Sinlog::Logger` in class B.
 
 ## Side Note
 
@@ -336,6 +362,23 @@ Breaking changes:
 - `fetch_env_and_update_log_level(ENV_NAME)` => `set_level_from_env!(ENV_NAME)`
 - remove `LogLambdaExt` and related modules
 
+### 0.0.6
+
+- add `Sinlog::ShortMixin` module
+- reimplement `Sinlog.logger` to make the API more user-friendly.
+    - We can now configure the log level via `Sinlog.logger(level: "info", env_name: "CUSTOM_ENV_LOG")`.
+    - **Note:** When both `level` and `env_name` are provided, `level` takes precedence.
+
+Breaking changes:
+
+- `using LogExt` => `using Sinlog::Refin`
+- `using LogShortExt` => `using Sinlog::ShortRefin`
+- `include Loggable` => `include Sinlog::Mixin`
+- `Sinlog` class => `Sinlog` module
+  - private method: `Sinlog.initialize` => `Sinlog::Logger.initialize`
+- remove `Sinlog.logger_with_level`
+- change the default fallback log level from "unknown(5)" to "error(3)"
+
 ## License
 
 [MIT License](../License)

data/lib/sinlog/consts.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Sinlog
+  StdLogger = ::Logger
+
+  # Define colors for different log levels
+  COLORS = {
+    debug: "\e[34m",   # Blue
+    info: "\e[36m",    # Cyan
+    warn: "\e[33m",    # Yellow
+    error: "\e[31m",   # Red
+    fatal: "\e[35m",   # Magenta
+    unknown: "\e[0m"   # Reset
+  }.freeze
+
+  # log levels
+  LV = {
+    debug: StdLogger::DEBUG,
+    info: StdLogger::INFO,
+    warn: StdLogger::WARN,
+    error: StdLogger::ERROR,
+    fatal: StdLogger::FATAL,
+    unknown: StdLogger::UNKNOWN
+  }.freeze
+end