Size: 2740
Comment:
|
Size: 7406
Comment: New version
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
= IniFiles = {{{IniFiles}}} is part of the CategoryAplApl project. <<TableOfContents>> |
|
Line 2: | Line 7: |
INI files are still useful to provide settings to an application. Vista is not going to change this. |
INI files are still useful to provide settings to an application. Neither Vista nor Windows 7 are going to change this. |
Line 6: | Line 11: |
They have a disadvantage as well: they are slow. If you are not interested in the Windows registry and command line parameters, and if you are not changing your INI files while the 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. |
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. |
Line 13: | Line 21: |
=== Character Values === | |
Line 18: | Line 26: |
results in a string holding the path, but an entry like: | results in a string holding the path. === Numeric Values === An entry like: |
Line 22: | Line 33: |
results in a two-element-vector "!FormSize" holding two Integers. | results in a two-element-vector "!FormSize" holding two integers. === References === |
Line 28: | Line 40: |
is treated in a special way: the name between the curlies is treated as the name of an alreday defined value in the same section. It is then replaced by the value of that entry. |
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] ; to be ignored! 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' [PATHES] 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. == Example == === Creating an Instance === |
Line 32: | Line 84: |
{{{MyIni←⎕New #.IniClass 'C:/Appl/Example.ini'}}} you can get all information you are interested in by calling the only method "Get". Given this file "Example.ini": |
{{{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": |
Line 40: | Line 96: |
LogLevels=1 2 3 * from 1 to 9 | LogLevels=1 2 3 ; from 1 to 9 |
Line 48: | Line 104: |
You can get any level of information you are interested in: * list everything * list a particular section * list a particular value in a particular section == Examples == {{{ MyIni.Get ⍬ ⍬ GENERAL MaxNoOfErrors 20 GENERAL FormSize 800 1200 GENERAL LogfileFlag 1 GENERAL LogLevels 1 2 3 DIR Home C:/mainfolder/ DIR AppFolder C:/mainfolder/appls/ DIR DocsFolder C:/mainfolder/docs/ DIR LogFileFolder C:/mainfolder//Logs/ MyIni.Get'General' ⍬ MaxNoOfErrors 20 FormSize 800 1200 LogfileFlag 1 LogLevels 1 2 3 MyIni.Get'General' 'FormSize' |
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' |
Line 74: | Line 130: |
MyIni.Get'General' 'Unknown' ¯1 MyIni.Get'General' 'Unknown' |
¯1 myIni.Get'General' 'Unknown' ⍝ with default |
Line 78: | Line 132: |
¯1 MyIni.Get'Dir' 'LogFileFolder' C:/mainfolder/Logs/ }}} >> [:IniFiles/Script:The Script] Kai Jaeger |
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. == Project Page == For bug reports, future enhancements and a full version history see IniFiles/ProjectPage == Version Information == ||Original author: ||KaiJaeger || ||Responsible: ||KaiJaeger || ||Email: || kai@aplteam.com || ||Current state: ||1.7.3 || == Download == You have two options: you can either download the script for usage: [[http://aplwiki.com/IniFiles?action=AttachFile&do=get&target=IniFiles.ZIP|Download IniFiles script right now]] or get the whole thing from the AplWikiRepository, including the development workspace and the script and maybe more for any development or for running the test cases: {{{ svn list svn://aplteam.com/os/dyalog/IniFiles/tags }}} If you plan to contribute please note that all stuff published as part of the APLAPL project must follow certain [[AplAplStandards|APLAPL-specific standards]]. |
Line 86: | Line 214: |
CategoryDyalog CategoryScripts | CategoryAplApl |
IniFiles
IniFiles is part of the CategoryAplApl 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] ; to be ignored! 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' [PATHES] 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.
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.
Project Page
For bug reports, future enhancements and a full version history see IniFiles/ProjectPage
Version Information
Original author: |
|
Responsible: |
|
Email: |
|
Current state: |
1.7.3 |
Download
You have two options: you can either download the script for usage:
Download IniFiles script right now
or get the whole thing from the AplWikiRepository, including the development workspace and the script and maybe more for any development or for running the test cases:
svn list svn://aplteam.com/os/dyalog/IniFiles/tags
If you plan to contribute please note that all stuff published as part of the APLAPL project must follow certain APLAPL-specific standards.