sinlog 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f34c532f5dee51480976b05ef2257a4cbd6555c8ef7af54430a26890f57510bf
-  data.tar.gz: 36abd9cb6265627faf12bde9cdf3a8ccce0fde6c904032b15dd05f235bdab916
+  metadata.gz: 17e9888bbb5141e0cea455861ecb8f138f6e84d5d1cd6bcd12e6ebc7e471850f
+  data.tar.gz: 4c042bae2dd42b2340160dccb99a64cdde3c63746f39da5c0cc19ff8094d3d95
 SHA512:
-  metadata.gz: 0c2274a0d751ede93a7d022a4099cb2b53e842905d71d96ed56c45dc6f001d3767805c71c20c6a8713ab2ef2114c2a253cba2c10f9aeb12364809de682babbd7
-  data.tar.gz: 9fd628020647f1f341aaf747033eeb94d00f7624491a59078a4bc3a931b45536fc21083c14cf44f4a4d0ab1f1c7cbcbe68cc915f97cb657e2c60869ceb1deabd
+  metadata.gz: 3f6cabc49234fdf2b150ad21cfe4ac65d9359e54008219b1493f5f5a939ba9498ef5638f6ff1fdd636074d1d91a58d990c4fe107f741adaba3f99e5e17306381
+  data.tar.gz: 835f9664e09f5cc82194aff7050eec4094fb206b868c201b0c0be982485533c5134429fe930b7eac6327920d6b485ca77bb2aa0b3f2ad3ac6252888881541447

data/docs/Changelog.md

