EPICS base macLib库解析与测试
文件： macLib.h
简述：文本宏替换的例程
这个通用宏替换库用于EPICS base中所有宏替换。大部分例程成功返回0(OK),出错返回-1(ERROR)，或者对应其它信息的小整数。macGetValue() 和 macExpandString()是这个的例外，并且返回有关成功/失败的和有关value长度的信息。使用errlogPrintf()报告出错和警告。
简述： 宏名和值的最大尺寸
#define MAC_SIZE 256简述： 宏替换的上下文，仅由macLib例程使用 . 如果需要， 一个程序可以有多个活动的上下文.
typedef struct {
long magic; /**< 用于验证的魔术值 */
int dirty; /**< 需要从原始值展开的值? */
int level; /**< 作用域 */
int debug; /**< 调试级别 */
ELLLIST list; /**< 宏名/值列表 */
int flags; /**< 操作模式标志 */
} MAC_HANDLE;核心库：核心库提供了一个基本操作的最小集合。
简述：创建一个新的宏替换上下文 .
返回： 0 = OK; <0 = ERROR
LIBCOM_API long epicsStdCall macCreateHandle(
MAC_HANDLE **handle, /**< 指向一个变量的指针，此变量接收一个指向新的宏替换上下文的指针 */
const char * pairs[] /**< 指向{name,value}对字符串的NULL结尾数组的指针。一个NULL值隐含未被定义，一个NULL对参数隐含没有宏 */
);
禁用或启用警告消息 .
当macExpandString()不能展开一个宏时，例程打印警告。这个程序可以用于静默那些消息。对于相同的句柄，一个非0值将禁止来自后续库例程的警告消息。
LIBCOM_API void epicsStdCall macSuppressWarning(
MAC_HANDLE *handle, /**< 不透明句柄 */
int falseTrue /**< 0表示发出, 1表示禁止*/
);
简述：展开一个可能包含宏引用的字符串 .
返回：返回被展开字符串的长度，如果宏未被定义，<0。这个例程解析src字符串，查找宏引用并且传递它找到的任何宏给macGetValue()来翻译。
注意： 返回值类似于macGetValue()的返回值。它的绝对值时被复制到dest的字符数目。如果返回值是负数，至少一个未被定义的宏被留下未被展开。
LIBCOM_API long epicsStdCall macExpandString(
MAC_HANDLE *handle, /**< 不透明句柄 */
const char *src, /**< 源字符串 */
char *dest, /**< 目标字符串 */
long capacity /**< 目标缓存的容量(dest) */
);
简述：设置一个特定的宏的值 .
返回： 返回这个value字符串的长度。
如果value是NULL，解除定义所有作用域的name的所有实例。(指定名称的宏在这种情况中不是必须存在的)。在value中引用的宏不需要在此处被定义。
LIBCOM_API long epicsStdCall macPutValue(
MAC_HANDLE *handle, /**< 不透明句柄 */
const char *name, /**< 宏名 */
const char *value /**< 宏值 */
);
简述：返回一个宏的值
返回： 返回这个value字符串的长度，如果未定义，<0
如果这个值的长度少于capacity，value将是0结尾的。 返回值是被复制到value的字符数目(如果宏未被定义， 行为见以下)。
如果capacity是0， 没有字符将被复制到value(其可以是NULL)，并且调用可以用于检查这个宏是否被定义。 注意： 不报告这个value的截断，程序应该认为如果返回值等于capacity，截断已经发生。
如果宏未被定义，(如果maxlen允许)宏引用将在value字符串中被返回，并且这个函数值将时被复制的最少字符。注意： capacity用于保持与strncpy()例程保持一致。如果这个值包含宏引用，这些引用将被递归地展开。这个展开将探测一个直接或间接的自引用。
宏引用以一个"$"后面紧跟一个"("或一个"{"开始。宏名接着出现，并且能够可选地后跟一个"="和一个默认值， 一个引用是以一个匹配的")"或"}"字符结束。
LIBCOM_API long epicsStdCall macGetValue(
MAC_HANDLE *handle, /**< 不透明的句柄 */
const char *name, /**< 宏名或引用 */
char *value, /**< 如果宏未被定义， 接收宏值或名称参数的字符串。*/
long capacity /**< 目标缓存(value)的容量*/
);
简述： 标记一个句柄无效，并且释放与它相关联的所有存储
返回： 0 = OK; <0 = ERROR
注意： 这个不释放已经返回宏值所在的任何字符串。宏值总是被返回到由调用者先前分配的字符串。
LIBCOM_API long epicsStdCall macDeleteHandle(
MAC_HANDLE *handle /**< 不透明的句柄 */
);
标记一个新的作用域的开始
返回： 0 = OK; <0 = ERROR
标记在这个调用之后的所有宏定义属于另一个作用域。这些宏将在一个macPopScope()时丢失，
而在当前作用域的那些宏将被重新安装。
LIBCOM_API long epicsStdCall macPushScope(
MAC_HANDLE *handle /**< 不透明的句柄 */
);
简述： 获取上次被压栈的作用域(像栈操作)
返回：0 = OK; <0 = ERROR
见 macPushScope()
LIBCOM_API long epicsStdCall macPopScope(
MAC_HANDLE *handle /**< 不透明的句柄 */
);
简述：报告当前定义细节
返回： 0 = OK; <0 = ERROR
这发送当前定义的细节到标准输出，并且仅用于调试目的
LIBCOM_API long epicsStdCall macReportMacros(
MAC_HANDLE *handle /**< opaque handle */
);工具库
这些便捷函数是用于程序，出于某些目的，使用和提供一个更方便的接口。
简述： 解析宏定义未一个{name, value}对的数组。
返回：找到的宏的数目; <0 = ERROR
这接收"a=xxx,b=yyy"格式的宏定义集合，并且转换它们未一个指向字符串的指针的数组，
这个数组以两个NULL指针终结，并且所有存储区是被连续分配的，因而，可以用单个free()调用释放它们。这个例程独立于任何句柄， 并且提供了可以在别处使用的通用有用的服务。在值中任何宏引用在宏实际必须被转换前可以被定义或者重新定义。
支持shell风格转义和引号，如像"A=B,B=$(C$(A)),CA=CA,CB=CB" (设置 B 为 "CB")的定义。
空白在值中是重要的，但在别处被忽略(即： 在"="和','字符周围)
这个函数返回遇到的定义数目，如果提供的字符串无效，为-1
LIBCOM_API long epicsStdCall macParseDefns(
MAC_HANDLE *handle, /**< 不透明的句柄，如果不需要调试消息，可以是NULL。*/
const char *defns, /**< "a=xxx,b=yyy"格式的宏定义 */
char **pairs[] /**< 接收指向{name, value}对字符串的NULL终结的数组的指针的变量地址所有存储是连续分配的 */
);
简述： 安装{name, value}对的集合作为定义
返回： 定义的宏的数目，<0=ERROR
这接收一个以上定义的对的数组，并且通过调用macPutValue()安装它们作为定义。
对数组是由一个NULL指针终结。
LIBCOM_API long epicsStdCall macInstallMacros(
MAC_HANDLE *handle, /**< 不透明的句柄 */
char *pairs[] /**< 指向{name,value}对字符串的NULL结尾的数组的指针，一个NULL值表示解除定义，
一个NULL参数表示没有宏 */
);
简述：展开在字符串中的环境变量
返回： 展开的字符串，如果使用任何未定义的宏，NULL。
这个里车工展开一个字符串，它可能包含了宏引用引用。它解析这个字符串，查找这些引用并且传递它们给macGetValue来转换。它使用malloc()来为被展开字符串分配空间，并且返回一个指向这个null结尾的字符串的指针。如果这个源字符串包含任何未定义的引用，它返回NULL。
LIBCOM_API char * epicsStdCall macEnvExpand(
const char *str /**< 待被展开的字符串 */
);
简述： 展开在字符串中的宏和环境变量
返回： 展开的字符串，如果使用任何未定义的宏，NULL。
这个例程类似于macEnvExpand()，但它允许传入一个可选的句柄，其可能包含更多的宏定义。
在展开这个字符串时， 从环境变量追加这些宏到宏的集合。
LIBCOM_API char * epicsStdCall macDefExpand(
const char *str, /**< 待被展开的字符串 */
MAC_HANDLE *macros /**< 不透明的句柄， 如果仅使用环境变量，可以是NULL */
);测试macLib.h中每个函数的测试程序，如下：
#include
#include
#include
#include "macLib.h"
int main()
{
MAC_HANDLE * handle = NULL;
char ** ppairs;
printf("Test function: macCreateHandle\n");
macCreateHandle(&handle, NULL);
if (handle == NULL){
printf("can not create handle\n");
return -1;
}
char defns[] = "name=greatwall,location=beijing";
int len;
printf("Test function: macParseDefns\n");
//len = macParseDefns(handle, defns, &ppairs);
len = macParseDefns(NULL , defns, &ppairs);
printf("The length of %s is %d\n", defns, len);
int i;
for (i = 0; i < 2; i++){
printf("%d: key:%s, value: %s\n", i+1, ppairs[i * 2], ppairs[i * 2 + 1] );
}
printf("Test function: macInstallMacros\n");
len = macInstallMacros(handle, ppairs);
printf("The number of macros : %d\n", len);
printf("Call funtion: macPutValue\n");
macPutValue(handle, "sport", "walk");
char name[100];
memset(name, 0, sizeof(name));
char value[100];
memset(value, 0, sizeof(value));
printf("Test function: macGetValue\n");
strcpy(name, "name");
len = macGetValue(handle, name, value, sizeof(value));
printf("len = %d\n", len);
printf("name: %s expanded to value: %s\n", name, value);
printf("Test function : macExpandString\n");
memset(name, 0, sizeof(name));
memset(value, 0, sizeof(value));
strcpy(name, "name: ${name} location: ${location} sport: ${sport}");
macExpandString(handle, name, value, sizeof(value));
printf("%s is expanded to %s\n", name, value);
printf("Call macEnvExpand:\n");
char * pvalue = macEnvExpand("${EPICS_CA_ADDR_LIST}");
printf("EPICS_CA_ADDR_LIST: %s\n", pvalue);
free(pvalue);
printf("Call function: macReportMacros\n");
macReportMacros(handle);
printf("Call function: macDeleteHandle\n");
macDeleteHandle( handle );
free(ppairs);
return 0;
}
测试结果如下：
orangepi@orangepi5:~/C_program/host_program/hostApp$ O.linux-aarch64/testMacLib
Test function: macCreateHandle
Test function: macParseDefns
The length of name=greatwall,location=beijing is 2
1: key:name, value: greatwall
2: key:location, value: beijing
Test function: macInstallMacros
The number of macros : 2
Call funtion: macPutValue
Test function: macGetValue
len = 9
name: name expanded to value: greatwall
Test function : macExpandString
name: ${name} location: ${location} sport: ${sport} is expanded to name: greatwall location: beijing sport: walk
Call macEnvExpand:
EPICS_CA_ADDR_LIST: 192.168.50.25 192.168.50.234:5092 192.168.50.234:5100
Call function: macReportMacros
e name rawval value
- ---- ------ -----
name greatwall greatwall
location beijing beijing
sport walk walk
Call function: macDeleteHandle