Pliki konfiguracyjne

Na początek definicja wg wiki:

Plik konfiguracyjny – plik komputerowy używany do zmiany ustawień niektórych programów komputerowych.

Pliki konfiguracyjne są najczęściej czytane w momencie startu programu (chociaż nie ma pod tym względem żadnych ograniczeń) i służą do przechowywania informacji z jakimi parametrami program ma być uruchomiony (np. kolory, ścieżki dostępu, wersje językowe itp.).

Pliki INI

W AutoIt wykorzystuje się pliki w formacie INI opracowanym przez Microsoft jako format plików konfiguracyjnych wczesnych wersji systemu Windows.

Pliki INI są zwykłymi plikami tekstowymi i mają bardzo prostą budowę:

[sekcja]
klucz=wartość
     ...

gdzie:

sekcja - nazwa sekcji

klucz - nazwa klucza

Wartość - wartość klucza, może być dowolną liczbą lub łańcuchem znakowym (stringiem)

Oczywiście plik INI może zawierać wiele sekcji, a w każdej sekcji wiele kluczy. Podział na sekcje umożliwia wprowadzenie porządku w danych, poprzez grupowanie tych o podobnym zastosowaniu. Ponadto można w różnych sekcjach stosować klucze o tych samych nazwach.

AutoIt posiada kilka funkcji służących do tworzenia, edycji i odczytu plików INI.

Funkcje do zapisu i edycji plików INI

Funkcja do zapisu klucza

IniWrite("nazwa_pliku", "sekcja", "klucz", wartość)

Funkcja zwraca 1 gdy sukces lub 0 gdy plik ma atrybut "tylko do odczytu"

Parametry:

"nazwa_pliku" - nazwa pliku konfiguracyjnego (może być ze ścieżką dostępu)

Pozostałe parametry jak w opisie formatu.

Jeżeli podany plik nie istnieje to zostanie utworzony (nie są tworzone jednak nieistniejące foldery wypisane w ścieżce dostępu, plik nie zostanie utworzony ale żaden błąd nie będzie zgłaszany).

Jeżeli nie istnieje sekcja lub klucz, to zostaną utworzone. Jeżeli istnieje sekcja i klucz to zostanie zmieniona jego wartość.

IniWrite("ustawienia.ini", "Kolory","Kolor_1", "czerwony")

W plikach INI nie są zapisywane cudzysłowy. Jeżeli z jakiś powodów chcemy je umieścić w nazwach lub wartościach, należy je ująć w apostrofy np.:

IniWrite("ustawienia.ini", "Kolory", "Kolor_1", '"czerwony"')

Nie można wprowadzać wartości wielowierszowych. Nie spowoduje to błędu, ale zapamiętana wartość zostanie obcięta na pierwszym znaku nowej linii:

IniWrite("ustawienia.ini", "Kolory","Kolor_1", "czerwony"&@LF&"niebieski")

Zapamiętana zostanie tylko wartość "czerwony".

Funkcja zapisuje całą sekcję, wraz z zawartymi w niej kluczami

IniWriteSection ( "nazwa_pliku", "sekcja", "dane" [, indeks ] )

Wartości zwracane, "nazwa_pliku", "sekcja", oraz uwagi dotyczące tworzenia pliku i zmian wartości kluczy jak dla IniWrite.

"dane" - string zawierający nazwy kluczy i ich wartości, albo nazwa tablicy z danymi

Jeżeli dane są stringiem to każda para klucz=wartość musi być rozdzielona znakiem końca linii (@LF) n.: "kl1=10"&@LF&"kl2=20"&@LF&"kl3="niebieski".

Jeżeli dane zawarte są w tablicy, to tablica ta musi być dwuwymiarowa. Pierwszy wymiar ma minimum tyle elementów ile jest kluczy, a drugi wymiar ma dwie komórki (zerowy zawiera nazwę klucza, a pierwsza jego wartość).

indeks - parametr opcjonalny określający od którego elementu tablicy mają być zapisywane dane, domyślnie jest 1.

UWAGA: Aby zachować zgodność z formatem tablicy zwracanej przez funkcję IniReadSection należy zadeklarować tablicę o ilości komórek w pierwszy wymiarze o 1 większą od ilości kluczy i w komórce [0,0] wpisać ilość kluczy

[0,0] - ilość kluczy     [0,1] - niewykorzystane
[1,0] - nazwa 1 klucza   [1,1] - wartość 1 klucza
[2,0] - nazwa 2 klucza   [2,1] - wartość 2 klucza
                    ...

Przykład (dane jako string):

;zapis sekcji w pliku INI, dane w postaci stringu
IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20"&@LF&"kl3=niebieski") 
MsgBox(0, "", FileRead("ustawienia.ini"))                  ;podgląd zawartości pliku INI

Przykład (dane jako tablica):

;zadeklarowanie tablicy, format zgodny z IniReadSection
Dim $aArray[4][2]=[[3,0], ["kl1", 10], ["kl2", 20], ["kl3", "niebieski"]]
IniWriteSection("ustawienia.ini", "sekcja_1", $aArray)           ;zapis sekcji w pliku INI
MsgBox(0, "", FileRead("ustawienia.ini"))                        ;podgląd zawartości pliku INI

Funkcja usuwająca klucz lub całą sekcję

IniDelete("nazwa_pliku", "sekcja", ["klucz"])

Wartości zwracane i parametry jak dla IniWrite.

Funkcja usuwa klucz z określonej sekcji. Jeżeli nie podamy nazwy klucza to zostanie usunięta cała sekcja, wraz z wszystkimi znajdującymi się w niej kluczami.

IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20")             ;tworzenie sekcji_1 z dwoma kluczami
IniWriteSection("ustawienia.ini", "sekcja_2", "kl1=czerwony"&@LF&"kl2=niebieski");tworzenie sekcji_2 z dwoma kluczami
MsgBox(0, "", FileRead("ustawienia.ini"))                                        ;wyświetlenie zawartości pliku INI
IniDelete("ustawienia.ini", "sekcja_1", "kl1")                                   ;usunięcie klucza kl1 z sekcji_1
MsgBox(0, "", FileRead("ustawienia.ini"))                                        ;wyświetlenie zawartości pliku INI
IniDelete("ustawienia.ini", "sekcja_2")                                          ;usunięcie sekcji_2 z wszystkimi kluczami
MsgBox(0, "", FileRead("ustawienia.ini"))                                        ;wyświetlenie zawartości pliku INI

Funkcja zmieniająca nazwę sekcji

IniRenameSection ( "nazwa_pliku", "sekcja", "nowa sekcja" [, flag] )

Funkcja zmienia nazwę sekcji w standardowym pliku INI. Zwraca <>0 gdy sukces lub 0 gdy niepowodzenie.

Parametry:

"nazwa_pliku" - nazwa pliku konfiguracyjnego (może być ze ścieżką dostępu)

"sekcja" - sekcja do zmiany nazwy

"nowa sekcja" - nowa nazwa sekcji

flag - parametr opcjonalny

0 - niepowodzenie, gdy istnieje już sekcja o podanej nazwie (domyślne), zmiana nie jest wykonana, a funkcja zwróci wartość 0

1 - nadpisanie kluczy, gdy istnieje już sekcja o podanej nazwie

Przykład:

IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20")              ;tworzenie sekcji_1 z dwoma kluczami
IniWriteSection("ustawienia.ini", "sekcja_2", "kl3=czerwony"&@LF&"kl4=niebieski") ;tworzenie sekcji_2 z dwoma kluczami
MsgBox(0, "", FileRead("ustawienia.ini"))                                         ;podgląd zawartości pliku INI
IniRenameSection("ustawienia.ini", "sekcja_1", "nowa_sekcja")                     ;zmiana nazwy sekcji_1 na nowa_sekcja
MsgBox(0, "", FileRead("ustawienia.ini"))                                         ;podgląd zawartości pliku INI
IniRenameSection("ustawienia.ini", "sekcja_2", "nowa_sekcja",1)    ;nazwy sekcji_2 na nowa_sekcja z nadpisaniem kluczy
MsgBox(0, "", FileRead("ustawienia.ini"))                                         ;podgląd zawartości pliku INI

Funkcje do odczytu plików INI

Funkcja wczytująca wartość pojedynczego klucza

IniRead ("nazwa_pliku", "sekcja", "klucz", "domyślny" )

Funkcja zwraca wartość klucza lub string "domyślny" jeżeli klucz nie został odnaleziony.

Przykład:

IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20")             ;tworzenie sekcji_1 z dwoma kluczami
IniWriteSection("ustawienia.ini", "sekcja_2", "kl1=czerwony"&@LF&"kl2=niebieski");tworzenie sekcji_2 z dwoma kluczami
MsgBox(0, "", IniRead("ustawienia.ini", "sekcja_2","kl2","brak klucza"))         ;wyświetli: niebieski
MsgBox(0, "", IniRead("ustawienia.ini", "sekcja_2","kl3","brak klucza"))         ;wyświetli: brak klucza

Funkcja wczytująca nazwy i wartości kluczy z całej sekcji

IniReadSection ( "nazwa_pliku", "sekcja" )

Funkcja zwraca dwuwymiarową tablicę. Pierwszy wymiar ma tyle komórek ile jest kluczy+1, a drugi wymiar ma dwie komórki (zerowa zawiera nazwę klucza, a pierwsza jego wartość). W komórce [0,0] zapisana jest ilość kluczy, komórka [0,1] nie jest wykorzystana.

[0,0] - ilość kluczy     [0,1] - niewykorzystane
[1,0] - nazwa 1 klucza   [1,1] - wartość 1 klucza
[2,0] - nazwa 2 klucza   [2,1] - wartość 2 klucza
                    ...

Jeżeli wystąpi błąd (np. brak pliku lub sekcji o podanej nazwie), funkcja oraz makro @error przyjmują wartość 1.

Przykład:

#include <Array.au3>  
IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20")             ;tworzenie sekcji_1 z dwoma kluczami
IniWriteSection("ustawienia.ini", "sekcja_2", "kl1=czerwony"&@LF&"kl2=niebieski");tworzenie sekcji_2 z dwoma kluczami
$aArray = IniReadSection("ustawienia.ini", "sekcja_2")                           ;utworzenie tablicy z kluczami
_ArrayDisplay($aArray)                                                           ;podgląd zawartości tablicy

Funkcja wczytująca nazwy wszystkich sekcji w pliku INI

IniReadSectionNames ( "nazwa_pliku" )

Funkcja zwraca jednowymiarową tablicę, w komórce [0] wpisuje ilość sekcji, a w następnych kolejne nazwy sekcji. Jeżeli wystąpi błąd (np. brak pliku), funkcja oraz makro @error przyjmują wartość 1.

Przykład:

#include <Array.au3>  
IniWriteSection("ustawienia.ini", "sekcja_1", "kl1=10"&@LF&"kl2=20")             ;tworzenie sekcji_1 z dwoma kluczami
IniWriteSection("ustawienia.ini", "sekcja_2", "kl1=czerwony"&@LF&"kl2=niebieski");tworzenie sekcji_2 z dwoma kluczami
$aArray = IniReadSectionNames("ustawienia.ini")                                  ;utworzenie tablicy z nazwami sekcji
_ArrayDisplay($aArray)                                                           ;podgląd zawartości tablicy