IniFiles is part of the CategoryAplTree project.

(Hide table-of-contents)


INI files are still useful to provide settings to an application. Neither Vista nor Windows 7 are going to change this.

The Windows API methods provided to read a particular value have one advantage: they deliver always up-to-date values. Whether that is an important feature or not is another matter.

They have disadvantages as well:

In case 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.

The INI specification

INI files are not well-defined. Different implementation come with all sorts of specialties. For details see:

However, there is some common ground:

Differences between APL-like INI files and classic ones

A warning

An INI file is by definition not a kind of database and should not be used as such. Therefore it is recommended to use the Save method only for two purposes:


Character values

An entry like:


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 (place holders)

If you need to define a number of paths like:


you can simplify this by using the "replacement" syntax:


Naturally "path" must be specified upfront. Prior to version 1.5, this must be specified within the same section. As a result the same variable needed to be specified more than once if the same path needed to be available in more than one section.

Since version 1.5 this restriction was lifted by the introduction of "local" variables, see there.

Note that you can still specify {} as part of the data: just double them like quotes:

      '{{⍵/⍨2=+⌿0=⍵∘.|⍵}⍳⍵}' ←→ '{{{{⍵/⍨2=+⌿0=⍵∘.|⍵}}⍳⍵}}'

Local variables

Local values are those specified above the first section. They have only one purpose: to be used as references in several sections.

There are some restrictions:

Nested entries: special "Add" syntax

Sometimes one needs to specify potentially long lists on a particular keyword, for example a list of IP addresses a server is supposed to ignore: "DenyIP". Specifying them on one single line is very hard to read and prone to error in case of a change.

Instead this can be achieved with a special syntax:


This results in a nested vector of strings. Note that you must initialize the vars as an empty vector in the first place. The =, syntax implies an (enlose) on the data to the right of "=".

This syntax is supported for both, characters and numbers:

vector,=1 2 3
vector,=200 300

leads to:

(1 2 3) (200 300)

Importing another INI file

Above the first section definition one can also import another INI file. This can be used for two different purposes:

This is how an INI file that is going to be imported elsewhere could look like:

; INI file to be imported
[DRIVES]  ; This is a comment

Assuming that the name of this INI file is "local.ini":

!Import local.ini

Using this technique all values that depend on the current environment can be specified in local.ini while all the other entries can be specified in the second INI file.

However, with version 2.0.0 the constructor accepts more than one filename: use this to effectively merge INI files.

Which technique is more appropriate depends on the application. See Merging versus importing for a discussion.

Classic INI files

Since version 2.2 IniFiles is able to process classic INI files. This means that these two values:

digits=1 2 3

are both converted into text.

Note that an INI file must be consistent: it cannot mix classic stuff with new stuff. This INI file:


would therefore cause an error. This means that in order to be identified as classic an INI file must not enclose any of its values in quotes.

This INI file would not work either:


because it also is inconsistent but this one would:


"text1" ends up as an empty text vector.

Note that an INI file that contains any local variables or that contains at least one line that starts with "!Import" before the first section is not considered to be a classic INI file.


Note that there is room for ambiguity; consider this INI file:


Interpreted as a classic INI file this would result in three variables carrying the strings "1", "2" and "3". Interpreted as an APL-style INI file you would get three variables carrying integer values.

In case of ambiguity the INI file is interpreted as an APL-style one.

The "OldStyleFlag"

From version 2.2 on there is a new property OldStyleFlag which is a Boolean that will be 1 only if the processed INI file is a classic one.

Converting Classic INI files

An INI file can be converted into an APL-like INI file by instantiating it and then issuing the Save command. Note that all values will be surrounded by quotes by then even if a value "Number" carries "123" as value. If you want to take advantage of the numeric data type you have to make changes to the INI file. Of course this means that you also have to change your code.

Check whether an INI file has changed

When instantiated a read-only property EstablishedAt is set. This is used by the method HasInifileChanged which returns a 1 in case the INI file had been changed since it was instantiated, otherwise 0.


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.

(Note that any instance of the IniFiles class can be converted to an ordinary namespace - see the Convert method)

Given this file "Example.ini":

FormSize=800 1200
LogLevels=1 2 3 ; from 1 to 9


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

Examples with "Get"

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


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):

