Frozen扩展开发指南：如何为Frozen添加自定义数据格式支持

【免费下载链接】frozenJSON parser and generator for C/C++ with scanf/printf like interface. Targeting embedded systems.项目地址: https://gitcode.com/gh_mirrors/fro/frozen

Frozen是一个面向嵌入式系统的轻量级JSON解析器和生成器库，以其类似scanf/printf的简洁接口而闻名。本文将详细介绍如何为Frozen添加自定义数据格式支持，让您能够扩展其功能以满足特定需求。通过自定义格式支持，您可以处理非标准数据格式或优化特定场景下的性能表现。

为什么需要自定义数据格式支持？ 🤔

Frozen默认支持标准的JSON数据类型和几种扩展格式（如Base64、十六进制等），但在实际应用中，您可能需要：

1. 处理自定义二进制格式- 如特定的编码方案
2. 优化内存使用- 针对特定数据结构进行优化
3. 支持专有协议- 集成到现有系统中
4. 提升性能- 针对特定数据模式进行优化

Frozen的扩展机制解析

Frozen提供了两种主要的扩展机制：

1.%M格式说明符 - 自定义扫描器

在frozen.h中定义的json_scanner_t类型允许您创建自定义的扫描函数：

typedef void (*json_scanner_t)(const char *str, int len, void *user_data);

这个函数类型用于json_scanf()中的%M格式说明符，让您可以完全控制如何解析特定的JSON值。

2.%M格式说明符 - 自定义打印机

在frozen.h中定义的json_printf_callback_t类型允许您创建自定义的打印函数：

typedef int (*json_printf_callback_t)(struct json_out *, va_list *ap);

这个回调函数用于json_printf()中的%M格式说明符，让您可以自定义如何序列化复杂数据结构。

实战：添加自定义时间戳格式支持 ⏰

让我们通过一个实际例子来演示如何为Frozen添加自定义的时间戳格式支持。

步骤1：定义时间戳数据结构

首先，在您的项目中定义时间戳结构：

#include "frozen.h" #include <time.h> typedef struct { time_t seconds; long nanoseconds; } timestamp_t;

步骤2：实现自定义扫描函数

创建一个扫描函数，将JSON字符串转换为时间戳：

// 自定义时间戳扫描器 void scan_timestamp(const char *str, int len, void *user_data) { timestamp_t *ts = (timestamp_t *)user_data; char buffer[64]; // 确保不会溢出缓冲区 if (len >= sizeof(buffer)) len = sizeof(buffer) - 1; memcpy(buffer, str, len); buffer[len] = '\0'; // 解析ISO 8601格式的时间戳 struct tm tm_info = {0}; char *remainder = strptime(buffer, "%Y-%m-%dT%H:%M:%S", &tm_info); if (remainder != NULL) { ts->seconds = mktime(&tm_info); // 解析纳秒部分（如果有） if (*remainder == '.') { char *endptr; double fraction = strtod(remainder, &endptr); ts->nanoseconds = (long)(fraction * 1e9); } else { ts->nanoseconds = 0; } } }

步骤3：实现自定义打印函数

创建一个打印函数，将时间戳序列化为JSON字符串：

// 自定义时间戳打印机 int print_timestamp(struct json_out *out, va_list *ap) { timestamp_t *ts = va_arg(*ap, timestamp_t *); struct tm *tm_info = localtime(&ts->seconds); char buffer[64]; // 格式化为ISO 8601 strftime(buffer, sizeof(buffer), "%Y-%m-%dT%H:%M:%S", tm_info); // 添加纳秒部分 if (ts->nanoseconds > 0) { char ns_buffer[32]; snprintf(ns_buffer, sizeof(ns_buffer), ".%09ld", ts->nanoseconds); strcat(buffer, ns_buffer); } // 使用%Q格式说明符输出带引号的字符串 return json_printf(out, "%Q", buffer); }

步骤4：使用自定义格式

现在您可以在代码中使用自定义的时间戳格式：

