school_stm32_lab/libs/pynic_log/README.md

Pythonic_log

纯头文件的轻量化日志库，模仿 Python logging 标准库的设计，支持终端彩色输出，不依赖任何标准库。

特性亮点

• 🚀 纯头文件实现 - 单文件集成，无需编译
• 🧩 零依赖 - 不依赖标准库（可通过宏配置）
• 🌈 终端彩色输出 - 内置 ANSI 颜色支持
• ⚙️ 多级日志系统 - 支持 DEBUG/INFO/WARN/ERROR/FATAL/TRACE
• 🧪 高级断言工具 - 包含 Assert, Panie, TODO 等实用宏
• 📦 模块化设计 - 支持多模块独立日志配置
• 🔧 高度可配置 - 自定义输出、格式化和退出行为

快速入门

基础使用

#include "pylike_log.h"

int main() {
    // 基础日志输出
    LOG_INFO("Application started");
    LOG_DEBUG("Debug value: %d", 42);
    LOG_WARN("This is a warning");
    LOG_ERROR("Something went wrong!");
    
    // 断言工具
    int value = 10;
    Assert(value > 5); // 条件断言
    AssertFmt(value != 0, "Value cannot be zero");
    
    return 0;
}

输出示例

[INFO ] - root - main.c:8 | Application started
[DEBUG] - root - main.c:9 | Debug value: 42
[WARN ] - root - main.c:10 | This is a warning
[ERROR] - root - main.c:11 | Something went wrong!

核心功能

日志级别控制

// 获取日志器实例
logger_t* logger = log_get("my_module");

// 设置日志级别（只显示 WARN 及以上）
log_set_level(logger, LOG_LEVEL_WARN | LOG_LEVEL_ERROR | LOG_LEVEL_FATAL);

// 模块化日志
MLOG_WARN(logger, "Module-specific warning: %s", "Low memory");

自定义日志处理器

void custom_handler(
    log_level_t level,
    const char* module,
    const char* file,
    int line,
    const char* message
) {
    // 自定义处理逻辑（如写入文件/网络）
    printf("[CUSTOM] %s:%d - %s\n", file, line, message);
}

int main() {
    logger_t* logger = log_get(NULL);
    log_set_handler(logger, custom_handler);
    
    LOG_INFO("This will use custom handler");
    return 0;
}

断言系统

void critical_function(int* ptr) {
    // 空指针检查
    AssertFmt(ptr != NULL, "Received NULL pointer");
    
    // 范围检查
    AssertFmt(*ptr >= 0 && *ptr <= 100, "Value %d out of range", *ptr);
    
    // 标记未实现功能
    TODO(); // 触发致命错误
}

配置选项

基本配置宏

宏名称	默认值	描述
LOGGER_MAX_BUF_SIZE	512	单条日志最大长度
__LOG_NO_COLOR__	-	禁用彩色输出
__NO_STDIO__	-	禁用标准库依赖

标准库替代（嵌入式环境）

// 在包含头文件前定义这些宏
#define _pylike_logout_printf(fmt, ...)  my_printf(fmt, ##__VA_ARGS__)
#define _pylike_snprintf                 my_snprintf
#define _pylike_exit                     my_exit

#include "pylike_log.h"

颜色自定义

编辑 pylike_color.h 修改 ANSI 颜色代码，或定义 __NO_PYLIKE_COLOR__ 完全禁用颜色。

高级用法

性能追踪

void complex_operation() {
    LOG_TRACE("Entering complex_operation");
    
    // ... 复杂计算 ...
    
    LOG_TRACE("Exiting complex_operation");
}

致命错误处理

void load_config() {
    if (!config_valid) {
        LOG_FATAL("Invalid configuration - aborting");
        // 此处会自动调用 exit(-1)
    }
}

模块化日志系统

// 创建模块专用日志器
logger_t network_logger;
init_logger(&network_logger, "NETWORK");

// 设置模块日志级别
log_set_level(&network_logger, LOG_LEVEL_DEBUG | LOG_LEVEL_ERROR);

// 使用模块日志
MLOG_DEBUG(&network_logger, "Connecting to %s", "192.168.1.1");

API 参考

日志级别

typedef enum log_level {
    LOG_LEVEL_NOTSET  = 0,      // 未设置级别（继承默认配置）
    LOG_LEVEL_DEBUG   = 1 << 0, // 调试信息（开发阶段详细信息）
    LOG_LEVEL_INFO    = 1 << 1, // 常规信息（系统运行状态）
    LOG_LEVEL_WARN    = 1 << 2, // 警告信息（潜在问题提示）
    LOG_LEVEL_ERROR   = 1 << 3, // 错误信息（可恢复的错误）
    LOG_LEVEL_FATAL   = 1 << 4, // 致命错误（导致程序终止的严重错误）
    LOG_LEVEL_TRACE   = 1 << 5, // 追踪（性能追踪或者栈帧追踪）
    LOG_LEVEL_ALL     = 0xFF,   // 全级别标志（组合所有日志级别）
} log_level_t;

日志器结构

typedef struct logger {
    const char* name;           // 日志器名称（用于模块区分）
    log_level_t level;          // 当前设置的日志级别
    log_handler handler;        // 日志处理回调函数
    char buf[LOGGER_MAX_BUF_SIZE]; // 格式化缓冲区
} logger_t;

核心函数

函数	描述
init_logger(logger_t*, const char*)	初始化日志器实例
log_get(const char*)	获取或创建日志器实例
log_set_level(logger_t*, log_level_t)	设置日志级别
log_set_handler(logger_t*, log_handler)	设置自定义日志处理器

集成指南

1. 将 pylike_log.h 和 pylike_color.h 添加到项目
2. 在需要日志的源文件中包含头文件
3. （可选）配置自定义输出函数（嵌入式系统）
4. 使用提供的日志宏记录信息

设计理念

• 极简主义：单头文件实现核心功能
• 灵活性：通过宏配置适应各种环境
• Pythonic API：借鉴 Python logging 的优秀设计
• 安全第一：所有宏都使用 do {...} while(0) 包装