LS_CDRun

Ini file format

Introduction

This document specifies a text-based file format for representing software configuration data in a format which is easily editable by humans and unambiguously readable by a simple automatic parser.

The format described here is an implementation of the ".INI File Format", as defined in the Microsoft Windows for Workgroups Resource Kit.

Character Set

The entire INI file, including section names, key names and data values is encoded using 8-bit characters in the ISO 8859-1 character set (of which 7-bit ASCII is a subset). Application-specific string values may store data using other character sets, and even binary data, as long as they are encoded as either ASCII or ISO 8859-1 text. ANSI C Escape sequences are used for the encoding of special characters in strings.

File Names

If the INI file is to be stored or used on a Microsoft Windows system, the following characters should not be used in the file name, as they are not supported by older filing systems: "\", "/", ":", "*", "?", """ (double quote character), "" and "|".

Additionally, certain file names are supported at the filing system level, and can be accessed by programs, but they are not accessible from certain shells and file manipulation programs. These names include: "COMx", "AUX", "LPTx", "PRN", "NUL" and "CON", and all variants with a "dot suffix". File names entirely consisting of dots (".", "..", etc.) are also "problem files".

Where compatibility with older filing systems is important, short names ("8+3") should be used for directory and file names.

File Structure

An INI file is an 8-bit text file divided into sections, each containing zero or more keys. Each key contains zero or more values.

Example:

[SectionName]

keyname= value

;comment

keyname=value, value, value ;comment

Section names are enclosed in square brackets, and must begin at the beginning of a line.

Section and key names are case-insensitive. In consideration of possible future upgrades from INI to XML, authors of INI files may want to use consistent and case-exact section and key names, as if INI parsers were case-sensitive (XML parsers are case-sensitive).

Section and key names cannot contain spacing characters. The key name is followed by an equal sign ("=", decimal code 61), optionally surrounded by spacing characters, which are ignored.

If the same section appears more than once in the same file, or if the same key appears more than once in the same section, then the last occurrence prevails.

Multiple values for a key are separated by a comma followed by at least one spacing character.

When a parser encounters an unrecognized section name, the entire section (with all its keys) should be skipped. Within a known section, only unrecognized keys should be skipped.

Spacing, Line Terminators and Comments

Both Space (decimal code 32) and Horizontal Tab (HT, decimal code 9) are acceptable spacing characters.

Lines are terminated by a CR (decimal code 13) or LF (decimal code 10) character. If CR+LF or LF+CR appear consecutively, they count as a single line terminator, generating one line, not two lines. A sequence consisting of CR+LF+CR+LF would however result in two lines, not one line. Where implementation-specific considerations do not advise otherwise, the recommended line terminator is a LF character.

Comments are introduced by a semicolon character (";", decimal code 59). Comments must begin at the beginning of a line or after a spacing character. Comments terminate at the end of the line.

String Values

String values may optionally be enclosed in quote characters (""", decimal code 34). String values beginning or ending with spaces, or containing commas or semicolons, must be enclosed in quotes. Quote and backslash ("\", decimal code 92) characters, as well as binary characters (decimal ranges 0..31, 127..159) appearing inside strings must be encoded using the escape sequences described in this document.

The default character set for text appearing inside string values is ISO 8859-1. Applications may define certain sections and/or keys to store text which, from the application side, results as being encoded using different character sets, or even binary data. However, the string data appearing in the INI file must be encoded as ISO 8859-1 text, using escape sequences as necessary, so as to be compatible with INI parsers.

Path Values

Path values are identical to String values, with the exception that escape sequences introduced by the backslash character are not supported. Path values are used to represent filing system and registry paths, where for clarity it is not desirable to use double backslash characters ("\\") to indicate backslash characters inside paths. This means that a path like "C:\readme.txt" would remain unchanged (whereas it would have to be indicated as "C:\\readme.txt" in a String field).

Numerical Values

In numerical values, the period (".", decimal code 46) is the only valid decimal separator. Leading zeros are optional (e.g. "0.5", "000.5" and ".5" are all valid representations for the same value, i.e. 0.5). For consistency, one leading zero (e.g. "0.5") is the preferred format to represent values smaller than 1.

Trailing zeroes may be used on an application-dependent basis, for example to express precision (e.g. "0.50", opposed to "0.5", may indicate that the smallest currency unit is equal to fifty "cents", as opposed to five "tenths" of the full unit, and "1.234000" may indicate to use a precision of six decimal digits in partial or total results).