// 解析包含时间戳的JSON const char *json_str = "{\"created_at\": \"2023-10-05T14:30:25.123456789\", \"data\": \"example\"}"; timestamp_t ts = {0}; char *data = NULL; json_scanf(json_str, strlen(json_str), "{created_at: %M, data: %Q}", scan_timestamp, &ts, &data); printf("Parsed timestamp: %ld.%09ld\n", ts.seconds, ts.nanoseconds); printf("Data: %s\n", data); free(data); // 生成包含时间戳的JSON timestamp_t current_time = {time(NULL), 0}; char output[256]; struct json_out out = JSON_OUT_BUF(output, sizeof(output)); json_printf(&out, "{timestamp: %M, status: %Q}", print_timestamp, &current_time, "success"); printf("Generated JSON: %s\n", output);

高级技巧：创建可重用的格式处理器 🛠️

对于更复杂的场景，您可以创建通用的格式处理器：

1. 注册表模式

typedef struct { const char *format_char; json_scanner_t scanner; json_printf_callback_t printer; } format_handler_t; format_handler_t custom_handlers[] = { {"T", scan_timestamp, print_timestamp}, // 添加更多自定义处理器... {NULL, NULL, NULL} }; // 包装函数，根据格式字符选择处理器 int custom_json_scanf(const char *str, int len, const char *fmt, ...) { va_list ap; va_start(ap, fmt); // 这里可以解析fmt，将自定义格式字符映射到%M处理器 // 简化实现：在实际项目中需要更复杂的解析逻辑 va_end(ap); return 0; }

2. 宏包装器

#define JSON_SCAN_TIMESTAMP(ptr) %M, scan_timestamp, (ptr) #define JSON_PRINT_TIMESTAMP(ts) %M, print_timestamp, (ts) // 使用示例 json_scanf(str, len, "{created: " JSON_SCAN_TIMESTAMP(&ts) "}"); json_printf(&out, "{timestamp: " JSON_PRINT_TIMESTAMP(&current_time) "}");

性能优化建议 ⚡

当为嵌入式系统开发自定义格式支持时，考虑以下优化：

1. 避免动态内存分配- 在扫描函数中使用静态缓冲区
2. 预计算格式字符串- 避免在热路径中解析格式字符串
3. 使用整数运算- 避免浮点运算以提高性能
4. 缓存解析结果- 对于重复使用的格式，缓存解析后的结果

调试和测试技巧 🔧

1. 单元测试

在unit_test.c中添加测试用例：

static const char *test_custom_format(void) { const char *json = "{\"timestamp\": \"2023-10-05T14:30:25\"}"; timestamp_t ts = {0}; int result = json_scanf(json, strlen(json), "{timestamp: %M}", scan_timestamp, &ts); ASSERT(result == 1); ASSERT(ts.seconds > 0); return NULL; }

2. 调试输出

添加调试信息到自定义处理器：

void scan_timestamp_debug(const char *str, int len, void *user_data) { printf("Scanning timestamp: %.*s\n", len, str); scan_timestamp(str, len, user_data); }

常见问题解答 ❓

Q: 自定义格式会影响性能吗？

A: 正确实现的自定义格式通常比通用解析更快，因为它们是针对特定数据模式优化的。

Q: 可以添加多个自定义格式吗？

A: 是的，您可以为不同的数据类型创建多个自定义处理器。

Q: 自定义格式支持嵌套结构吗？

A: 是的，您可以在%M处理器内部使用json_scanf()或json_printf()来处理嵌套结构。

Q: 如何处理错误情况？

A: 在自定义处理器中添加错误检查，并考虑使用返回值或错误参数来报告问题。

总结

通过为Frozen添加自定义数据格式支持，您可以：

1. 扩展功能- 支持特定领域的数据格式
2. 优化性能- 针对特定用例进行优化
3. 简化代码- 提供更简洁的API
4. 提高可维护性- 将复杂逻辑封装在可重用的处理器中

Frozen的%M格式说明符提供了强大的扩展能力，让您可以根据项目需求定制JSON处理逻辑。无论是处理时间戳、二进制数据还是复杂的业务对象，自定义格式支持都能让您的代码更加简洁高效。

记住，良好的扩展设计应该保持与现有API的一致性，并提供清晰的错误处理和文档。通过遵循本文的指南，您将能够为Frozen创建强大而可靠的自定义数据格式支持。

【免费下载链接】frozenJSON parser and generator for C/C++ with scanf/printf like interface. Targeting embedded systems.项目地址: https://gitcode.com/gh_mirrors/fro/frozen