⚙️ CLTLogger (Command-Line Tools Logger，命令行工具日志记录器)

一个简单的，与 swift-log 兼容的日志记录器，专为命令行工具设计。

在创建任何日志记录器之前，使用 CLTLogger 引导 LoggingSystem。

LoggingSystem.bootstrap(CLTLogger.init, metadataProvider: nil/* or whatever you want */)

注意：截图与系统主题（深色模式 vs. 浅色模式）匹配。

CLTLogger 的设计初衷是不在其输出中打印日志记录器的标签，也不打印日期。如果需要打印这些信息，可以使用 CLTLogger 的便捷初始化方法，将其添加到日志记录器的元数据中。

LoggingSystem.bootstrap(CLTLogger.initWithLabelAndDateMetadata, metadataProvider: nil/* or whatever you want */)

标签和日期元数据分别命名为 zz-label 和 zz-date。

CLTLogger 中几乎所有内容都是可配置的。

默认输出目的地是 stderr，但可以使用 FileHandle 更改为任何文件描述符。

将日志记录到 stderr 的理由是日志不是“正常”程序输出，并且在管道传输到另一个程序时应该被忽略。

假设我正在 Swift 中编写一个 sed 程序。在调试时，我想要记录一些信息以便了解我的 bug 在哪里，但我不想让我的 sed 的输出与日志交织在一起！所以我们记录到 stderr。

假设我们运行以下代码

Logger(label: "main").info(
   """
   The following actions are taking place:
      - Demonstrate CLTLogger;
      - Reticulate splines;
      - End with a big finish.
   """,
   metadata: [
      "demo-mode": "amazing",
      "splines-count": "4200",
   ])

以下是使用颜色日志样式的可能输出。

这是默认模式。

此处的名称是不言自明的。

您可以强制使用特定的日志样式，并忽略 CLTLOGGER_LOG_STYLE 环境变量。 不建议这样做。

创建 CLTLogger 实例时，可以为每个日志级别传递一些 CLTLogger.Constants。

此结构允许配置

• 日志前缀（例如，对于使用原始集的关键级别的表情符号日志样式，值为 ‼️ ）；
• 多行日志前缀：它是单个日志中第一行之后的行的日志前缀（当多行模式允许日志中包含多行时）；
• 元数据行前缀；
• 元数据分隔符；
• 日志和元数据分隔符（当元数据与日志行在同一行时）；
• 行分隔符（通常是 \n……）。

我们想要一种符合以下约束的日志格式

• 在命令行工具运行的最常见配置中工作。我们已经测试了以下环境（在深色和浅色模式下）
  • Xcode
  • macOS 终端
  • macOS 上的 VSCode
  • iTerm2
  • Windows PowerShell
  • Windows 上的 VSCode
  • Windows 命令提示符
  • GitHub Actions
• 可读性
  • 当颜色可用时，CLTLogger 使用颜色；
  • 当已知环境良好支持表情符号且不支持颜色（Xcode...）时，我们会回退到表情符号来区分日志级别；
  • 最后，如果其他方式都无法正常工作，则使用文本格式。
• 输出定义清晰，没有意外
  • 我们已经使其能够将所有日志直接通过复制粘贴安全地放入 Swift 中的 #""# 引号字符串中。
  • 默认情况下，一个日志只有一行，即使记录的字符串包含换行符（换行符会被转义）。请注意，这是可配置的，并且多行日志也得到正确支持。
  • 此外，默认情况下，日志行之后是元数据行，每个元数据条目只有一行。这也是可配置的，尽管有意未启用多行元数据（如果需要，我们可能会稍后启用它）。
• 可配置

  • 可以设置 CLTLOGGER_LOG_STYLE 环境变量，以强制 CLTLogger 使用以下方式区分日志级别

    • 值为 color 的颜色；
    • 值为 emoji 的表情符号；
    • 值为 text 的纯文本；
    • 值为 none 的无区分。

  • 可以设置 CLTLOGGER_EMOJI_SET_NAME 环境变量，在使用表情符号记录时使用不同的表情符号集。支持的集合是

    ORIGINAL:                    ‼️ - ❗️ - ⚠️ - 🗣 - 📔 - ⚙️ - 💩
    SWIFTY_BEAVER:               🟥 - 🟥 - 🟨 - 🟦 - 🟦 - 🟩 - ⬜️
    CLEANROOM_LOGGER:            ❌ - ❌ - 🔶 - 🔷 - 🔷 - ◾️ - ◽️
    VAIBHAVSINGH97_EMOJI_LOGGER: 🚑 - 😱 - ⚠️ - ✅ - 🧐 - 🐞 - 🐞
    NO_ALTERNATES:               ❌ - 🔴 - 🟠 - 🟡 - 🟢 - 🟣 - ⚪️
    

    某些表情符号可能会根据您的环境而变化，因为有时表情符号无法正确显示。只有 NO_ALTERNATES 集合才能保证在任何地方看起来都一样。

  • 可以设置 CLTLOGGER_OUTPUT_ENV 环境变量，以使 CLTLogger 假定其运行的给定环境。支持的值为

    • XCODE
    • MACOS_TERMINAL
    • MACOS_ITERM2
    • MACOS_VSCODE
    • MACOS_UNKNOWN
    • WINDOWS_TERMINAL（此值永远不会自动检测到：我们不知道如何检测它 (TERM_PROGRAM 未设置)。）
    • WINDOWS_CONSOLE（此值永远不会自动检测到：我们不知道如何检测它。）
    • WINDOWS_VSCODE
    • WINDOWS_UNKNOWN
    • UNKNOWN_VSCODE
    • UNKNOWN

    这在 CLTLogger 在未知环境中运行时（例如，在 Docker 中几乎不可能知道输出将在 Apple 终端或其他设备中读取）最有用。

    输出环境目前仅用于在使用表情符号记录时修复对齐和其他极端情况。