Overview

TableOfContents

INI files are still useful to provide settings to an application. Vista is not going to change this.

The Windows API methods provided to read a particular value have an advantage: they follow a clearly defined search path, and following that path they take not only the INI file into account, they also check the Windows registry and the command line parameter. Furthermore, they deliver always up-to-date values.

They have disadvantages as well:

If you are not interested in the Windows registry and command line parameters, and if nobody else is changing your INI files while your application is running, then the "IniFile" class introduced in this article might attract your attention.

This class allows you to use a kind of APL-Syntax in your INI files. Values not enclosed in quotes will be converted to numbers, everything else gets a string.

Details

Character Values

An entry like:

HomeFolder='C:/Windows/Appl/'

results in a string holding the path.

Numeric Values

An entry like:

FormSize=300 400

results in a two-element-vector "FormSize" holding two integers.

References

Furthermore, an entry like:

LogFolder='{"HomeFolder}Logsfiles/'

is treated in a special way: the name between the curlies is taken as the name of an already defined value. It is then replaced by the value of that entry.

Example

Creating an Instance

After creating an instance from the class:

myIni←⎕New #.IniClass (,⊂'C:/Appl/Example.ini')

Accessing Data with the "Get" method

you can get all information you are interested in by calling the method "Get". Note that names are not case sensitive.

Given this file "Example.ini": 

[GENERAL]
MaxNoOfErrors=20
FormSize=800 1200
LogfileFlag=1
LogLevels=1 2 3 ; from 1 to 9

[DIR]
Home='C:/mainfolder/'
AppFolder='{Home}appls/'
DocsFolder='{Home}docs/'
LogFileFolder='{Home}Logs/'

You can get any level of information you are interested in:

Examples with "Get"

      myIni.Get ⍬ ⍬ 
 GENERAL                                      
          MAXNOOFERRORS                    20 
          FORMSIZE                   800 1200 
          LOGFILEFLAG                       1 
          LOGLEVELS                     1 2 3 
 DIR                                          
          HOME                 C:/mainfolder/ 
          APPFOLDER      C:/mainfolder/appls/ 
          DOCSFOLDER      C:/mainfolder/docs/ 
          LOGFILEFOLDER   C:/mainfolder/Logs/ 
      myIni.Get'General' ⍬
MAXNOOFERRORS        20 
FORMSIZE       800 1200 
LOGFILEFLAG           1 
LOGLEVELS         1 2 3 
      myIni.Get'General' 'FormSize'
800 1200
      ¯1 myIni.Get'General' 'Unknown' ⍝ with default
¯1
      myIni.Get'General' 'Unknown' ⍝ without default
Value Error: "Unknown"
myDoc.Get'General' 'Unknown'

Indexing

Since version 1.1, the class provides a default property. That means you can access values by indexing.

Examples (with the same INI file listed above): 

      myIni[⊂'GeneRAL:']
20  800 1200  1  1 2 3
            ⊃myIni[⊂'GeneRAL:FormSize']
800 1200

Assigning

The "Put" method

Nested Entries

Since version 1.4 nested values are supported. Imagine an INI file that sets an "AcceptIP" value to a number of IP addresses to be accepted when a client tries to connect to your application. That's how that might look like: 

AcceptID='192.168.68.1,192.168.68.100,195.64.2.2,127.0.0.1,85.86.87.88,156.147.123.1'

and maybe even much longer. Horrible, and prone to error when that needs to be changed. By initializing the value as an empty vector and then using the ",=" syntax one can overcome the problem: 

AcceptID=''
AcceptID,='192.168.68.1'
AcceptID,='192.168.68.100'
AcceptID,='195.64.2.2'
AcceptID,='127.0.0.1'
AcceptID,='85.86.87.88'
AcceptID,='156.147.123.1'

This results in a nexted vector of length 6 were each item holds a single IP addres. This works with numbers as well: 

vector=''
vector,=1 2 3
vector,=200 300

leads to: 

(1 2 3) (200 300)

The "Save" method

You can also change a particular value but the changed value will persist only if you execute the "Save" method at some point: 

      myIni[⊂'GeneRAL:FormSize']←⊂'¯1 1000
      myIni.Save

A Warning

However, an INI file is by definition not a kind of database and should not be used to save data by the application itself. However, the "Save" method might be useful to initialise an INI file.

Check Keys before indexing

Note that when indexing is used there is no default. That means that specifying an unknown value leads to an error. There are two ways to escape this problem: 

      myIni.Exist 'General:Unknown'
0
      myIni.Default← ¯1 ¯1
      myIni[⊂'General:Unknown']
¯1 ¯1
      myIni[⊂'General:Unknown']←200
      myIni[⊂'General:Unknown']
200

Creating an INI file

To create a new INI file, don't specify a filename:

myIni←⎕New #.IniClass 

Adding a Section

The only way to add a new section is to use the AddSection-method: 

      myIni←⎕New #.IniClass
      myIni.AddSection'NewSection'

Adding Values

Adding new values can be done the same way you would cange a value: either use the "Put"-method or simply assign a value.

Other Methods

Delete

Examples with supported syntax: 

      myIni←⎕New #.IniClass
      myIni.Delete 'MySection:key1'
      myIni.Delete 'MySection' 'key2'
      myIni.Delete 'MySection:' ⍝ this will delete the entire section

The "Delete" method returns a shy boolean which gets 1 in case something was to be deleted.

Exist

Let's assume that "myIni" is an instance of the IniFile class, and that there is a section "Config" which contains exactly one key: "Size":

DeleteDefault

Setting the "Default" property might be appropriate if you need a default value for undefined keys. However, as soon as the "Default" property is set, one can get rid of it only be calling the "DeleteDefault" method. The method returns a shy Boolean which gets 1 only if there was a default.

History

For a full version history: [:IniFiles/History: History]

Version Information

Original author:

KaiJaeger

Responsible:

KaiJaeger

Email:

kai@aplteam.com

Current state:

1.4.2

Download

Goto the [:IniFiles/DownloadPage: DownloadPage]

CategoryOpenSourceApl CategoryAplAplDyalog