inih

inih（INI 不是这里发明的）

inih（INI Not Invented Here）是一个用 C 语言编写的简单的 .INI 文件解析器。它只有几页代码，并且被设计得小而简单，因此它非常适合嵌入式系统。它还或多或少地与 Python 的 ConfigParser 风格的 .INI 文件兼容，包括 RFC 822 风格的多行语法和name: value条目。

要使用它，只需给ini_parse()一个 INI 文件，它就会为解析的每个name=value对调用回调，为您提供部分、名称和值的字符串。它以这种方式完成（“SAX 风格”），因为它在低内存嵌入式系统上运行良好，而且还因为它适合 KISS 实现。

您还可以调用ini_parse_file()来直接从FILE*对象进行解析， ini_parse_string()来解析字符串中的数据，或者调用ini_parse_stream()来使用自定义 I/O 的自定义 fgets 样式读取器函数进行解析。

下载版本、浏览源代码或阅读有关如何通过 X-Macros 以 DRY 风格使用 inih 的信息。

编译时选项

您可以使用预处理器定义来控制 inih 的各个方面：

语法选项

• 多行条目：默认情况下，inih 支持 Python ConfigParser 风格的多行条目。要禁用，请添加-DINI_ALLOW_MULTILINE=0 。
• UTF-8 BOM：默认情况下，inih 允许在 INI 文件的开头使用 UTF-8 BOM 序列 (0xEF 0xBB 0xBF)。要禁用，请添加-DINI_ALLOW_BOM=0 。
• 内联注释：默认情况下，inih 允许使用 ; 进行内联注释;特点。要禁用，请添加-DINI_ALLOW_INLINE_COMMENTS=0 。您还可以使用INI_INLINE_COMMENT_PREFIXES指定哪些字符开始内联注释。
• 行首注释：默认情况下，inih 允许;和#在行首开始注释。您可以通过更改INI_START_COMMENT_PREFIXES来覆盖此设置。
• 不允许无值：默认情况下，inih 将没有值的名称（行上没有= : :）视为错误。要允许没有值的名称，请添加-DINI_ALLOW_NO_VALUE=1 ，inih 将调用您的处理函数，并将值设置为 NULL。

解析选项

• 出现第一个错误时停止：默认情况下，inih 在出现错误后继续解析文件的其余部分。要在出现第一个错误时停止解析，请添加-DINI_STOP_ON_FIRST_ERROR=1 。
• 报告行号：默认情况下， ini_handler回调不接收行号作为参数。如果需要，请添加-DINI_HANDLER_LINENO=1 。
• 在新部分上调用处理程序：默认情况下，inih 仅在每个name=value对上调用处理程序。要检测新部分（例如，INI 文件具有多个同名部分），请添加-DINI_CALL_HANDLER_ON_NEW_SECTION=1 。然后，每次遇到新节时都会调用处理函数， section设置为新节名称，但name和value设置为 NULL。

内存选项

• 堆栈与堆：默认情况下，inih 在堆栈上创建固定大小的行缓冲区。要使用malloc在堆上分配，请指定-DINI_USE_STACK=0 。
• 最大行长度：默认最大行长度（对于堆栈或堆）为 200 字节。要覆盖此设置，请添加类似-DINI_MAX_LINE=1000内容。请注意， INI_MAX_LINE必须比最长行多 3（由于r 、 n和 NUL）。
• 初始malloc大小： INI_INITIAL_ALLOC指定使用堆时的初始malloc大小。默认为 200 字节。
• 允许重新分配：默认情况下，使用堆 ( -DINI_USE_STACK=0 ) 时，inih 分配INI_INITIAL_ALLOC字节的固定大小缓冲区。要允许其增长到INI_MAX_LINE字节（如果需要则加倍），请设置-DINI_ALLOW_REALLOC=1 。
• 自定义分配器：使用堆时默认使用标准库的malloc 、 free和realloc函数；要使用自定义分配器，请指定-DINI_CUSTOM_ALLOCATOR=1 （和-DINI_USE_STACK=0 ）。您必须定义并链接名为ini_malloc 、 ini_free和（如果设置了INI_ALLOW_REALLOC ） ini_realloc的函数，它们必须具有与stdlib.h内存分配函数相同的签名。

C 中的简单示例

 #include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "../ini.h"

typedef struct
{
    int version ;
    const char * name ;
    const char * email ;
} configuration ;

