Difference between revisions of "Using INI Files/pl"

From Lazarus wiki
Jump to navigationJump to search
(tłumaczenie na j. polski)
 
(tłumaczenie na j. polski, dokończenie)
Line 113: Line 113:
 
{{Uwaga| Sprawy mogą się nie udać. Aby zapewnić czytelność, powyższy kod pominął ważne instrukcje '''try''', które mogą zapobiec awariom lub wyciekom pamięci, jeśli wydarzy się coś nieoczekiwanego. Prawdziwy kod potrzebuje takiej ochrony.}}
 
{{Uwaga| Sprawy mogą się nie udać. Aby zapewnić czytelność, powyższy kod pominął ważne instrukcje '''try''', które mogą zapobiec awariom lub wyciekom pamięci, jeśli wydarzy się coś nieoczekiwanego. Prawdziwy kod potrzebuje takiej ochrony.}}
  
==Ini file reading example==
+
==Przykład odczytu pliku ini==
  
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.
+
Poniższa aplikacja konsolowa pokazuje, jak czytać pliki ini. Aby to przetestować, utwórz plik ini o nazwie „DB.ini” i zawartości jak podano poniżej, a następnie zapisz go w tym samym folderze co program wykonywalny.
  
 
<syntaxhighlight lang="ini">
 
<syntaxhighlight lang="ini">
Line 125: Line 125:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
   
 
   
The code to read this ini file:
+
Kod do odczytu tego pliku ini wygląda tak:
  
 
<syntaxhighlight lang=pascal>
 
<syntaxhighlight lang=pascal>
Line 145: Line 145:
 
   TryCount: integer;
 
   TryCount: integer;
 
begin
 
begin
   // Create the object, specifying the the ini file that contains the settings
+
   // Utwórz obiekt, określając plik ini, który zawiera ustawienia
 
   INI := TINIFile.Create('DB.ini');
 
   INI := TINIFile.Create('DB.ini');
  
   // Put reading the INI file inside a try/finally block to prevent memory leaks
+
   // Umieść kod odczytujący plik INI w bloku try/finally, aby zapobiec wyciekom pamięci
 
   try
 
   try
     // Demonstrates reading values from the INI file.
+
     // Demonstruje odczytywanie wartości z pliku INI.
 
     Author      := INI.ReadString(C_DB_SECTION,'Author','');
 
     Author      := INI.ReadString(C_DB_SECTION,'Author','');
 
     Pass        := INI.ReadString(C_DB_SECTION,'Pass','');
 
     Pass        := INI.ReadString(C_DB_SECTION,'Pass','');
Line 156: Line 156:
 
     MaxAttempts := INI.ReadInteger(C_DB_SECTION,'MaxAttempts',1);
 
     MaxAttempts := INI.ReadInteger(C_DB_SECTION,'MaxAttempts',1);
  
     // Do something with the values read; e.g. verify the password
+
     // Zrób coś z odczytanymi wartościami; np. zweryfikuj hasło
 
     if Pass <> '' then
 
     if Pass <> '' then
 
     begin
 
     begin
       // Ask for the password, max attempts = MaxAttempts
+
       // Zapytaj o hasło, maksymalna ilość prób = MaxAttempts
 
       TryCount := MaxAttempts;
 
       TryCount := MaxAttempts;
 
       repeat
 
       repeat
         write('Please enter password; ', TryCount, ' attempt(s) left: ');
+
         write('Proszę wprowadzić hasło; ', TryCount, ' pozostało prób: ');
 
         readln(PassEnter);
 
         readln(PassEnter);
 
         dec(TryCount);
 
         dec(TryCount);
 
         if (PassEnter <> Pass) and (TryCount > 0) then
 
         if (PassEnter <> Pass) and (TryCount > 0) then
           writeln('Wrong Password, please try again');
+
           writeln('Błędne hasło, spróbuj ponownie');
 
       until(PassEnter = Pass) or (TryCount = 0);
 
       until(PassEnter = Pass) or (TryCount = 0);
  
       // Correct password given?
+
       // Czy podano prawidłowe hasło?
 
       if PassEnter = Pass then
 
       if PassEnter = Pass then
         writeln('Correct Password.')
+
         writeln('Hasło jest prawidłowe.')
 
       else
 
       else
         writeln('Invalid password, but maxiumm number of password attempts reached.');
+
         writeln('Nieprawidłowe hasło i osiągnięto maksymalną liczbę prób hasła.');
 
     end;
 
     end;
  
     writeln('Author              : ', Author);
