102 lines
4.1 KiB
Markdown
102 lines
4.1 KiB
Markdown
# IniFile
|
|
|
|
IniFile is an Arduino library for reading ini files. The format is
|
|
similar to that seen in Microsoft `.ini` files but the implementation
|
|
is completely independent. IniFile is designed to use minimal memory
|
|
requirements, and the only buffer used is one supplied by the user,
|
|
thus the user remains in charge of memory usage.
|
|
|
|
The ini file is separated into sections, where the section names are
|
|
written inside square brackets. If you don't wish to use sections then
|
|
pass a `NULL` pointer for the section name. Under each section are a
|
|
set of key-value pairs, separated by an equals sign (`=`). Spaces
|
|
around keys and values are ignored, but extra spaces inside the key
|
|
are significant. Whitespace inside the value string is preserved; if
|
|
leading or trailing whitespace is important you must quote the value
|
|
string inside the ini file, and you must strip out the quotes
|
|
yourself. If multiple entries for the same key exist inside the
|
|
selected section (if using) then only the first value is returned. If
|
|
a section is defined more than once only the first is used. The .ini
|
|
file can contain comments, which begin with a semicolon (`;`) or hash
|
|
(`#`). The user-supplied buffer must be large enough to accomodate the
|
|
longest line in the file.
|
|
|
|
## Example file format
|
|
|
|
; Semi-colon comment
|
|
[network]
|
|
mac = 01:23:45:67:89:AB
|
|
|
|
# hash comment, leading spaces below
|
|
gateway = 192.168.1.1
|
|
|
|
# extraneous spaces before and after key and value
|
|
ip = 192.168.1.2
|
|
|
|
hosts allow = example.com
|
|
|
|
# A similarly-named section
|
|
[network2]
|
|
mac = ee:ee:ee:ee:ee:ee
|
|
subnet mask=255.255.255.0
|
|
|
|
; Extra whitespace around the key and value is permitted
|
|
; (and ignored)
|
|
hosts allow = sloppy.example.com
|
|
|
|
[misc]
|
|
|
|
string = 123456789012345678901234567890123456789001234567890
|
|
string2 = a string with spaces in it
|
|
|
|
; This section is a repeat of en existing section and will be ignored.
|
|
[network]
|
|
mac = 01:23:45:67:89:ab
|
|
ip = 192.168.1.2
|
|
gateway = 192.168.1.1
|
|
|
|
|
|
## Write support
|
|
|
|
Write support is a feature that has been requested on several
|
|
occasions but as I am no longer using the IniFile library I will not
|
|
add this feature. For anyone planning to add such support the
|
|
information below may be useful.
|
|
|
|
One goal of the `IniFile` implementation was to limit the amount of
|
|
memory required. For use in embedded systems `malloc` and `new` are
|
|
deliberately not used. Another goal was that tasks which take a longer
|
|
duration were broken down into smaller chunks of work, eg
|
|
`IniFile::getValue(const char* section, const char* key, char* buffer,
|
|
int len, IniFileState &state)`. This was because I wanted my `WwwServer`
|
|
library, which uses `IniFile`, to avoid interfering with time-critical
|
|
code.
|
|
|
|
I don't think that write support can meet the time-critical goal but
|
|
that doesn't prevent its inclusion. I think the way I would choose to
|
|
implement write support is to use `IniFile::findKey()` to find where the
|
|
desired key is located in the file. I'd then copy everything up to
|
|
that point to a temporary file, insert a line for the value and new
|
|
key, skip the current line in the existing file (using
|
|
`IniFile::readline()`) and then write out the reminder of the existing
|
|
file into the temporary file. I'd like to move or rename the temporary
|
|
file over the existing file but the Arduino SD library doesn't provide
|
|
this functionality; I'd probably just copy the temporary file over the
|
|
old one and then delete the temporary one.
|
|
|
|
The code has been written under a standard Linux environment, using a
|
|
compatibility header file to mimic the SD library. This was far more
|
|
convenient than doing everything on the Arduino and enabled me to use
|
|
`gdb` to debug the code and core dumps. You'll find `arduino_compat.h`
|
|
inside the test directory, along with a `Makefile` which can be used for
|
|
regression testing. Any proposed changes must pass the regression
|
|
tests.
|
|
|
|
## Contributors
|
|
|
|
* [Steve Marple](https://github.com/stevemarple)
|
|
* [per1234](https://github.com/per1234)
|
|
* [OscarVanL](https://github.com/OscarVanL)
|
|
* [MikuX2](https://github.com/toybox01)
|
|
* [kaixxx](https://github.com/kaixxx)
|