You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
minIni is a portable and configurable library for reading and writing ".INI" files. At roughly 950 lines of commented source
3
-
code, minIni truly is a "mini" INI file parser, especially considering its features.
2
+
minIni is a portable and configurable library for reading and writing ".INI" files. At less than a thousand lines of
3
+
commented source code, minIni truly is a "mini" INI file parser, especially considering its features.
4
4
5
-
The library does not require the file I/O functions from the standard C/C++ library, but instead lets you configure
6
-
the file I/O interface to use via macros. minIni uses limited stack space and does not use dynamic memory (malloc and
5
+
The library does not require the file I/O functions from the standard C/C++ library, but instead lets you configure
6
+
the file I/O interface to use via macros. minIni uses limited stack space and does not use dynamic memory (malloc and
7
7
friends) at all.
8
8
9
9
Some minor variations on standard INI files are supported too, notably minIni supports INI files that lack sections.
@@ -13,15 +13,15 @@ Some minor variations on standard INI files are supported too, notably minIni su
13
13
14
14
minIni is derived from an earlier INI file parser (which I wrote) for desktop systems.
15
15
16
-
In turn, that earlier parser was a re-write of the code from the article "Multiplatform .INI Files" by Joseph J. Graf
17
-
in the March 1994 issue of Dr. Dobb's Journal. In other words, minIni has its roots in the work of Joseph Graf (even
16
+
In turn, that earlier parser was a re-write of the code from the article "Multiplatform .INI Files" by Joseph J. Graf
17
+
in the March 1994 issue of Dr. Dobb's Journal. In other words, minIni has its roots in the work of Joseph Graf (even
18
18
though the code has been almost completely re-written).
19
19
20
20
21
21
# Features
22
22
23
-
minIni is a programmer's library to read and write "INI" files in embedded systems. minIni takes little resources,
24
-
can be configured for various kinds of file I/O libraries and provides functionality for reading, writing and
23
+
minIni is a programmer's library to read and write "INI" files in embedded systems. minIni takes little resources,
24
+
can be configured for various kinds of file I/O libraries and provides functionality for reading, writing and
25
25
deleting keys from an INI file.
26
26
27
27
Although the main feature of minIni is that it is small and minimal, it has a few other features:
@@ -34,32 +34,32 @@ Although the main feature of minIni is that it is small and minimal, it has a fe
34
34
* Section and key enumeration are supported.
35
35
* You can optionally set the line termination (for text files) that minIni will use. (This is a compile-time setting, not a run-time setting.)
36
36
* Since writing speed is much lower than reading speed in Flash memory (SD/MMC cards, USB memory sticks), minIni minimizes "file writes" at the expense of double "file reads".
37
-
* The memory footprint is deterministic. There is no dynamic memory allocation.
37
+
* The memory footprint is deterministic. There is no dynamic memory allocation.
38
38
39
39
## INI file reading paradigms
40
40
41
-
There are two approaches to reading settings from an INI file. One way is to call a function, such as
42
-
GetProfileString() for every section and key that you need. This is especially convenient if there is a large
43
-
INI file, but you only need a few settings from that file at any time —especially if the INI file can also
41
+
There are two approaches to reading settings from an INI file. One way is to call a function, such as
42
+
GetProfileString() for every section and key that you need. This is especially convenient if there is a large
43
+
INI file, but you only need a few settings from that file at any time —especially if the INI file can also
44
44
change while your program runs. This is the approach that the Microsoft Windows API uses.
45
45
46
-
The above procedure is quite inefficient, however, when you need to retrieve quite a few settings in a row from
47
-
the INI file —especially if the INI file is not cached in memory (which it isn't, in minIni). A different approach
48
-
to getting settings from an INI file is to call a "parsing" function and let that function call the application
49
-
back with the section and key names plus the associated data. XML parsing libraries often use this approach; see
46
+
The above procedure is quite inefficient, however, when you need to retrieve quite a few settings in a row from
47
+
the INI file —especially if the INI file is not cached in memory (which it isn't, in minIni). A different approach
48
+
to getting settings from an INI file is to call a "parsing" function and let that function call the application
49
+
back with the section and key names plus the associated data. XML parsing libraries often use this approach; see
50
50
for example the Expat library.
51
51
52
-
minIni supports both approaches. For reading a single setting, use functions like ini_gets(). For the callback
52
+
minIni supports both approaches. For reading a single setting, use functions like ini_gets(). For the callback
53
53
approach, implement a callback and call ini_browse(). See the minIni manual for details.
54
54
55
55
56
56
# INI file syntax
57
57
58
-
INI files are best known from Microsoft Windows, but they are also used with applications that run on other
58
+
INI files are best known from Microsoft Windows, but they are also used with applications that run on other
59
59
platforms (although their file extension is sometimes ".cfg" instead of ".ini").
60
60
61
-
INI files have a simple syntax with name/value pairs in a plain text file. The name must be unique (per section)
62
-
and the value must fit on a single line. INI files are commonly separated into sections —in minIni, this is
61
+
INI files have a simple syntax with name/value pairs in a plain text file. The name must be unique (per section)
62
+
and the value must fit on a single line. INI files are commonly separated into sections —in minIni, this is
63
63
optional. A section is a name between square brackets, like "[Network]" in the example below.
64
64
65
65
```
@@ -69,30 +69,30 @@ address=dhcp
69
69
dns = 192.168.1.1
70
70
```
71
71
72
-
In the API and in this documentation, the "name" for a setting is denoted as the key for the setting. The key
73
-
and the value are separated by an equal sign ("="). minIni supports the colon (":") as an alternative to the
72
+
In the API and in this documentation, the "name" for a setting is denoted as the key for the setting. The key
73
+
and the value are separated by an equal sign ("="). minIni supports the colon (":") as an alternative to the
74
74
equal sign for the key/value delimiter.
75
75
76
-
Leading a trailing spaces around values or key names are removed. If you need to include leading and/or trailing
77
-
spaces in a value, put the value between double quotes. The ini_gets() function (from the minIni library, see the
78
-
minIni manual) strips off the double quotes from the returned value. Function ini_puts() adds double quotes if
76
+
Leading a trailing spaces around values or key names are removed. If you need to include leading and/or trailing
77
+
spaces in a value, put the value between double quotes. The ini_gets() function (from the minIni library, see the
78
+
minIni manual) strips off the double quotes from the returned value. Function ini_puts() adds double quotes if
79
79
the value to write contains trailing white space (or special characters).
80
80
81
-
minIni ignores spaces around the "=" or ":" delimiters, but it does not ignore spaces between the brackets in a
82
-
section name. In other words, it is best not to put spaces behind the opening bracket "[" or before the closing
81
+
minIni ignores spaces around the "=" or ":" delimiters, but it does not ignore spaces between the brackets in a
82
+
section name. In other words, it is best not to put spaces behind the opening bracket "[" or before the closing
83
83
bracket "]" of a section name.
84
84
85
-
Comments in the INI must start with a semicolon (";") or a hash character ("#"), and run to the end of the line.
86
-
A comment can be a line of its own, or it may follow a key/value pair (the "#" character and trailing comments
85
+
Comments in the INI must start with a semicolon (";") or a hash character ("#"), and run to the end of the line.
86
+
A comment can be a line of its own, or it may follow a key/value pair (the "#" character and trailing comments
87
87
are extensions of minIni).
88
88
89
-
For more details on the format, please see http://en.wikipedia.org/wiki/INI_file.
89
+
For more details on the format, please see http://en.wikipedia.org/wiki/INI_file.
90
90
91
91
92
92
# Adapting minIni to a file system
93
93
94
-
The minIni library must be configured for a platform with the help of a so- called "glue file". This glue file
95
-
contains macros (and possibly functions) that map file reading and writing functions used by the minIni library
94
+
The minIni library must be configured for a platform with the help of a so- called "glue file". This glue file
95
+
contains macros (and possibly functions) that map file reading and writing functions used by the minIni library
96
96
to those provided by the operating system. The glue file must be called "minGlue.h".
97
97
98
98
To get you started, the minIni distribution comes with the following example glue files:
@@ -101,36 +101,36 @@ To get you started, the minIni distribution comes with the following example glu
101
101
* a glue file for Microchip's "Memory Disk Drive File System Library" (see http://www.microchip.com/),
102
102
* a glue file for the FAT library provided with the CCS PIC compiler (see http://www.ccsinfo.com/)
103
103
* a glue file for the EFS Library (EFSL, http://www.efsl.be/),
104
-
* and a glue file for the FatFs and Petit-FatFs libraries (http://elm-chan.org/fsw/ff/00index_e.html).
104
+
* and a glue file for the FatFs and Petit-FatFs libraries (http://elm-chan.org/fsw/ff/00index_e.html).
105
105
106
-
The minIni library does not rely on the availability of a standard C library, because embedded operating systems
107
-
may have limited support for file I/O. Even on full operating systems, separating the file I/O from the INI format
106
+
The minIni library does not rely on the availability of a standard C library, because embedded operating systems
107
+
may have limited support for file I/O. Even on full operating systems, separating the file I/O from the INI format
108
108
parsing carries advantages, because it allows you to cache the INI file and thereby enhance performance.
109
109
110
-
The glue file must specify the type that identifies a file, whether it is a handle or a pointer. For the standard
110
+
The glue file must specify the type that identifies a file, whether it is a handle or a pointer. For the standard
111
111
C/C++ file I/O library, this would be:
112
112
113
113
```C
114
114
#defineINI_FILETYPE FILE*
115
115
```
116
116
117
-
If you are not using the standard C/C++ file I/O library, chances are that you need a different handle or
118
-
"structure" to identify the storage than the ubiquitous "FILE*" type. For example, the glue file for the FatFs
117
+
If you are not using the standard C/C++ file I/O library, chances are that you need a different handle or
118
+
"structure" to identify the storage than the ubiquitous "FILE*" type. For example, the glue file for the FatFs
119
119
library uses the following declaration:
120
120
121
121
```C
122
122
#defineINI_FILETYPE FIL
123
123
```
124
124
125
-
The minIni functions declare variables of this INI_FILETYPE type and pass these variables to sub-functions
125
+
The minIni functions declare variables of this INI_FILETYPE type and pass these variables to sub-functions
126
126
(including the glue interface functions) by reference.
127
127
128
-
For "write support", another type that must be defined is for variables that hold the "current position" in a
128
+
For "write support", another type that must be defined is for variables that hold the "current position" in a
129
129
file. For the standard C/C++ I/O library, this is "fpos_t".
130
130
131
-
Another item that needs to be configured is the buffer size. The functions in the minIni library allocate this
132
-
buffer on the stack, so the buffer size is directly related to the stack usage. In addition, the buffer size
133
-
determines the maximum line length that is supported in the INI file and the maximum path name length for the
131
+
Another item that needs to be configured is the buffer size. The functions in the minIni library allocate this
132
+
buffer on the stack, so the buffer size is directly related to the stack usage. In addition, the buffer size
133
+
determines the maximum line length that is supported in the INI file and the maximum path name length for the
134
134
temporary file. For example, minGlue.h could contain the definition:
135
135
136
136
```C
@@ -139,9 +139,9 @@ temporary file. For example, minGlue.h could contain the definition:
139
139
140
140
The above macro limits the line length of the INI files supported by minIni to 512 characters.
141
141
142
-
The temporary file is only used when writing to INI files. The minIni routines copy/change the INI file to a
143
-
temporary file and then rename that temporary file to the original file. This approach uses the least amount of
144
-
memory. The path name of the temporary file is the same as the input file, but with the last character set to a
142
+
The temporary file is only used when writing to INI files. The minIni routines copy/change the INI file to a
143
+
temporary file and then rename that temporary file to the original file. This approach uses the least amount of
144
+
memory. The path name of the temporary file is the same as the input file, but with the last character set to a
145
145
tilde ("~").
146
146
147
147
Below is an example of a glue file (this is the one that maps to the C/C++ "stdio" library).
@@ -165,5 +165,5 @@ Below is an example of a glue file (this is the one that maps to the C/C++ "stdi
165
165
166
166
As you can see, a glue file is mostly a set of macros that wraps one function definition around another.
167
167
168
-
The glue file may contain more settings, for support of rational numbers, to explicitly set the line termination
169
-
character(s), or to disable write support (for example). See the manual that comes with the archive for the details.
168
+
The glue file may contain more settings, for support of rational numbers, to explicitly set the line termination
169
+
character(s), or to disable write support (for example). See the manual that comes with the archive for the details.
0 commit comments