20  800 1200  1  1 2 3
800 1200


The "Put" method

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

You can use the Save method to convert an old-fashioned INI file because every value will be saved within quotes. There is an important restriction however: The Save method cannot be invoked when more than one file was evaluated. See Multiple INI files (Merging) for details.

The "GetSections" method

With version 2.8.0 a method GetSections was introduced. It returns all sections names in uppercase letters:


The "Convert" method

Any instance of the IniFiles class can be converted into an ordinary namespace. The myIni instance created earlier on for example can be converted in two ways:

Use namespace rather than instance

The Convert method can be used to convert an instance into an ordinary namespace. It takes a reference to a namespace as the right argument:

      Ini←myIni.Convert ⎕NS''
      Ini.List ⍬
 DIR      AppFolder      C:/mainfolder/appls/ 
 DIR      DocsFolder      C:/mainfolder/docs/ 
 DIR      Home                 C:/mainfolder/ 
 DIR      LogFileFolder   C:/mainfolder/Logs/ 
 GENERAL  FormSize                   800 1200 
 GENERAL  LogLevels                     1 2 3 
 GENERAL  LogfileFlag                       1 
 GENERAL  MaxNoOfErrors                    20 

You can ask Convert to convert the instance into a flat namespace, effectively ignoring the sections:

      Ini←'flat' myIni.Convert ⎕NS''
      Ini.List ⍬
      Ini.List ⍬
 AppFolder      C:/mainfolder/appls/    
 DocsFolder      C:/mainfolder/docs/    
 FormSize                   800 1200    
 Home                 C:/mainfolder/    
 LogFileFolder   C:/mainfolder/Logs/    
 LogLevels                     1 2 3    
 LogfileFlag                       1    
 MaxNoOfErrors                    20 

Multiple INI files (Merging)

Note that since version 2.0.0 one can specify more than one filename in the ⎕NEW statement. This effectively merges the INI files together. Note that....

  1. in case of name clashes the last file wins.
  2. you cannot execute the Save method when more than one INI file was specified.

  3. the IniFilename property always returns a simple string. In case of more than one INI file the filenames are separated by ";".

Note that placeholders are replaced only after all INI files specified have been processed. Imagine this general INI file Foo.INI:



and a machine-specific INI file Foo_MyMachine.INI:


When only the first INI file is processed and the result of ⎕NEW is assigned to MyIni then you get this:


When you process both INI file, first Foo.INI and then Foo_MyMachine.INI then you get this:


That way you can specify important defaults at a client's side in the main INI file. When running the same application on your laptop you can add a file that carries the necessary differences.

There is a shared method GetIniFiles available that supports this:

The GetIniFiles method

If a directory "foo\" contains just a file "my.ini" then:

      #.IniFiles.GetIniFiles 'foo\my'
      #.IniFiles.GetIniFiles 'foo\my.ini'

If there are four files: "my.ini", "my2.ini", "my_kai.ini" and "my_peter.ini" then on a computer with the name "kai":

   #.IniFiles.GetIniFiles 'foo\my'

but on a computer with the name "peter":

      #.IniFiles.GetIniFiles 'foo\my'

Merging versus importing

Merging two or more INI files shares many features with importing them. Let's discuss the differences.

Local specialities

Imagine that at your clients site you run a certain application from a certain folder on a certain server. You specify a "Home" value in your master INI file called "Master.INI" to reflect this:


You might want to run and develop that application on your laptop as well. On your laptop it's located in a folder "Foo" on your local D:\ drive. Let's assume that you laptop has the name "myLaptop".

By creating a second INI file called "Master_myLaptop.INI" with this contents:


you can solve the problem. Since version 2.6 there is a method GetIniFiles available to deal with this - see above.

Multiple locations

I found myself once in a situation where I had to keep the same INI file on different computers on the network. Of course this is dangerous because to keep them in sync is important but will at one stage or another almost certainly fail. !Import to the rescue: you keep just one master file while all the other INI files contain just one line pointing to that master file:

!Import  \\servername\INIs\master.ini

Editing INI files

Note that there is a tailored INI-file editor available as part of the APLTree project. See EditIni for details.

The EditIni project has been retired.

IniFiles (last edited 2018-02-18 08:31:06 by KaiJaeger)