_file.readIniFile
(As of 3.1.002.10)
Load an INI file into a JavaScript object
Syntax
_file.readIniFile(filename)
Parameters
filename is the name of the INI file to be read. Note that the usual $X-type of substitution is also applied. The file is required to contain either UTF8 or plain ASCII characters.
Returned Value
The contents of the INI file is converted to a JavaScript structure. null is returned in case of an error, e.g. file not found.
Description
For INI file entries without a [section] (i.e. in the default "" section), these are simple name:value entries in the JavaScript object. Entries within a [section] are stored as section:{array of name:value pairs}. See the Example below.
Example
; sample ini file first="ABCDEF" second="12345" [Section1] third=123 fourth=456
The above can be loaded by:
var oIni = _file.readIniFile("thefilename");
The resulting value of variable oIni will be:
oIni={
"first":"ABCDEF",
"second":"12345",
"Section1":{
"third":"123",
"fourth":"456"
}
}
first = oIni.first; // simple reference to a value
home = oIni["home address"]; // when the keyword contains a non-alphanumeric char.
third = oIni['Section1'].third; // reference to a section
DocOrigin Extended ini Support
Please see _profile (Access Profile Files) for descriptions of DocOrigin's extended support for INI files. These include:
1. Conditional and unconditional includes of other INI files
2. Special character handling within values
3. "heredoc" support
4. Default section continuation using []
5. Auto text substitution using the [Define] section
6. Key names may be any string not just a single word
7. Values can optionally be surrounded by "" or ''.
The readIniFile() function is similar to the _profile.load() function, but more general-purpose, and is recommended unless you are specifically wanting to reset the internal Profile settings. readIniFile will not do any of the automatic actions that may be specified in a true profile file.
readIniFile does not have specific sibling functions for enumerating sections and/or keys within sections. As the returned object is a standard JavaScript object, the usual
for (var x in oIni)... constructs should suffice for enumeration needs. If typeof x is an object then x is a section name.
INI files are often used for language translation tables. In such cases, it is not unusual that the key is a multi-word string. Eg.
Continues on the next page=Fortsättning på nästa sida
You will not be able to reference oIni.Continues on the next page but you can (must) reference oIni["Continues on the next page"]. Since this example is likely from the [Swedish] section you might be referencing oIni.Swedish["Continues on the next page"]. All the usual JavaScript capabilities apply.
