# fastxml

**Repository Path**: fangbinbin1990/fastxml

## Basic Information

- **Project Name**: fastxml
- **Description**: 纯C编写的XML解析引擎
- **Primary Language**: C
- **License**: BSD-3-Clause-Clear
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 27
- **Created**: 2019-07-18
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fastxml 纯C语言编写的XML解析库 #

## 什么是fastxml? ##

**fastxml是一款支持XML解析的多根节点的解析引擎，支持特性如下：**

- 支持多根 **XML**，一个 **XML** 文档支持多个 ROOT 标记，如下包含`information` 和 `list`：

  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <information>
      <name>Josin</name>
      <age>26</age>
      <address>Changsha</address>
  </information>
  
  <list>
  	<name>Linux</name>
  	<version>v5.0.1</version>
  	<tool>Git</tool>
  </list>
  ```

- 支持XML文档声明，声明必须位于第一行，以及众多属性，标准的XML声明如下：

  ```xml
  <?xml version="1.0" encoding="UTF-8" author="Josin"?>
  ```

- 支持标记的属性特性，如下面的 `information` 标记包含的 `id` 和 `pid` 属性：

  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <information id="11" pid="99">
      <name>Josin</name>
      <age>26</age>
      <address>Changsha</address>
  </information>
  ```

- 支持注释，**注意：注释不可以嵌套**

  ```xml
  <?xml version="1.0" encoding="UTF-8"?>
  <information id="11" pid="99">
      <!--<name>Josin</name>-->
      <age>2<!--6--></age>
      <address>Changsha</address>
  </information>
  ```

- 支持 **CDATA标记** 防止浏览器转义

  ```xml
  <?xml version="1.0" encoding="UTF-8" author="Josin"?>
  <!--This is the comments-->
  <information>
      <name><![CDATA[Josin]]></name>
      <!--<age>26</age>-->
      <address>Hunan</address>
  </information>
  ```

## 编译 & 运行 ##

**fastxml** 使用纯C99语法编写，可以使用在支持标准C99的操作系统上，**fastxml**使用 cmake编译管理系统，推荐版本 3.13以及以上

```c
git clone https://gitee.com/josinli/fastxml.git
cd fastxml
mkdir build
cd build
cmake .. && make 
./fastxml	
```

## APIs 列表

- 从字符串解析 **XML**，返回 **NULL** 表示XML文件格式错误

```c
CXML *new_cxml_from_string(char *str, unsigned long long);
```

- 从CXML文件信息，解码为字符串，返回的字符串需要通过 **free** 函数释放

```c
char *new_string_from_cxml(CXML *c);
```

- 释放编码后的 **CXML** 信息

```c
int   trash_cxml(CXML *v);
```

### 快捷操作宏 ###

```
// 用来定义一个 CXML_n 的结构来存储解码后的XML信息
CXML_FIELD_DEF(n)
// 中间使用 *aname 来定义一个节点名称， 前面的 * 不能省略
CXML_FIELD_DEF_END(n);
```

```c
// 用来声明函数，用来在其他的文件引入声明
CXML_FIELD_FUNC_DEF(n);
```

```c
// 上面的声明的实现文件
CXML_FIELD_FUNC(n)
  // 存在多个节点，信息，就定义多行
  // 第一个参数对应 XML的节点名称，大小写区分
  // 第二个参数对应上面第一步 CXML_FIELD_DEF(n) 中定义的名称，去掉前缀 *
  // 第三个参数对应第一个参数的字符个数
  // 第四个参数可选 if 或者 elif 第一行必须为 if
  CXML_FIELD_CMP(name, aname, l, e)
CXML_FIELD_FUNC_END();
```

**操作属性的宏，跟操作节点的宏只是中间的 FIELD 变更为 ATTR，如下是操作XML节点属性的宏列表**

```
// 用来定义一个 CXML_n 的结构来存储解码后的XML信息
CXML_ATTR_DEF(n)
// 中间使用 *aname 来定义一个节点名称， 前面的 * 不能省略
CXML_ATTR_DEF_END(n);
```

```
// 用来声明函数，用来在其他的文件引入声明
CXML_ATTR_FUNC_DEF(n);
```

```
// 上面的声明的实现文件
CXML_ATTR_FUNC(n)
  // 存在多个节点，信息，就定义多行
  // 第一个参数对应 XML的节点名称，大小写区分
  // 第二个参数对应上面第一步 CXML_FIELD_DEF(n) 中定义的名称，去掉前缀 *
  // 第三个参数对应第一个参数的字符个数
  // 第四个参数可选 if 或者 elif 第一行必须为 if
  CXML_ATTR_CMP(name, aname, l, e)
CXML_ATTR_FUNC_END();
```

## 怎么快速在C语言或者C++操作XML? ##

**fastxml** 自定了一系列的宏，来方便操作XML文档，可以使用宏来快速完成XML文档的解析与编码，如下简短示例，针对于下面的 **XML**文档，我们来看看我们的解析过程：

