一、前言
上篇文章（设计模式学习（三）：生成器（Builder）模式）记录了 Builder 模式的具体内容，这次使用C语言来实现一个实际的例子——基于Builder模式的歌词解析器。
二、示例介绍
歌词文件（.lrc）是一种文本文件，用来描述歌曲的歌词。在该文件的帮助下，音乐播放器可以根据相应时间同步显示歌词。歌词文件由时间标签、ID标签和歌词组成。
- 时间标签，例如：[00:23.25]
- ID标签，例如：[ar:谭咏麟]
- 歌词，例如：凄雨冷风中 多少繁华如梦
下面是谭咏麟先生的歌曲 水中花 歌词的截取部分：
[ti:水中花]
[ar:谭咏麟]
[al:心手相连]
[by:孟德良]
[00:00.00]《水中花》
[00:02.00]演唱：谭咏麟
[00:04.00]作词：娃娃
[00:05.50]作曲：简宁
[00:07.00]
[00:09.03]凄雨冷风中 多少繁华如梦
[00:15.25]曾经万紫千红 随风吹落
[00:23.25]蓦然回首中 欢爱宛如烟云
[00:29.57]似水年华流走 不留影踪
[00:36.30]
[00:37.18]我看见 水中的花朵
[00:40.31]强要留住一抹红
[00:44.50]奈何辗转在风尘
[00:48.07]不再有往日颜色
[00:50.84]
......
......
[02:46.85]感怀飘零的花朵
[02:50.01]城市中无从寄托
[02:54.10]任那雨打风吹 也沉默
[02:57.90]仿佛是我
[03:00.12]
[03:01.72]啦…啦…啦…啦…
[03:16.09]啦…啦…啦…啦…
三、示例代码（C）
以下歌词解析器的代码参考了李先静老师基于AWTK实现的多媒体播放器项目（awtk-media-player），可前往 GitHub开源仓库 下载，其中歌词解析器位于awtk-media-player\src\media_player\lrc目录中。
3.1 Builder接口（lrc_builder.h）
#ifndef TK_LRC_BUILDER_H
#define TK_LRC_BUILDER_H
#include "tkc/types_def.h"
BEGIN_C_DECLS
struct _lrc_builder_t;
typedef struct _lrc_builder_t lrc_builder_t;
typedef ret_t (*lrc_builder_on_id_tag_t)(lrc_builder_t* builder, const char* key,
const char* value);
typedef ret_t (*lrc_builder_on_time_tag_t)(lrc_builder_t* builder, uint32_t start_time);
typedef ret_t (*lrc_builder_on_text_t)(lrc_builder_t* builder, const char* text);
typedef ret_t (*lrc_builder_on_error_t)(lrc_builder_t* builder, const char* error);
typedef ret_t (*lrc_builder_destroy_t)(lrc_builder_t* builder);
typedef struct _lrc_builder_vtable_t {
lrc_builder_on_text_t on_text;
lrc_builder_on_error_t on_error;
lrc_builder_on_id_tag_t on_id_tag;
lrc_builder_on_time_tag_t on_time_tag;
lrc_builder_destroy_t destroy;
} lrc_builder_vtable_t;
/**
* @class lrc_builder_t
* lrc builder
*/
struct _lrc_builder_t {
const lrc_builder_vtable_t* vt;
};
/**
* @method lrc_builder_on_id_tag
* 处理id标签。
*
* @param {lrc_builder_t*} builder lrc_builder对象。
* @param {const char*} id 名称。
* @param {const char*} value 值。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t lrc_builder_on_id_tag(lrc_builder_t* builder, const char* id, const char* value);
/**
* @method lrc_builder_on_time_tag
* 处理time标签。
*
* @param {lrc_builder_t*} builder lrc_builder对象。
* @param {uint32_t} timestamp 时间。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t lrc_builder_on_time_tag(lrc_builder_t* builder, uint32_t timestamp);
/**
* @method lrc_builder_on_text
* 处理歌词。
*
* @param {lrc_builder_t*} builder lrc_builder对象。
* @param {const char*} text 歌词。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t lrc_builder_on_text(lrc_builder_t* builder, const char* text);
/**
* @method lrc_builder_on_error
* 处理错误。
*
* @param {lrc_builder_t*} builder lrc_builder对象。
* @param {const char*} error 错误。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t lrc_builder_on_error(lrc_builder_t* builder, const char* error);
/**
* @method lrc_builder_destroy
* 销毁lrc builder对象。
*
* @param {lrc_builder_t*} builder lrc_builder对象。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t lrc_builder_destroy(lrc_builder_t* builder);
END_C_DECLS
#endif /*TK_LRC_BUILDER_H*/
3.2 Builder的实现一(lrc_builder_dump.c)
lrc_builder_dump：直接把解析的内容保存为文本，方便打印调试 以及 美化格式较乱的 lrc 文件，其主要代码如下：
#include "tkc/mem.h"
#include "tkc/utils.h"
#include "media_player/lrc/lrc_builder_dump.h"
static ret_t lrc_builder_dump_on_id_tag(lrc_builder_t* builder, const char* id, const char* value) {
lrc_builder_dump_t* dump = (lrc_builder_dump_t*)builder;
str_append(&(dump->result), "[");
str_append(&(dump->result), id);
str_append(&(dump->result), ":");
str_append(&(dump->result), value);
str_append(&(dump->result), "]");
return RET_OK;
}
static ret_t lrc_builder_dump_on_time_tag(lrc_builder_t* builder, uint32_t timestamp) {
char buff[64];
uint32_t m = timestamp / (1000 * 60);
double s = (timestamp % (1000 * 60)) / 1000.0f;
lrc_builder_dump_t* dump = (lrc_builder_dump_t*)builder;
tk_snprintf(buff, sizeof(buff), "[%02d:%2.2f]", m, s);
str_append(&(dump->result), buff);
return RET_OK;
}
static ret_t lrc_builder_dump_on_text(lrc_builder_t* builder, const char* text) {
lrc_builder_dump_t* dump = (lrc_builder_dump_t*)builder;
str_append(&(dump->result), text);
return RET_OK;
}
static ret_t lrc_builder_dump_on_error(lrc_builder_t* builder, const char* error) {
lrc_builder_dump_t* dump = (lrc_builder_dump_t*)builder;
str_append(&(dump->result), error);
return RET_OK;
}
static ret_t lrc_builder_dump_destroy(lrc_builder_t* builder) {
lrc_builder_dump_t* dump = (lrc_builder_dump_t*)builder;
str_reset(&(dump->result));
TKMEM_FREE(builder);
return RET_OK;
}
static const lrc_builder_vtable_t s_lrc_builder_dump_vtable = {
.on_text = lrc_builder_dump_on_text,
.on_id_tag = lrc_builder_dump_on_id_tag,
.on_time_tag = lrc_builder_dump_on_time_tag,
.on_error = lrc_builder_dump_on_error,
.destroy = lrc_builder_dump_destroy,
};
lrc_builder_t* lrc_builder_dump_create(void) {
lrc_builder_dump_t* dump = TKMEM_ZALLOC(lrc_builder_dump_t);
return_value_if_fail(dump != NULL, NULL);
str_init(&(dump->result), 0);
dump->lrc_builder.vt = &s_lrc_builder_dump_vtable;
return (lrc_builder_t*)dump;
}
3.3 Builder的实现二(lrc.c)
lrc：这是默认的builder，它负责把lrc文件构建成内存中的结构，以便查询，其主要代码如下：
#include "tkc/mem.h"
#include "media_player/lrc/lrc.h"
#include "media_player/lrc/lrc_parser.h"
#include "media_player/lrc/lrc_builder.h"
typedef struct _lrc_builder_default_t {
lrc_builder_t lrc_builder;
lrc_t* lrc;
char* p;
char* strs;
uint32_t size;
} lrc_builder_default_t;
#define lrc_isspace(c) ((c) == ' ' || (c) == '\t' || (c) == '\n' || (c) == '\r')
static const char* lrc_builder_default_dup(lrc_builder_default_t* b, const char* text) {
char* p = b->p;
uint32_t size = strlen(text);
const char* start = text;
const char* end = start + size - 1;
while (*start && lrc_isspace(*start)) start++;
while (end > start && lrc_isspace(*end)) end--;
size = end - start + 1;
memcpy(p, start, size);
p[size] = '\0';
b->p += size + 1;
return p;
}
#define DUP(text) lrc_builder_default_dup(b, text)
static ret_t lrc_builder_default_on_id_tag(lrc_builder_t* builder, const char* id,
const char* value) {
lrc_builder_default_t* b = (lrc_builder_default_t*)builder;
lrc_id_tag_list_append(b->lrc->id_tags, DUP(id), DUP(value));
return RET_OK;
}
static ret_t lrc_builder_default_on_time_tag(lrc_builder_t* builder, uint32_t timestamp) {
lrc_builder_default_t* b = (lrc_builder_default_t*)builder;
lrc_time_tag_list_append(b->lrc->time_tags, timestamp);
return RET_OK;
}
static ret_t lrc_builder_default_on_text(lrc_builder_t* builder, const char* text) {
lrc_builder_default_t* b = (lrc_builder_default_t*)builder;
lrc_time_tag_list_set_text(b->lrc->time_tags, DUP(text));
return RET_OK;
}
static ret_t lrc_builder_default_on_error(lrc_builder_t* builder, const char* error) {
log_debug("error:%s\n", error);
return RET_OK;
}
static ret_t lrc_builder_default_destroy(lrc_builder_t* builder) {
lrc_builder_default_t* b = (lrc_builder_default_t*)builder;
b->lrc->strs = b->strs;
return RET_OK;
}
static const lrc_builder_vtable_t s_lrc_builder_default_vtable = {
.on_text = lrc_builder_default_on_text,
.on_id_tag = lrc_builder_default_on_id_tag,
.on_time_tag = lrc_builder_default_on_time_tag,
.on_error = lrc_builder_default_on_error,
.destroy = lrc_builder_default_destroy,
};
lrc_builder_t* lrc_builder_default_init(lrc_builder_default_t* b, lrc_t* lrc, char* strs,
uint32_t size) {
return_value_if_fail(strs != NULL, NULL);
b->lrc = lrc;
b->p = strs;
b->strs = strs;
b->size = size;
memset(strs, 0x00, size);
b->lrc_builder.vt = &s_lrc_builder_default_vtable;
return (lrc_builder_t*)b;
}
static lrc_t* lrc_parse(lrc_t* lrc, const char* text) {
ret_t ret = RET_OK;
lrc_builder_default_t builder;
uint32_t size = strlen(text) + 1;
char* strs = TKMEM_ALLOC(size);
lrc_builder_t* b = lrc_builder_default_init(&builder, lrc, strs, size);
ret = lrc_parser_parse(b, text);
lrc_time_tag_list_sort(lrc->time_tags);
lrc_builder_destroy(&builder);
return ret == RET_OK ? lrc : NULL;
}
lrc_t* lrc_create(const char* text) {
lrc_t* lrc = NULL;
return_value_if_fail(text != NULL, NULL);
lrc = TKMEM_ZALLOC(lrc_t);
return_value_if_fail(lrc != NULL, NULL);
lrc->id_tags = lrc_id_tag_list_create();
lrc->time_tags = lrc_time_tag_list_create();
if (lrc->id_tags == NULL || lrc->time_tags == NULL) {
lrc_destroy(lrc);
lrc = NULL;
}
return_value_if_fail(lrc != NULL, NULL);
if (lrc_parse(lrc, text) == NULL) {
lrc_destroy(lrc);
lrc = NULL;
}
return lrc;
}
ret_t lrc_destroy(lrc_t* lrc) {
return_value_if_fail(lrc != NULL, RET_BAD_PARAMS);
lrc_id_tag_list_destroy(lrc->id_tags);
lrc_time_tag_list_destroy(lrc->time_tags);
TKMEM_FREE(lrc->strs);
TKMEM_FREE(lrc);
return RET_OK;
}
3.4 产品（Product）
根据上篇 文章 中的描述，Product 就是 ConcreteBuilder 产生的结果，不同的 ConcreteBuilder 所产生的 Product 是不同的。
在上面的例子中，lrc_builder_dump 产生的 Product 是一段文本。而Builder默认的实现（lrc）产生的 Product 是一个数据结构，如下：
/**
* @class lrc_t
* lrc
*/
typedef struct _lrc_t {
/**
* @property {lrc_id_tag_list_t*} id_tags
* @annotation ["readable"]
* id tags。
*/
lrc_id_tag_list_t* id_tags;
/**
* @property {lrc_time_tag_list_t*} time_tags
* @annotation ["readable"]
* time tags。
*/
lrc_time_tag_list_t* time_tags;
/*private*/
char* strs;
} lrc_t;
3.5 解析器(Director)的工作过程
解析器的任务就是解析出 lrc 文件最基本的元素：时间标签、ID标签和歌词，然后调用builder相应的函数表示出来，此处仅做例子，完整代码请参考 lrc_parser.c 。
static ret_t lrc_parser_parse_tag(lrc_parser_t* parser) {
lrc_parser_skip_chars(parser, "\t \r\n");
if (parser->p[0] == '\0') {
return RET_OK;
}
if (isdigit(parser->p[0])) {
return lrc_parser_parse_time_tag(parser);
} else {
return lrc_parser_parse_id_tag(parser);
}
}
static ret_t lrc_parser_parse_impl(lrc_parser_t* parser) {
lrc_parser_skip_text(parser);
while (TRUE) {
char c = parser->p[0];
if (c == '\0') {
break;
}
if (c == '[') {
parser->p++;
lrc_parser_parse_tag(parser);
if (parser->p[0] == ']') {
parser->p++;
}
} else {
lrc_parser_parse_text(parser);
}
}
return RET_OK;
}
ret_t lrc_parser_parse(lrc_builder_t* builder, const char* str) {
lrc_parser_t p;
ret_t ret = RET_OK;
return_value_if_fail(lrc_parser_init(&p, builder, str) == RET_OK, RET_BAD_PARAMS);
ret = lrc_parser_parse_impl(&p);
lrc_parser_deinit(&p);
return ret;
}
3.6 调用者(Client)
有了 解析器（Parser）和 相应的Builder 后，调用者需要把它们组合起来。解析完成时，调用者还希望从 Builder 取出 Product，以便后面使用。例如此处调用 lrc_create() 函数解析歌词文本（text参数）即可，代码如下：
static lrc_t* lrc_parse(lrc_t* lrc, const char* text) {
ret_t ret = RET_OK;
lrc_builder_default_t builder;
uint32_t size = strlen(text) + 1;
char* strs = TKMEM_ALLOC(size);
lrc_builder_t* b = lrc_builder_default_init(&builder, lrc, strs, size);
ret = lrc_parser_parse(b, text);
lrc_time_tag_list_sort(lrc->time_tags);
lrc_builder_destroy(&builder);
return ret == RET_OK ? lrc : NULL;
}
lrc_t* lrc_create(const char* text) {
lrc_t* lrc = NULL;
return_value_if_fail(text != NULL, NULL);
lrc = TKMEM_ZALLOC(lrc_t);
return_value_if_fail(lrc != NULL, NULL);
lrc->id_tags = lrc_id_tag_list_create();
lrc->time_tags = lrc_time_tag_list_create();
if (lrc->id_tags == NULL || lrc->time_tags == NULL) {
lrc_destroy(lrc);
lrc = NULL;
}
return_value_if_fail(lrc != NULL, NULL);
if (lrc_parse(lrc, text) == NULL) {
lrc_destroy(lrc);
lrc = NULL;
}
return lrc;
}