Difference between revisions of "Using INI Files"

From Free Pascal wiki
Jump to navigationJump to search
(INI Files..)
 
m (Fixed syntax highlighting; deleted category included in page template)
(30 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 +
{{INI Files}}
 +
 +
=INI Files=
 +
 +
==Basic Information==
 +
 +
INI files are text files that store key/value pairs that are grouped in sections.
 +
 +
INI files can be used to save user settings easily. With the [http://www.freepascal.org/docs-html/fcl/inifiles/index.html IniFiles unit] and the [http://www.freepascal.org/docs-html/fcl/inifiles/tinifile.html TINIFile class] you can easily work with them. The IniFiles unit is part of the FCL.
 +
 +
Currently only INI files compliant with the more restrictive Windows ini-file format are supported. I.e. using [http://en.wikipedia.org/wiki/INI_file#Sections sections] is mandatory and only the semicolon can be used for comments.
 +
For more general information about ini-files read [http://en.wikipedia.org/wiki/INI_file this].
 +
 
==INI Files==
 
==INI Files==
  
===Over View===
+
INI Files use brackets to create and mark '''Sections''', which contain '''keys''' and key '''values'''.
INI files can be used to save basic user settings easily. With the INIfiles unit and the TINIFile class you can easily work with existing INI files... I will show you the basics of the TINIFile class.
+
A Key and its corresponding Value are separated with an equals sign (Key=Value).
  
===INI Files?===
+
Section names are put inside square brackets ([Section]).
INI Files work with sections,keys and values. Example:
 
[Section]
 
Key=Value
 
  
Just like that...
+
Comments are permitted and are marked with a semicolon (;) at the beginning of a line.
It is posible to have multiple keys and sections..
 
  
====Why?====
+
An example ini file:
INI files make it incredibly easy to read and work with data.
 
Similar to XML files.. I think programmers should be well rounded with one or the other.. Or both.
 
  
===Example===
+
<syntaxhighlight lang="ini">
 +
; Comment. Beginning of INI file
  
So first things first.. Lets do a basic console application.
+
; empty lines are ignored
<Delphi>
 
Progam INIex;
 
  
{$mode objfpc}
+
[General]
 +
; This starts a General section
 +
Compiler=FreePascal
 +
; Key Compiler and value FreePascal
 +
</syntaxhighlight>
  
Uses
+
==Ini file reading example==
SysUtils,INIFiles;{INIFiles = The unit with the INI Classes}
 
  
Var
+
The console application below shows how to read ini files. To test it, create an ini file with the name "DB.ini" and the contents below, and save it in the same folder as the executable program.
IniF:TINIFile;//The class
 
</Delphi>
 
  
Something you have to know is that when using the TINIfile class you have to work with an existing INI file.. So open Note pad and create an INI file.. Lets use this as an example:
+
<syntaxhighlight lang="ini">
 +
[DB-INFO]
 +
Author=Adam
 +
Pass=secret
 +
MaxAttempts=5
 +
DBFile=C:\Money.dat
 +
</syntaxhighlight>
 +
 +
The code to read this ini file:
  
[S1]
+
<syntaxhighlight lang=pascal>
 +
Program IniReadExample;
  
Key1=Hello World
+
{$mode objfpc}{$H+}
  
[S2]
+
uses
 +
  classes, sysutils, IniFiles;
  
Key2=Worldly Hello
+
const
 +
  C_DB_SECTION = 'DB-INFO';
  
Ok.. Now back to our code
+
var
<Delphi>
+
  INI: TINIFile;
 +
  Author, Pass, DBFile: String;
 +
  MaxAttempts: integer;
 +
  PassEnter: String;
 +
  TryCount: integer;
 
begin
 
begin
   Writeln('Creating class');
+
   // Create the object, specifying the the ini file that contains the settings
   IF(FileExists('someini.ini'))then
+
  INI := TINIFile.Create('DB.ini');
  begin
+
 
    Inif := TINIFile.Create('someini.ini');
+
   // Put reading the INI file inside a try/finally block to prevent memory leaks
     Writeln(INiF.ReadString('s1','Key1','');
+
  try
  End else Writeln('File not found...');
+
    // Demonstrates reading values from the INI file.
   Readln;
+
    Author      := INI.ReadString(C_DB_SECTION,'Author','');
 +
    Pass        := INI.ReadString(C_DB_SECTION,'Pass','');
 +
    DBFile      := INI.ReadString(C_DB_SECTION,'DBFile','');
 +
    MaxAttempts := INI.ReadInteger(C_DB_SECTION,'MaxAttempts',1);
 +
 
 +
    // Do something with the values read; e.g. verify the password
 +
    if Pass <> '' then
 +
    begin
 +
      // Ask for the password, max attempts = MaxAttempts
 +
      TryCount := MaxAttempts;
 +
      repeat
 +
        write('Please enter password; ', TryCount, ' attempt(s) left: ');
 +
        readln(PassEnter);
 +
        dec(TryCount);
 +
        if (PassEnter <> Pass) and (TryCount > 0) then
 +
          writeln('Wrong Password, please try again');
 +
      until(PassEnter = Pass) or (TryCount = 0);
 +
 
 +
      // Correct password given?
 +
      if PassEnter = Pass then
 +
        writeln('Correct Password.')
 +
      else
 +
        writeln('Invalid password, but maxiumm number of password attempts reached.');
 +
     end;
 +
 
 +
    writeln('Author              : ', Author);
 +
    writeln('File                : ', DBFile);
 +
    writeln('Password            : ', Pass);
 +
    writeln('Max password attempts: ', MaxAttempts);
 +
    writeln;
 +
    write('Press Enter to close...');
 +
    Readln;
 +
 
 +
  finally
 +
    // After the ini file was used it must be freed to prevent memory leaks.
 +
    INI.Free;
 +
   end;
 
end.
 
end.
</Delphi>
+
</syntaxhighlight>
 +
 
 +
==Objects to know==
 +
 
 +
In the TINIFile class there are many different properties, procedures and functions that can be used.
 +
 
 +
'''CaseSensitive''' - This property allows you to say if the keys and sections are case sensitive or not. By default they aren't.
 +
 
 +
'''ReadString''' - Has 3 constant statements. The first one is the section to search in. The second one is the key to look for. The third one is a default string in case the key and/or section searched for is not found.
  
===Objects to know===
+
'''WriteString''' - has three constant statements, too. The first is the section. The second is the key and the last is the value that you want to write. If the key and section exist already, the key will be overwritten with the new value..
In the TINIFile class there are many different Propertys,procedures and functions to be used.
 
  
'''CaseSensitive''' - This property allows you to say if the keys and sections are case sensitive or not.. by default they aren't..
+
'''ReadSections''' - Will allow you to to take the sections from the INI file and put them in a TStrings class (or TStringList with the AS operator).
  
'''ReadString''' - Has 3 constant statements. the first one is the section to search in. The second one is the key to look for. The third one is a default string incase the key and\or section searched for is not found.
+
'''DeleteKey''' - Remove an existing key from a specific section.
  
'''WriteString''' has three constant statements too... The first is the section. The third is the key and the last is the Value. If the key and section exist already the Key will be over written with the new value..
+
'''EraseSection''' - Remove a section and all its data.
  
'''ReadSections''' - Will allow you to to take the sections from the INI file and put them in a TStrings class(Or TStringList with the AS code)
+
There are more procedures and functions but this is enough to get you started.
  
'''DeleteKey''' - Remove an existing Key from a specific section
+
===Reference Documentation===
  
'''EraseSection''' Remove a section and all its data
+
Here: [http://lazarus-ccr.sourceforge.net/docs/fcl/inifiles/index.html Free Pascal documentation on INI files]
  
There are more procedures and functions but this is basic..
+
= See also =
  
===Last words...===
+
* [[HistoryFiles]]
Here: [http://lazarus-ccr.sourceforge.net/docs/fcl/inifiles/index.html] you can learn all about INI Files to..
+
* [[XML Tutorial]]
Please, if you can put up more information about INI files in Pascal.
 
'''Modify At Will'''
 

Revision as of 09:04, 4 March 2020

العربية (ar) Deutsch (de) English (en) español (es) suomi (fi) français (fr) polski (pl) русский (ru) 中文(中国大陆)‎ (zh_CN)

INI Files

Basic Information

INI files are text files that store key/value pairs that are grouped in sections.

INI files can be used to save user settings easily. With the IniFiles unit and the TINIFile class you can easily work with them. The IniFiles unit is part of the FCL.

Currently only INI files compliant with the more restrictive Windows ini-file format are supported. I.e. using sections is mandatory and only the semicolon can be used for comments. For more general information about ini-files read this.

INI Files

INI Files use brackets to create and mark Sections, which contain keys and key values. A Key and its corresponding Value are separated with an equals sign (Key=Value).

Section names are put inside square brackets ([Section]).

Comments are permitted and are marked with a semicolon (;) at the beginning of a line.

An example ini file:

; Comment. Beginning of INI file

; empty lines are ignored

[General]
; This starts a General section
Compiler=FreePascal
; Key Compiler and value FreePascal

Ini file reading example

The console application below shows how to read ini files. To test it, create an ini file with the name "DB.ini" and the contents below, and save it in the same folder as the executable program.

[DB-INFO]
Author=Adam
Pass=secret
MaxAttempts=5
DBFile=C:\Money.dat

The code to read this ini file:

Program IniReadExample;

{$mode objfpc}{$H+}

uses
  classes, sysutils, IniFiles;

const
  C_DB_SECTION = 'DB-INFO';

var
  INI: TINIFile;
  Author, Pass, DBFile: String;
  MaxAttempts: integer;
  PassEnter: String;
  TryCount: integer;
begin
  // Create the object, specifying the the ini file that contains the settings
  INI := TINIFile.Create('DB.ini');

  // Put reading the INI file inside a try/finally block to prevent memory leaks
  try
    // Demonstrates reading values from the INI file.
    Author      := INI.ReadString(C_DB_SECTION,'Author','');
    Pass        := INI.ReadString(C_DB_SECTION,'Pass','');
    DBFile      := INI.ReadString(C_DB_SECTION,'DBFile','');
    MaxAttempts := INI.ReadInteger(C_DB_SECTION,'MaxAttempts',1);

    // Do something with the values read; e.g. verify the password
    if Pass <> '' then
    begin
      // Ask for the password, max attempts = MaxAttempts
      TryCount := MaxAttempts;
      repeat
        write('Please enter password; ', TryCount, ' attempt(s) left: ');
        readln(PassEnter);
        dec(TryCount);
        if (PassEnter <> Pass) and (TryCount > 0) then
          writeln('Wrong Password, please try again');
      until(PassEnter = Pass) or (TryCount = 0);

      // Correct password given?
      if PassEnter = Pass then
        writeln('Correct Password.')
      else
        writeln('Invalid password, but maxiumm number of password attempts reached.');
    end;

    writeln('Author               : ', Author);
    writeln('File                 : ', DBFile);
    writeln('Password             : ', Pass);
    writeln('Max password attempts: ', MaxAttempts);
    writeln;
    write('Press Enter to close...');
    Readln;

  finally
    // After the ini file was used it must be freed to prevent memory leaks.
    INI.Free;
  end;
end.

Objects to know

In the TINIFile class there are many different properties, procedures and functions that can be used.

CaseSensitive - This property allows you to say if the keys and sections are case sensitive or not. By default they aren't.

ReadString - Has 3 constant statements. The first one is the section to search in. The second one is the key to look for. The third one is a default string in case the key and/or section searched for is not found.

WriteString - has three constant statements, too. The first is the section. The second is the key and the last is the value that you want to write. If the key and section exist already, the key will be overwritten with the new value..

ReadSections - Will allow you to to take the sections from the INI file and put them in a TStrings class (or TStringList with the AS operator).

DeleteKey - Remove an existing key from a specific section.

EraseSection - Remove a section and all its data.

There are more procedures and functions but this is enough to get you started.

Reference Documentation

Here: Free Pascal documentation on INI files

See also