```xml
<?xml version="1.0" encoding="UTF-8" author="Josin" ?>
<!--Hello This is the comments-->
<info>
    <name><![CDATA[Josin]]></name>
    <address>Hunan</address>
</info>
```

### 操作流程如下：

1. 新建 .h 和 .c 文件，如下命名为 **xml_demo.c** 和 **xml_demo.h**， 内容如下：

   - **xml_demo.h** 文件内容如下：

   ```c
   #include <fc_xml.h>
   
   /**
    * @brief NOTICE
    * Simple example for using the macros
    */
   CXML_FIELD_DEF(root) /* 括号内的info可以随意填写，如下相同 */
       *info /* 这里写上需要解析的 同级XML 节点名称，上面的xml最外层的只有一个 info节点，所以只有 *info */
   CXML_FIELD_DEF_END(root);
   CXML_FIELD_FUNC_DEF(root);
   ```

   - **xml_demo.c** 内容如下：

   ```c
   CXML_FIELD_FUNC(root)
       CXML_FIELD_CMP(info,    info,    4,   if) // 第一个宏参数表示的解析的节点名称，如果在上面的宏里面定义了 CXML_FIELD_DEF里面需要解析到一个不同的变量，可以定义第二个别名参数， 第三个参数表示的是第一个参数的字符长度， 最后一个可以使 if 或者 elif，第一个限制为if，后续的为 elif
   CXML_FIELD_FUNC_END(root);
   ```

2. 在 main.c中开始解析过程：

   ```c
   #include <stdio.h>
   #include <xml_demo.h>
   
   int main(int argc, char *argv[])
   {
       char *xml_str = "<?xml version=\"1.0\" encoding=\"UTF-8\" author=\"Josin\" ?>\n"
                       "<!--Hello This is the comments-->\n"
                       "<info>\n"
                       "    <name><![CDATA[Josin]]></name>\n"
                       "    <address>Hunan</address>\n"
                       "</info>";
       CXML *xml = new_cxml_from_string(xml_str, strlen(xml_str));
       
       if ( !xml ) {
           printf("Your xml format is wrong.");
           trash_cxml(xml);
           return 0;
       }
       
       CXML_root *root = NEW_CXML_root_FROM_DATA(xml->data);
       printf("Root name: %s\n", root->info->key);
       TRASH_CXML_root(root);
       trash_cxml(xml);
   }
   ```

   输出如下：

   ```shell
   Root name: info
   ```

3. 因为这里的info节点是一个最外层的节点，它的值是一些子节点，所以如果需要解析他的子节点信息，需要重复上面的步骤，下面是一个整的示例，demo在demo目录中：

**xml_demo.h  内容如下：**

```c
#include <fc_xml.h>

/**
 * @brief NOTICE
 * Simple example for using the macros
 */
CXML_FIELD_DEF(root)
    *info
CXML_FIELD_DEF_END(root);
CXML_FIELD_FUNC_DEF(root);

CXML_FIELD_DEF(info)
    *name, *age, *addr
CXML_FIELD_DEF_END(info);
CXML_FIELD_FUNC_DEF(info);
```

**xml_demo.c 内容如下：**

```c
#include <xml_demo.h>


/**
 * @brief NOTICE
 * Simple example for parsing the XML data
 */
CXML_FIELD_FUNC(root)
    CXML_FIELD_CMP(info,   info,    4, elif)
CXML_FIELD_FUNC_END();

CXML_FIELD_FUNC(info)
    CXML_FIELD_CMP(name,    name,    4,   if)
    CXML_FIELD_CMP(address, addr,    7, elif)
CXML_FIELD_FUNC_END();
```

**main.c 内容如下：**

```
#include <stdio.h>
#include <xml_demo.h>


int main(int argc, char *argv[])
{
    char *xml_str = "<?xml version=\"1.0\" encoding=\"UTF-8\" author=\"Josin\" ?>\n"
                    "<!--Hello This is the comments-->\n"
                    "<info>\n"
                    "    <name><![CDATA[Josin]]></name>\n"
                    "    <address>Hunan</address>\n"
                    "</info>";
    CXML *xml = new_cxml_from_string(xml_str, strlen(xml_str));
    
    if ( !xml ) {
        printf("Your xml format is wrong.");
        trash_cxml(xml);
        return 0;
    }
    
    CXML_root *root = NEW_CXML_root_FROM_DATA(xml->data);
    printf("Root name: %s\n", root->info->key);
    
    CXML_info *info = NEW_CXML_info_FROM_DATA(root->info->val);

    printf("%s: %s\n", info->name->key, (char *)info->name->val);
    printf("%s: %s\n", info->addr->key, (char *)info->addr->val);

    TRASH_CXML_info(info);
    TRASH_CXML_root(root);
    trash_cxml(xml);
    
    return 0;
}
```