APL Wiki
IniFiles
IniFiles is part of the CategoryAplTree project.
Overview
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 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:
- They are slow
- They return everything as a string
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.
Note that of course "HomeFolder" 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.
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:
- They can only be used during the instanciation
- They must not be nested
- Although it is possible to specify a numeric value this does not make any sense since numeric values cannot be used as references
Import another INI files
Above the first section definition one can also import another INI file. This can be used to make an INI file path/drive independent, for example in order to support an application on a notebook as well as a server.
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 ArchiveDrive='D:\' DocDrive='M:\'
Note that the section is ignored in the file that will import this INI file. Assuming that the name of this INI file is "local.ini":
!Import local.ini
[PATHS]
ArchivePath='{ArchiveDrive}this\that\'
DocPath='{DocDrive}there\'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, this is suitable for small "local" INI files. With version 2.0.0 the constructor accepted more than one filename: use this to effectively merge INI files together.
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:
- get everything
- get all keys and values of a particular section
- get a particular value from a particular section
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
myIni[⊂'GeneRAL:FormSize']←⊂12 23
The "Put" method
(12 23) myIni.Put 'GeneRAL:FormSize'
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
An INI file is by definition not a kind of database and should not be used as such.
Multiple INI files
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....
- in case of name clashes the last file wins.
you cannot execute the Save method when more than one INI file was specified.
the IniFilename property always returns a simple string. In case of more than one INI file the filenames are separated by ";".
Project Page
For bug reports, future enhancements and a full version history see IniFiles/ProjectPage
Version Information
Original author: |
|
Responsible: |
|
Email: |