Skip to content

Latest commit

 

History

History
101 lines (81 loc) · 4.12 KB

README.md

File metadata and controls

101 lines (81 loc) · 4.12 KB
Raw

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