From e8c135ba0c364e8b314f0d6d5afcc753c240367f Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Mon, 23 Oct 2023 15:55:51 +0200 Subject: [PATCH] Documentaion: migrate fsutils/inifile readme --- Documentation/applications/fsutils/index.rst | 8 +- .../applications/fsutils/inifile/index.rst | 146 ++++++++++++++++++ 2 files changed, 153 insertions(+), 1 deletion(-) create mode 100644 Documentation/applications/fsutils/inifile/index.rst diff --git a/Documentation/applications/fsutils/index.rst b/Documentation/applications/fsutils/index.rst index a24d54c3c8..965afc4adc 100644 --- a/Documentation/applications/fsutils/index.rst +++ b/Documentation/applications/fsutils/index.rst @@ -2,8 +2,14 @@ File System Utilities ===================== +.. toctree:: + :glob: + :maxdepth: 3 + :titlesonly: + + */* + - flash_eraseall - flash_eraseall() function -- inifile - INI File Parser - inih - inih ini file parser - ipcfg - IP Configuration File Support - libtinycbor - TinyCBOR Library (RFC 8949) diff --git a/Documentation/applications/fsutils/inifile/index.rst b/Documentation/applications/fsutils/inifile/index.rst new file mode 100644 index 0000000000..17ee17a227 --- /dev/null +++ b/Documentation/applications/fsutils/inifile/index.rst @@ -0,0 +1,146 @@ +=========================== +``inifile`` INI File Parser +=========================== + +Syntax +------ + +This directory contains a very simple INI file parser. An INI file consists of a +sequence of lines up to the end of file. A line may be one of the following: + +1. A blank line. + +2. A comment line. Any line beginning with ``;`` + +3. A section header. Definitions are divided into sections. Each section begins + with a line containing the section name enclosed in square brackets. For + example, ``[section1]``. The left bracket must be the first character on the + line. Section names are case insensitive, i.e., ``SECTION1`` and ``Section1`` + refer to the same section. + +4. Variable assignments. A variable assignment is a variable name followed by + the ``=`` sign and then the value of the variable. For example, ``A=B``: ``A`` is + the variable name; ``B`` is the variable value. All variables following the + section header belong in the section. + + Variable names may be preceded with white space. Whitespace is not permitted + before the ``=`` sign. Variable names are case insensitive, i.e., ``A`` and ``a`` + refer to the same variable name. + + Variable values may be numeric (any base) or a string. The case of string + arguments is preserved. + +Programming Interfaces +---------------------- + +See ``apps/include/fsutils/inifile.h`` for interfaces supported by the INI file +parser. + +## Test Program + +Below is a simple test program: + +.. code-block:: C + + int main(int argc, char *argv[]) + { + INIHANDLE handle; + FILE *stream; + FAR char *ptr; + long value; + + stream = fopen("/tmp/file.ini", "w"); + fprintf(stream, "; Test INI file\n"); + fprintf(stream, "[section1]\n"); + fprintf(stream, " VAR1=1\n"); + fprintf(stream, " VAR2=2\n"); + fprintf(stream, " VAR3=3\n"); + fprintf(stream, "\n"); + fprintf(stream, "[section2]\n"); + fprintf(stream, " VAR4=4\n"); + fprintf(stream, " VAR5=5\n"); + fprintf(stream, "VAR6=6\n"); + fprintf(stream, "\n"); + fclose(stream); + + handle = inifile_initialize("/tmp/file.ini"); + + ptr = inifile_read_string(handle, "section2", "VAR5", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section2", "VAR5", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section1", "VAR2", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section1", "VAR2", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section3", "VAR3", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section3", "VAR3", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section1", "VAR3", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section1", "VAR3", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section1", "VAR1", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section1", "VAR1", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section1", "VAR42", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section1", "VAR42", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section2", "VAR6", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section2", "VAR6", ptr); + inifile_free_string(ptr); + + ptr = inifile_read_string(handle, "section2", "VAR4", "OOPS"); + printf("Section: %s Variable: %s String: %s\n", "section2", "VAR4", ptr); + inifile_free_string(ptr); + + value = inifile_read_integer(handle, "section1", "VAR3", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section1", "VAR3", value); + + value = inifile_read_integer(handle, "section3", "VAR3", 0); + printf("Section: %s Variable: %s String: %ld\n", "section3", "VAR3", value); + + value = inifile_read_integer(handle, "section1", "VAR1", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section1", "VAR1", value); + + value = inifile_read_integer(handle, "section2", "VAR5", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section2", "VAR5", value); + + value = inifile_read_integer(handle, "section2", "VAR6", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section2", "VAR6", value); + + value = inifile_read_integer(handle, "section1", "VAR42", 0); + printf("Section: %s Variable: %s String: %ld\n", "section1", "VAR42", value); + + value = inifile_read_integer(handle, "section1", "VAR2", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section1", "VAR2", value); + + value = inifile_read_integer(handle, "section2", "VAR4", 0); + printf("Section: %s Variable: %s Value: %ld\n", "section2", "VAR4", value); + + inifile_uninitialize(handle); + return 0; + } + +Test program output:: + + Section: section2 Variable: VAR5 String: 5 + Section: section1 Variable: VAR2 String: 2 + Section: section3 Variable: VAR3 String: OOPS + Section: section1 Variable: VAR3 String: 3 + Section: section1 Variable: VAR1 String: 1 + Section: section1 Variable: VAR42 String: OOPS + Section: section2 Variable: VAR6 String: 6 + Section: section2 Variable: VAR4 String: 4 + + Section: section1 Variable: VAR3 Value: 3 + Section: section3 Variable: VAR3 Value: 0 + Section: section1 Variable: VAR1 Value: 1 + Section: section2 Variable: VAR5 Value: 5 + Section: section2 Variable: VAR6 Value: 6 + Section: section1 Variable: VAR42 String: 0 + Section: section1 Variable: VAR2 Value: 2 + Section: section2 Variable: VAR4 Value: 4