+
     writeln('Autor                      : ', Author);
     writeln('File                : ', DBFile);
+
     writeln('Plik                        : ', DBFile);
     writeln('Password            : ', Pass);
+
     writeln('Hasło                      : ', Pass);
     writeln('Max password attempts: ', MaxAttempts);
+
     writeln('Maksymalna liczba prób hasła: ', MaxAttempts);
 
     writeln;
 
     writeln;
     write('Press Enter to close...');
+
     write('Naciśnij Enter, aby zamknąć...');
 
     Readln;
 
     Readln;
  
 
   finally
 
   finally
     // After the ini file was used it must be freed to prevent memory leaks.
+
     // Po użyciu pliku ini należy go zwolnić, aby zapobiec wyciekom pamięci.
 
     INI.Free;
 
     INI.Free;
 
   end;
 
   end;
Line 191: Line 191:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Handling of string representations of boolean values ==
+
== Obsługa reprezentacji ciągów wartości logicznych ==
The TiniFile.ReadBool and TIniFile.WriteBool functions use values of "0" (false) and "1" to represent boolean values in the ini file. You can change this to any other text you want:
+
Funkcje TiniFile.ReadBool i TIniFile.WriteBool używają wartości „0” (fałsz) i „1” do reprezentowania wartości logicznych w pliku ini. Możesz to zmienić na dowolny inny tekst:
  
 
<syntaxhighlight lang=pascal class="notranslate">
 
<syntaxhighlight lang=pascal class="notranslate">
Line 202: Line 202:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
ReadBool is not case-sensitive, the texts "true", "True" and "TRUE" are all interpreted as boolean true.
+
ReadBool nie rozróżnia wielkości liter, teksty „true”, „true” i „TRUE” są interpretowane jako prawda logiczna.
  
TIniFile.BoolTrueStrings and TIniFile.BoolFalseStrings are arrays of string, you can specify multiple values:
+
TIniFile.BoolTrueStrings i TIniFile.BoolFalseStrings to tablice łańcuchów, można określić wiele wartości:
  
 
<syntaxhighlight lang=pascal class="notranslate">
 
<syntaxhighlight lang=pascal class="notranslate">
 
[...]
 
[...]
 
   iniFile.Options := iniFile.Options + [ifoWriteStringBoolean];
 
   iniFile.Options := iniFile.Options + [ifoWriteStringBoolean];
   iniFile.BoolTrueStrings := ['true','yes','1'];
+
   iniFile.BoolTrueStrings := ['true','yes','tak','1'];
   iniFile.BoolFalseStrings := ['false','no','0'];
+
   iniFile.BoolFalseStrings := ['false','no','nie','0'];
 
[...]
 
[...]
 
</syntaxhighlight>
 
</syntaxhighlight>
  
When reading from the ini file, any of the array values will make ReadBool return the correct boolean value, when writing the ini file, the first value of the corresponding array is used.
+
Podczas odczytu z pliku ini, każda z wartości tablicy spowoduje, że ReadBool zwróci poprawną wartość logiczną, podczas zapisywania pliku ini używana jest pierwsza wartość odpowiedniej tablicy.
  
{{Warning|The current implementation if TIniFile.ReadBool has an odd behaviour, when the ifoWriteStringBoolean option is set. TIniFile.ReadBool and TIniFile.WriteBool have, when the BoolTrueStrings and BoolFalseStrings  arrays are not specified, an asymmetrical behaviour: TIniFile.ReadBool will expect "0" or "1", and TIniFile.WriteBool will write "true" or "false". This will lead to the surprising behavior that the TIniFile.ReadBool function won't be able to read back the "true" values if they were written by the TIniFile.WriteBool function. TIniFile.ReadBool will always return boolean false instead, even if a value is set to "true" in the ini file. If you use the ifoWriteStringBoolean option, and unless this behavior is the desired behaviour, don't forget to specify the TIniFile.BoolTrueStrings and TIniFile.BoolFalseStrings arrays.}}
+
{{Warning|Aktualna implementacja TIniFile.ReadBool działa tak, że zachowuje się dziwnie, gdy ustawiona jest opcja ifoWriteStringBoolean. Gdy nie określono tablic BoolTrueStrings i BoolFalseStrings, to TIniFile.ReadBool i TIniFile.WriteBool zachowują się asymetryczne: TIniFile.ReadBool będzie oczekiwać „0” lub „1”, a TIniFile.WriteBool zapisze „true” lub „false”. Doprowadzi to do zaskakującego zachowania polegającego na tym, że funkcja TIniFile.ReadBool nie będzie w stanie odczytać z powrotem wartości „true”, jeśli zostały zapisane przez funkcję TIniFile.WriteBool. TIniFile.ReadBool w tej sytuacji zawsze zwróci wartość logiczną false, nawet jeśli w pliku ini wartość ta jest ustawiona na „true”. Jeśli używasz opcji ifoWriteStringBoolean i to zachowanie nie jest pożądanym zachowaniem, nie zapomnij określić tablic TIniFile.BoolTrueStrings i TIniFile.BoolFalseStrings.}}
  