static int handler ( void * user , const char * section , const char * name ,
                   const char * value )
{
    configuration * pconfig = ( configuration * ) user ;

    #define MATCH ( s , n ) strcmp(section, s) == 0 && strcmp(name, n) == 0
    if ( MATCH ( "protocol" , "version" )) {
        pconfig -> version = atoi ( value );
    } else if ( MATCH ( "user" , "name" )) {
        pconfig -> name = strdup ( value );
    } else if ( MATCH ( "user" , "email" )) {
        pconfig -> email = strdup ( value );
    } else {
        return 0 ;  /* unknown section/name, error */
    }
    return 1 ;
}

int main ( int argc , char * argv [])
{
    configuration config ;

    if ( ini_parse ( "test.ini" , handler , & config ) < 0 ) {
        printf ( "Can't load 'test.ini'n" );
        return 1 ;
    }
    printf ( "Config loaded from 'test.ini': version=%d, name=%s, email=%sn" ,
        config . version , config . name , config . email );
    return 0 ;
}

C++ 示例

如果您喜欢 C++ 和 STL，还有一个易于使用的 INIReader 类，它将值存储在map中并允许您Get()它们：

# include < iostream >
# include " INIReader.h "

int main ()
{
    INIReader reader ( " ../examples/test.ini " );

    if (reader. ParseError () < 0 ) {
        std::cout << " Can't load 'test.ini' n " ;
        return 1 ;
    }
    std::cout << " Config loaded from 'test.ini': version= "
              << reader. GetInteger ( " protocol " , " version " , - 1 ) << " , name= "
              << reader. Get ( " user " , " name " , " UNKNOWN " ) << " , email= "
              << reader. Get ( " user " , " email " , " UNKNOWN " ) << " , pi= "
              << reader. GetReal ( " user " , " pi " , - 1 ) << " , active= "
              << reader. GetBoolean ( " user " , " active " , true ) << " n " ;
    return 0 ;
}

这个简单的 C++ API 工作得很好，但还不是很成熟。我目前不打算在 C++ API 上进行更多工作，因此如果您想要更多功能（例如GetSections()和GetFields()函数），请参阅这些分支：

• https://github.com/Blandinium/inih
• https://github.com/OSSystems/inih

与 ConfigParser 的区别

inih 和 Python 的 ConfigParser 标准库模块之间的一些区别：

• 上面给出的 INI 名称=值对，任何节标题都被视为没有节的有效项目（节名称是空字符串）。在 ConfigParser 中没有部分是一个错误。
• 行延续是通过连续行上的前导空格来处理的（如 ConfigParser）。但是，它们不是将连续的行连接在一起，而是被视为同一键的单独值（与 ConfigParser 不同）。

特定于平台的注释

• Windows/Win32 本身使用 UTF-16 文件名，因此要处理 Unicode 路径，您需要调用_wfopen()打开文件，然后调用ini_parse_file()解析它； inih 不包括wchar_t或 Unicode 处理。

介子笔记

• meson.build文件不需要使用或编译 inih，它的主要目的是用于发行版。
• 默认情况下，Meson 是为发行版安装设置的，但可以针对嵌入式用例配置此行为：
  • 使用-Ddefault_library=static构建静态库。
  • 使用-Ddistro_install=false库、标头和 pkg-config 文件将不会被安装。
  • 使用-Dwith_INIReader=false可以禁用构建 C++ 库。
• 所有编译时选项也在 Meson 中实现，您可以查看 meson_options.txt 了解它们的定义。如果distro_install设置为true ，这些将不起作用。
• 如果您想将 inih 用于可能在发行版中提供的程序，请考虑链接共享库。 pkg-config 条目是inih和INIReader 。
• 如果您使用 inih 作为 Meson 子项目，则可以使用inih_dep和INIReader_dep依赖变量。您可能需要为子项目设置default_library=static和distro_install=false 。 WrapDB 上提供了官方的 Wrap。
• 对于打包者：如果您想在 pkg-config 文件中标记版本，则需要在下游执行此操作。添加version : '<version_as_int>',位于project()函数中的license标记之后，以及version : meson.project_version(),位于两个library()函数中的soversion标记之后。

将inih 与tipi.build 一起使用

只需将以下条目添加到.tipi/deps中（将r56替换为最新版本标记），即可在 tipi.build 项目中轻松使用inih ：

{
    "benhoyt/inih" : { "@" : " r56 " }
}

项目中所需的包含路径是：

 #include <ini.h> 

从 vcpkg 构建

您可以使用 vcpkg 依赖管理器构建和安装 inih：

 git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install inih

vcpkg 中的 inih 端口由 Microsoft 团队成员和社区贡献者保持最新。如果版本已过时，请在 vcpkg 存储库上创建问题或拉取请求。

相关链接

• inih 的 Conan 包（Conan 是 C/C++ 包管理器）