sinlog 0.0.5 → 0.0.7

data/docs/Readme.md

@@ -22,18 +22,22 @@ A very, very simple Ruby singleton logger with colored log levels.
 Table of Contents (click to expand)
 </summary>
 
+- [API DOC](#api-doc)
 - [Quick Start](#quick-start)
 - [Installation](#installation)
-  - [Comparison](#comparison)
+  - [API Style](#api-style)
+    - [Procedural Style](#procedural-style)
+    - [OOP style](#oop-style)
+    - [FP Style](#fp-style)
+- [Monkey Patching](#monkey-patching)
+  - [Comparison Table](#comparison-table)
   - [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)
   - [Real World Example](#real-world-example)
   - [Log Levels](#log-levels)
@@ -43,11 +47,17 @@ Table of Contents (click to expand)
   - [Notes](#notes)
 - [Side Note](#side-note)
 - [Changelog](#changelog)
-  - [0.0.3](#003)
+  - [v0.0.7 (2025-12-03)](#v007-2025-12-03)
 - [License](#license)
 
 </details>
 
+## API DOC
+
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+
+- Github Pages: <https://2moe.github.io/sinlog-gem>
+
 ## Quick Start
 
 ## Installation
@@ -58,31 +68,123 @@ Table of Contents (click to expand)
 gem install sinlog
 ```
 
-### Comparison
+### API Style
+
+In this library, a set of similar functionalities can be accessed through multiple different calling approaches.
+
+Which style you choose mainly depends on your personal preference.
+
+
+#### 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
+
+# Set an environment variable for a custom log level
+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
 
-| 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` |
+'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
+
+### Comparison Table
+
+| 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,51 +195,55 @@ 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
 
-#### Classic Method Call (Neither Mixin nor 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/preview.png" alt="preview">
+<img src="../misc/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,42 +253,14 @@ class A
   end
 end
 
-Sinlog::LV[:info].then do
-  Sinlog.logger_with_level it
-end
-
 A.log
-```
-
-### Classic Method Call
 
-If you prefer the traditional style (`log.info(msg)` instead of `msg.info`):
-
-```ruby
-require 'sinlog'
-
-log = Sinlog.logger
-
-log.debug 'debug'
-log.info 'information'
-log.warn 'warning'
-log.error 'error'
-log.fatal 'fatal'
-log.unknown 'unknown'
+# update the log level to error
+Sinlog.logger(level: 'err')
+Kernel.warn 'Logger.level => error'
+A.log
 ```
 
-> The data type of `Sinlog.logger` is Ruby’s standard library `Logger`.
-
-In addition to the common methods listed above, you can also use other methods such as `.reopen`.
-For details, see <https://docs.ruby-lang.org/en/3.4/Logger.html>
-
-  - `debug`
-  - `info`
-  - `warn`
-  - `error`
-  - `fatal`
-  - `unknown`
-
 ## Advanced
 
 After trying it out ourselves, we have a basic understanding of `sinlog`.
@@ -200,7 +278,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 +302,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 +330,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 +354,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!"
@@ -285,7 +364,9 @@ logger.info "Hello!"
 
 By default, Sinlog outputs to `STDERR`.
 
-If you need to customize the log output path, you can call the Logger's `reopen` method.
+> The data type of `Sinlog.logger` is `::Logger` (from Ruby's standard library).
+
+If you need to customize the log output path, you can call the `::Logger`'s `reopen` method.
 
 ```ruby
 # Logs will be output to the file a.log
@@ -305,13 +386,15 @@ 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`.
+
+For details, see <https://docs.ruby-lang.org/en/3.4/Logger.html>
 
 ### 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
 
@@ -320,21 +403,32 @@ The API might not fully adhere to idiomatic Ruby usage, so I appreciate your und
 
 ## Changelog
 
-### 0.0.3
-
-- `Sinlog.instance.logger` can be simplified => `Sinlog.logger`
+[Earlier versions](./Changelog.md)
 
-- 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] }`
+### v0.0.7 (2025-12-03)
 
-- add `LogExt`, `LogShortExt` and `Loggable`
-
-- add sorbet **.rbi** files
+- add `Sinlog::Proc` module
+- add `lib/sinlog/08_module_short_ext.rb`:
+  - `Sinlog.dbg`
+  - `Sinlog.info`
+  - `Sinlog.warn`
+  - `Sinlog.err`
+  - `Sinlog.fatal`
+  - `Sinlog.unk`
+- update `Sinlog::Logger.logger`
+  - Previous: `def self.logger`
+  - Current: `def self.logger(level = nil, env_name = nil)`
 
 Breaking changes:
-- `fetch_env_and_update_log_level(ENV_NAME)` => `set_level_from_env!(ENV_NAME)`
-- remove `LogLambdaExt` and related modules
+
+- `Sinlog.to_log_level` => `Sinlog.as_log_level`
+- rename `lib/sinlog/*.rb`
+  - consts => 01_consts
+  - logger => 02_logger
+  - module_fn => 03_module_fn
+  - log_ext => 04_log_ext
+  - short_ext => 05_short_ext
+  - loggable => 06_loggable
 
 ## License
 

data/lib/sinlog/01_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

data/lib/sinlog/02_logger.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Sinlog # rubocop:disable Style/ClassAndModuleChildren
+  # Logger Singleton Class
+  class Logger
+    require 'singleton'
+
+    include Singleton
+    attr_reader :logger
+
+    # Since this is a Singleton class, you should use {.instance} instead of `.new`.
+    #
+    # @return [self] Sinlog::Logger
+    #
+    # @example
+    #
+    #     instance = Sinlog::Logger.instance
+    #     instance.logger.info "Hello"
+    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
+
+    # Configures and returns the {StdLogger}.
+    #
+    # @note  Similar to {Sinlog.logger}, but uses different parameter types.
+    #
+    #  - {Sinlog.logger}: uses keyword arguments, e.g., (level: "info", env_name: "RUBY_LOG")
+    #  - This function: uses positional arguments, e.g., ("warn", "CUSTOM_LOG")
+    #
+    # @param level [Integer, String, Symbol, nil]  Log Level.
+    # @param env_name [#to_s]  Name of the environment variable.
+    #
+    # @return [StdLogger]
+    #
+    # @see Sinlog.logger
+    #
+    # ## Example
+    #
+    #     log = Sinlog::Logger.logger("debug")
+    #     log.info "Information"
+    #     log.debug "This is a debug message"
+    #
+    # The log output format will be similar to:
+    #
+    # <ul>
+    #   <li><p><span style="color:darkcyan;">[INFO]</span> 21:29:22.004 Information</p></li>
+    #   <li><p><span style="color:blue;">[DEBUG]</span> 21:29:22.005 This is a debug message</p></li>
+    # </ul>
+    #
+    # > 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 self.logger(level = nil, env_name = nil)
+      Sinlog.logger(level:, env_name:)
+    end
+
+    # Sets 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
+    #
+    #     level = Sinlog.instance.set_level_from_env!("XX_LOG")
+    #     level == Sinlog::LV[:info] # => true
+    #
+    #     log = Sinlog.logger
+    #     log.debug "This message will not be displayed because the current log level is info"
+    #     log.info "Hello!"
+    #
+    # @return [Integer] `@logger.level`
+    # @param env_name [#to_s] Name of the environment variable.
+    def set_level_from_env!(env_name = 'RUBY_LOG')
+      env_str = ENV[env_name.to_s]&.downcase || 'debug'
+
+      Sinlog
+        .as_log_level(env_str)
+        .tap { @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