==Objects to know==
+
==Obiekty do poznania==
  
In the TINIFile class there are many different properties, procedures and functions that can be used.
+
W klasie TINIFile istnieje wiele różnych właściwości, procedur i funkcji, których można użyć.
  
'''CaseSensitive''' - This property allows you to say if the keys and sections are case sensitive or not. By default they aren't.
+
'''CaseSensitive''' — Ta właściwość pozwala określić, czy w kluczach i sekcjach jest rozróżniana wielkość liter, czy nie. Domyślnie nie są.
  
'''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.
+
'''ReadString''' - Ma 3 stałe parametry. Pierwszy to sekcja, w której należy szukać. Drugi jest kluczem do wyszukania. Trzeci jest domyślnym ciągiem na wypadek, gdyby szukany klucz i/lub sekcja nie zostały znalezione.
  
'''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..
+
'''WriteString''' - Również zawiera trzy stałe parametry. Pierwszy to sekcja. Drugi to klucz, a ostatni to wartość, którą chcesz wpisać. Jeśli klucz i sekcja już istnieją, klucz zostanie nadpisany nową wartością.
  
'''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).
+
'''ReadSections''' - Pozwala pobrać sekcje z pliku INI i umieścić je w klasie TStrings (lub TStringList z operatorem AS).
  
'''DeleteKey''' - Remove an existing key from a specific section.
+
'''DeleteKey''' — Usuń istniejący klucz z określonej sekcji.
  
'''EraseSection''' - Remove a section and all its data.
+
'''EraseSection''' — Usuń sekcję i wszystkie jej dane.
  
There are more procedures and functions but this is enough to get you started.
+
Procedur i funkcji jest więcej, ale to wystarczy, aby zacząć.
  
===Reference Documentation===
+
===Dokumentacja referencyjna===
  
Here: [http://lazarus-ccr.sourceforge.net/docs/fcl/inifiles/index.html Free Pascal documentation on INI files]
+
Tutaj jest: [http://lazarus-ccr.sourceforge.net/docs/fcl/inifiles/index.html Dokumentacja Free Pascal na temat INI files]
  
= See also =
+
= Zobacz także =
  
* [[HistoryFiles]]
+
* [[HistoryFiles | Historia plików]]
* [[XML Tutorial]]
+
* [[XML Tutorial | Poradnik o XML]]

Revision as of 23:04, 29 September 2022

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

Używanie plików INI

INI Files

Basic Information

Pliki INI to pliki tekstowe, które przechowują pary klucz/wartość pogrupowane w sekcje.

Pliki INI mogą być używane do łatwego zapisywania ustawień użytkownika. Możesz ułatwić sobie z nimi pracę za pomocą modułu IniFiles i klasy TINIFile. Moduł IniFiles jest częścią FCL.

Obecnie obsługiwane są tylko pliki INI zgodne z bardziej restrykcyjnym formatem plików ini systemu Windows, w których użycie sekcji jest obowiązkowe, a komentarze mogą zaczynać się tylko od średnika. Aby uzyskać więcej ogólnych informacji o plikach ini, przeczytaj to.

Pliki INI

Pliki INI używają nawiasów do tworzenia i oznaczania Sekcji, które zawierają klucze i wartości klucza. Klucz i odpowiadająca mu wartość są oddzielone znakiem równości (Klucz=Wartość).

Nazwy sekcji umieszczane są w nawiasach kwadratowych ([Sekcja]).

Komentarze są dozwolone i są oznaczone średnikiem (;) na początku linii.

Przykładowy plik ini:

; Komentarz. Początek pliku INI

; puste wiersze są ignorowane

[General]
; Tu rozpoczyna się sekcja ogólna
Compiler=FreePascal
; Key Compiler and value FreePascal
; Kompilator kluczy i wartość FreePascal


Prosty przykład

W praktyce musisz mieć możliwość utworzenia pliku ini w czasie wykonywania programu, gdy on nie istnieje, i ustawienia domyślnych wartości wpisów. Oto przykład przeznaczony do częściowego wklejenia do nowej aplikacji Lazarus. Definiujemy i deklarujemy rekord, który zawiera niektóre z naszych ustawień, mamy pole wyboru, które reprezentuje inne ustawienie. Aby uprościć, jedynym ustawieniem, które możemy tutaj zmienić, jest pole wyboru. Jego zdarzenie wywoływane „przy zmianie” wartości, wyzwala zapis pliku ini, za każdym razem aktualizując dane. Do formularza dodaliśmy również pole Memo, aby w łatwy sposób pokazać, co się dzieje. Dodane są prototypy nowych metod do interfejsu formularza. Dodany jest moduł 'inifiles' w sekcji implementacji.

interface
.......

type SettingRec = record
    X : integer;
    MyName : string;
end; 
....

implementation  
....
uses IniFiles;
const
  IniFile = 'settings.ini';   
....
procedure TForm1.ReadSettings;
var
    Sett : TIniFile;
begin
    Sett := TIniFile.Create(IniFile);
    Settings.X:= Sett.ReadInteger('Main', 'X', 1);    // (Sekcja, Klucz, Domyślna)
    Settings.MyName := Sett.ReadString('Main', 'MyName', 'Davo');
    CheckBox1.Checked := Sett.ReadBool('Main', 'CheckBox', true);
    Sett.Free;
end;

procedure TForm1.WriteSettings;
var
    Sett : TIniFile;
begin
    Sett := TIniFile.Create(IniFile);
    Sett.WriteBool('Main', 'CheckBox', CheckBox1.Checked);
    Sett.WriteInteger('Main', 'X', Settings.X);
    Sett.WriteString('Main', 'MyName', Settings.MyName);
    Sett.Free;
end;

Zauważ, że nie sprawdzamy, czy plik ini jest obecny, czy nie, to nie ma znaczenia. Jeśli nie ma określonego klucza (lub nie ma całego pliku), to podczas odczytu używana jest wartość domyślna, więc użyj domyślnej, która działa na początku. Wszystkie nasze dane są zapisywane i odczytywane z sekcji „Main” pliku ini. Warto jest pogrupować powiązane ze sobą dane w osobne sekcje. Rzeczywista nazwa sekcji nie ma znaczenia, ale musi być spójna.

Następnie potrzebujemy kilku metod, aby „przećwiczyć” powyższy kod. Oczywiście, możesz użyć używasz Lazarus Object Inspector do tworzenia FormCreate() i CheckBeSillyChange(), ale ich zawartość skopiuj stąd:

procedure TForm1.FormCreate(Sender: TObject);
begin
    ReadSettings;
    ShowSettings;
end;

procedure TForm1.CheckBox1Change(Sender: TObject);
begin
    WriteSettings;
    ShowSettings;
end;

procedure TForm1.ShowSettings;
begin
    Memo1.Clear;
    Memo1.Append('X=' + Settings.X.tostring);
    Memo1.Append('MyName=' + Settings.MyName);
    Memo1.Append('CheckBox ' + Booltostr(CheckBox1.Checked, true));
end;

procedure TForm1.CheckBox1Change(Sender: TObject);
begin
    WriteSettings;
    ShowSettings;
end;

Plik ini może (i musi mieć możliwość) zmienić kolejność prezentowania jego danych, więc nie można polegać na konkretnych numerach wierszy. Template:Uwaga

Przykład odczytu pliku ini

Poniższa aplikacja konsolowa pokazuje, jak czytać pliki ini. Aby to przetestować, utwórz plik ini o nazwie „DB.ini” i zawartości jak podano poniżej, a następnie zapisz go w tym samym folderze co program wykonywalny.

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

Kod do odczytu tego pliku ini wygląda tak:

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
  // Utwórz obiekt, określając plik ini, który zawiera ustawienia
  INI := TINIFile.Create('DB.ini');

  // Umieść kod odczytujący plik INI w bloku try/finally, aby zapobiec wyciekom pamięci
  try
    // Demonstruje odczytywanie wartości z pliku INI.
    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);

    // Zrób coś z odczytanymi wartościami; np. zweryfikuj hasło
    if Pass <> '' then
    begin
      // Zapytaj o hasło, maksymalna ilość prób = MaxAttempts
      TryCount := MaxAttempts;
      repeat
        write('Proszę wprowadzić hasło; ', TryCount, ' pozostało prób: ');
        readln(PassEnter);
        dec(TryCount);
        if (PassEnter <> Pass) and (TryCount > 0) then
          writeln('Błędne hasło, spróbuj ponownie');
      until(PassEnter = Pass) or (TryCount = 0);

      // Czy podano prawidłowe hasło?
      if PassEnter = Pass then
        writeln('Hasło jest prawidłowe.')
      else
        writeln('Nieprawidłowe hasło i osiągnięto maksymalną liczbę prób hasła.');
    end;

    writeln('Autor                       : ', Author);
    writeln('Plik                        : ', DBFile);
    writeln('Hasło                       : ', Pass);
    writeln('Maksymalna liczba prób hasła: ', MaxAttempts);
    writeln;
    write('Naciśnij Enter, aby zamknąć...');
    Readln;

  finally
    // Po użyciu pliku ini należy go zwolnić, aby zapobiec wyciekom pamięci.
    INI.Free;
  end;
end.

Obsługa reprezentacji ciągów wartości logicznych

Funkcje TiniFile.ReadBool i TIniFile.WriteBool używają wartości „0” (fałsz) i „1” do reprezentowania wartości logicznych w pliku ini. Możesz to zmienić na dowolny inny tekst:

[...]
  iniFile.Options := iniFile.Options + [ifoWriteStringBoolean];
  iniFile.BoolTrueStrings := ['true'];
  iniFile.BoolFalseStrings := ['false'];
[...]

ReadBool nie rozróżnia wielkości liter, teksty „true”, „true” i „TRUE” są interpretowane jako prawda logiczna.

TIniFile.BoolTrueStrings i TIniFile.BoolFalseStrings to tablice łańcuchów, można określić wiele wartości:

[...]
  iniFile.Options := iniFile.Options + [ifoWriteStringBoolean];
  iniFile.BoolTrueStrings := ['true','yes','tak','1'];
  iniFile.BoolFalseStrings := ['false','no','nie','0'];
[...]

Podczas odczytu z pliku ini, każda z wartości tablicy spowoduje, że ReadBool zwróci poprawną wartość logiczną, podczas zapisywania pliku ini używana jest pierwsza wartość odpowiedniej tablicy.

Warning-icon.png

Ostrzeżenie: Aktualna implementacja TIniFile.ReadBool działa tak, że zachowuje się dziwnie, gdy ustawiona jest opcja ifoWriteStringBoolean. Gdy nie określono tablic BoolTrueStrings i BoolFalseStrings, to TIniFile.ReadBool i TIniFile.WriteBool zachowują się asymetryczne: TIniFile.ReadBool będzie oczekiwać „0” lub „1”, a TIniFile.WriteBool zapisze „true” lub „false”. Doprowadzi to do zaskakującego zachowania polegającego na tym, że funkcja TIniFile.ReadBool nie będzie w stanie odczytać z powrotem wartości „true”, jeśli zostały zapisane przez funkcję TIniFile.WriteBool. TIniFile.ReadBool w tej sytuacji zawsze zwróci wartość logiczną false, nawet jeśli w pliku ini wartość ta jest ustawiona na „true”. Jeśli używasz opcji ifoWriteStringBoolean i to zachowanie nie jest pożądanym zachowaniem, nie zapomnij określić tablic TIniFile.BoolTrueStrings i TIniFile.BoolFalseStrings.

Obiekty do poznania

W klasie TINIFile istnieje wiele różnych właściwości, procedur i funkcji, których można użyć.

CaseSensitive — Ta właściwość pozwala określić, czy w kluczach i sekcjach jest rozróżniana wielkość liter, czy nie. Domyślnie nie są.

ReadString - Ma 3 stałe parametry. Pierwszy to sekcja, w której należy szukać. Drugi jest kluczem do wyszukania. Trzeci jest domyślnym ciągiem na wypadek, gdyby szukany klucz i/lub sekcja nie zostały znalezione.

WriteString - Również zawiera trzy stałe parametry. Pierwszy to sekcja. Drugi to klucz, a ostatni to wartość, którą chcesz wpisać. Jeśli klucz i sekcja już istnieją, klucz zostanie nadpisany nową wartością.

ReadSections - Pozwala pobrać sekcje z pliku INI i umieścić je w klasie TStrings (lub TStringList z operatorem AS).

DeleteKey — Usuń istniejący klucz z określonej sekcji.

EraseSection — Usuń sekcję i wszystkie jej dane.

Procedur i funkcji jest więcej, ale to wystarczy, aby zacząć.

Dokumentacja referencyjna

Tutaj jest: Dokumentacja Free Pascal na temat INI files

Zobacz także