@@ -0,0 +1,40 @@
+# ChangeLog
+
+- [2025](#2025)
+  - [v0.0.6 (2025-11-30)](#v006-2025-11-30)
+  - [v0.0.3](#v003)
+
+## 2025
+
+### v0.0.6 (2025-11-30)
+
+- 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)"
+
+### v0.0.3
+
+- `Sinlog.instance.logger` can be simplified => `Sinlog.logger`
+
+- add `Sinlog.logger_with_level`
+  - e.g., `logger = Sinlog.logger_with_level(Sinlog::LV[:warn])`
+  - old: `Sinlog.instance.logger.tap { it.level = Sinlog::LV[:warn] }`
+
+- add `LogExt`, `LogShortExt` and `Loggable`
+
+- add sorbet **.rbi** files
+
+Breaking changes:
+- `fetch_env_and_update_log_level(ENV_NAME)` => `set_level_from_env!(ENV_NAME)`
+- remove `LogLambdaExt` and related modules

data/docs/Readme-zh.md

@@ -22,18 +22,22 @@
 目录（点击展开）
 </summary>
 
+- [API DOC](#api-doc)
 - [快速上手](#快速上手)
-- [安装](#安装)
-  - [对比](#对比)
+  - [安装](#安装)
+  - [API style](#api-style)
+    - [Procedural Style](#procedural-style)
+    - [OOP style](#oop-style)
+    - [FP Style](#fp-style)
+- [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)
 - [进阶](#进阶)
   - [Real World Example](#real-world-example)
   - [日志级别](#日志级别)
@@ -46,9 +50,15 @@
 
 </details>
 
+## API DOC
+
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+
+- Github Pages: <https://2moe.github.io/sinlog-gem>
+
 ## 快速上手
 
-## 安装
+### 安装
 
 ```sh
 # POSIX-sh
@@ -56,18 +66,103 @@
 gem install sinlog
 ```
 
-### 对比
+### API style
+
+在此库中，一套相似的功能，有多种不同的调用方式。
+
+选择哪种风格，主要取决于您的偏好。
+
+#### Procedural Style
+
+```ruby
+require 'sinlog'
+
+# update the Sinlog logger level
+Sinlog.logger(level: "debug")
+  # OR: Sinlog::Logger.logger("debug")
+
+Sinlog.dbg 'debug'
+Sinlog.info 'information'
+Sinlog.warn 'warning'
+Sinlog.err 'error'
+Sinlog.fatal 'fatal'
+Sinlog.unk 'unknown'
+```
+
+OR：
+
+```sh
+# POSIX-sh
+
+# 设置环境变量，YOUR_CUSTOM_LOG 可以改为其他的名称
+export YOUR_CUSTOM_LOG=debug
+```
+
+```ruby
+# RUBY
+
+require 'sinlog'
+
+log = Sinlog.logger(env_name: "YOUR_CUSTOM_LOG")
+log.debug "This is a debug message"
+log.info 'information'
+log.warn 'warning'
+log.error 'error'
+log.fatal 'fatal'
+log.unknown 'unknown'
+```
+
+#### OOP style
+
+```ruby
+require 'sinlog'
+
+using Sinlog::Refin
+# OR: include Sinlog::Mixin
+
+'debug'.log_dbg
+'information'.log_info
+'warning'.log_warn
+'error'.log_err
+'fatal'.log_fatal
+'unknown'.log_unk
+```
+
+#### FP Style
+
+```ruby
+require 'sinlog'
+
+# update the Sinlog logger level
+{level: "dbg"}.then { Sinlog.logger **_1 }
+
+Log = Sinlog::Proc
+
+'debug'.tap &Log.dbg
+  # OR: Log.dbg['debug']
+  # OR: Log.dbg.call 'debug'
+  # OR: Log.dbg.('debug')
+
+class Object; def ▷(f) = f.call(self) end
+
+true.▷(Log.dbg >> Log.info >> Log.warn >> Log.err >> Log.fatal >> Log.unk)
+```
+
+
+## Monkey Patching
 
-| 模块        | 类型       | 方法                                         |
-| ----------- | ---------- | -------------------------------------------- |
-| Loggable    | Mixin      | `log_dbg`, `log_info`, etc.                  |
-| LogExt      | Refinement | `log_dbg`, `log_info`, etc.                  |
-| LogShortExt | Refinement | `dbg`, `info`, `warn`, `err`, `fatal`, `unk` |
+### 对照表
 
+| 模块       | 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 +171,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,52 +192,56 @@ 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`。
 
 ### 例子
 
-#### 经典方法调用 (非 mixin，亦非 refinement)
+#### Refinement
 
 ```ruby
 require 'sinlog'
+using Sinlog::Refin
+{ dir: "/path/to/xx" }.log_info
+```
 
-log = Sinlog.logger
-log.info "Information"
-log.debug "This is a debug message"
+```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="../misc/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,41 +250,15 @@ class A
   end
 end
 
-Sinlog::LV[:info].then do
-  Sinlog.logger_with_level it
-end
 
 A.log
-```
-
-### Classic Method Call
-
-您如果不喜欢 `msg.info` 这种做法 ，那不妨试试经典的方法调用吧！(i.e., `log.info(msg)`)
 
-```ruby
-require 'sinlog'
-
-log = Sinlog.logger
-
-log.debug 'debug'
-log.info 'information'
-log.warn 'warning'
-log.error 'error'
-log.fatal 'fatal'
-log.unknown 'unknown'
+# 修改日志级别为 error
+Sinlog.logger(level: 'err')
+Kernel.warn 'Logger.level => error'
+A.log
 ```
 
-> `Sinlog.logger` 的数据类型为 ruby 标准库的 Logger。
-
-除了以下这些常见的方法外，您还可以使用 `.reopen` 等其他的方法，详见 <https://docs.ruby-lang.org.cn/en/3.4/Logger.html>
-
-- debug
-- info
-- warn
-- error
-- fatal
-- unknown
-
 ## 进阶
 
 在亲自上手尝试之后，我们已经对 sinlog 有了初步的了解。
@@ -200,7 +276,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 +300,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 +328,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 +352,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 +360,9 @@ logger.info "Hello!"
 
 ### 日志输出设备/路径
 
-默认情况下，Sinlog 会输出到 STDERR。
+默认情况下，Sinlog 会输出到 `STDERR`。
+
+> `Sinlog.logger` 的数据类型为 ruby 标准库的 Logger。
 
 您如果需要自定义日志输出路径的话，那可以调用 logger 的 reopen 方法。
 
@@ -308,11 +386,13 @@ log.error "发生甚么事了！QuQ"
 
 除了 `.reopen`, `.level` 外，我们还可以在 `Sinlog.logger` 上调用 ruby 标准库的 logger 的其他方法。
 
+详见 <https://docs.ruby-lang.org.cn/en/3.4/Logger.html>
+
 ### 注意事项
 
-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`。
 
 ## 题外话