Introduction
Jealous that someone (Todd Davis) thought of it first, I was recently inspired to do some hacking of my own and put together my own .NET 2.0 INIFile class. Like Todd's, mine reads the file directly rather than relying on the Windows kernel to do it.
The INIFile class parses a .ini file into Section and Key classes upon setting its Contents property. Getting the property reconstructs the .ini file from the said Section and Key classes. The result is a parser that automatically reformats the .ini file for you (as a side effect, really).
The INIFile object maintains a List (Of Section) collection (aptly titled Sections), and each Section has a Keys collection (List (Of Key)).
Files are not directly edited except when loading and saving. In other words, the .ini file is edited entirely in memory.
In addition to using collections to edit the information, I also went about adding some higher level methods to the INIFile class. These operate on the INIFile.Sections and Section.Keys collections internally, but don't require a Section class or a Key class as a parameter, opting instead for the more traditional strings.
All of the high level editing functions also have a Shared counterpart that takes a filename parameter. This instantiates the INIFile class, loads the file, performs the operation, saves the file, and returns. For quick edits, this is fine. But for data intensive operations (i.e., thousands of sections or keys), it is recommended that the Shared editing functions (as well as the other high level editing functions, in general) not be used. For those kinds of things, it's always faster to use the Sections and Keys collections.
In addition to editing sections and keys, comments can be edited, and keys can be added to the top of the file outside of any section. A comment is any line that begins with a comment character (usually either a ; or a #). Creating a comment is as simple as creating a new key with only one parameter. Internally, a comment is simply a Key object with IsComment set to True and Value set to the text of the comment (without the comment character). The Name field is ignored for comments, and is not output through the Contents property.
If the *first Section in the Sections collection has its Name field set to Nothing, it indicates the top of the file, and contains the key and comments shown there.
The entire source code for the INIFile class has XML documentation, and should be ready for NDoc (whenever they get .NET 2.0 support working).
*See Known Issues.
Non-INI File Usage
The way INIFile is written gives developers a bit more of a choice in handling .ini files than the built in Windows functions do. Typically, .ini files are for storing settings and other initialization data, hence the name initialization file. They have a pretty standard format.
;generic comment
[section]
key=value
key=value
;commented key=value
The INIFile class has a few properties that allow the developer to change the parsing characters:
| Property Name | Default Value |
|---|
SectionOpenChar | [ |
SectionCloseChar | ] |
NameValueDelimChar | = |
CommentChar | ; |
Because the INIFile.Contents property parses directly, the INIFile class does not require a file actually be loaded or saved. This allows the data to be used in other ways. For example, you now have a formatter (other than XML) that uses a very simple syntax that can be easily sent over a network connection.
Demo App
Included in the Zip file is a demo application that illustrates most of the capabilities of the INIFile class. It can load and save .ini files as well as create them from scratch. It can view, add, and remove sections. It can view, edit, and remove comments. It can also view, add, edit, and remove keys.
The upper box is the value of the Contents property. The lower box lets you enter (or paste) a .ini file. The Parse button sets the INIFile.Contents property to contain the contents of the lower textbox, then outputs it again to the upper text box. It also sets the contents of the list boxes on the other tab page.
Editing the contents of either the sections or keys list boxes updates the contents of the INIFile class immediately.
This program demonstrates the use of collections. It does not demonstrate the higher level editing functions or the shared editing functions.
Known Issues
INIFile Class
If any Section in the Sections collection other than the first one has its name set to Nothing, the value of the Content property will omit the section header for that section. When re-parsing the output, the keys will be merged with the previous section. If you need a section with a blank title that is still output (usually as []), set the Name property to an empty string (i.e., String.Empty).
In some cases, INIFile.FindKey (and several other methods that rely on this method) throws a KeyNotFoundException even when the key exists. This is because only the first matching section is searched for the key. If it's not found in the first matching section, the call fails even if there are more than one matching sections. Instead, consider using the Sections and Keys collections. Also consider not using duplicate sections.
The Name field of a Key whose IsComment property is set to True (a comment key) is not output through the INIFile.Contents property. This will result in the value being lost when the .ini file is later read back from a file or some other source.
Demo App
INI Contents tab
No known issues.
Sections/Keys tab
Currently, the demo app cannot create a section for the top of the file (section for keys and comments outside of a section). It can, however, delete them and edit the keys and comments. The demo app cannot convert between a comment and a key. The demo app cannot rename an existing section without losing the keys it stores. These issues are limitations of the demo app, not the INIFile class. They can be fixed by manual editing under the INI Contents tab.
General
The caption bar of the application reads "Form1" rather than a more creative name such as "INIFile Class Demonstration". This particular problem stems from the fact that I am lazy and have (as of current writing) neglected to change it.
Licensing
The INIFile class and its demo app are both protected under the Creative Commons Attribution-ShareAlike 2.5 license. The full license text is available here. A non-legalese version is also available, here.
