Conventional INI File Parsing and Writing
Ah yes, INI files. We love them. We hate them. We cannot escape them. Originally made popular by Windows, INI files are everywhere including in Samba and Trac. This gem has one goal: make INI file, structure, and stream manipulation as fast, safe, and simple as possible. We take a modal approach with a pluggable parser class.
; some comment about section1 [section1] var1 = foo var2 = doodle [section2] ; some comment about var1 var1 = baz ; some comment about var2 var2 = shoodle
There is no formal INI specification but most parsers observe the following so we do also by default:
Section declarations are wrapped in square brackets (
[section1]) with no spaces surrounding the section name. Duplicate sections are discouraged but if included are merged.
var1 = foo above is an example of a parameter, also frequently referred to a property, item, or pair. Each parameter is made up of a key name (
var1), an equals sign (
=), and a value (
foo) with optional spaces. Leading spaces before the key name are allowed and leading spaces before or after the value are trimmed. Values are literally the characters that remain, even if quoted (
var1 = "foo" would include the quotes in the value). Duplicate parameters, either in the same section or merged duplicate sections, play 'last one wins'.
All lines starting with a semicolon (
;) are assumed to be comments and are ignored. This character must be the first on the line.
All lines that contain nothing but spaces are ignored.
Lines end at either a CRLF or just a LF (CR=015, LF=012). Files may mix the two within the same file to accomodate edits from different platforms.
Format Variations Supported
Because INI format is not formally specified, many variations exist in the wild. Some of these are supported by extra parsers that are included and set by changing the
mode of the <ini> instance.
To maintain backward compatibility with the original 'inifile' gem, the following variations are supported by the default parser:
Comments: the comment character can be specified when an instance is created
Parameters: separator character can be specified when an instance is created
Duplicate Sections: merged
Duplicate Parameters: the last one wins
Currently Unsupported Format Variations
If it isn't listed above, chances are it isn't supported. But here are some specific variations in case you are wondering (and, yes, we do have plans eventually support them, either as defaults or options):
Parameter value continuation with backslash (
Parameter value double-quoting with escapes (
foo = "value with \n in it")
Parameter values using braces (
Parameter values using simple commas parsing into arrays
Copyright and License
Copyright © 2006-2007 The 'ini' and 'inifile' Gem Team
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.