Po wielu miesiącach żmudnej pracy, w końcu udało się ukończyć pracę nad projektem TreeStructInfo; Poniżej znajduje się więc ogólny opis zarówno formatu plików, jak i przygotowanego API do ich obsługi, dlatego że jest to zaganienie dość obszerne;
Strona projektu: https://tsinfo.4programmers.net
Specyfikacja formatu: https://tsinfo.4programmers.net/pl/format/1.0.htm
Czym jest TreeStructInfo?
Format TreeStructInfo to projekt tekstowych i binarnych plików konfiguracyjnych, umożliwiających zapis informacji w postaci czytelnych drzewiastych struktur; Opracowany został z myślą o przechowywaniu różnego rodzaju ustawień aplikacji, gier i innych narzędzi; Umożliwia tworzenie zarówno prostych - jednoplikowych konfiguracji, a także bardziej złożonych, wieloplikowych systemów konfiguracyjnych; Nie jest on zależny od platform programowych, więc można z niego korzystać np. pod Windows, Linuks czy OS X;
Format ten według mnie stanowi ciekawą alternatywę przede wszytkim dla rejestru systemu oraz plików Ini, a także dla takich formatów jak XML, YAML czy TOML, z racji bardzo prostej budowy i składni, a także unikalnej funkcjonalności;
Uwaga! Format TreeStructInfo nie powinien być stosowany w zastępstwie systemów bazodanowych - nie takie jest jego pierwotne przeznaczenie i do tego się zbytnio nie nadaje;
1. Formy plików TreeStructInfo
Format ten przewiduje dwie formy plików konfiguracyjnych - tekstową oraz binarną; Pomiędzy tymi formami istnieje pełna kompatybilność; Dowolny plik tekstowy przekonwertowany na formę binarną i z powrotem, będzie posiadać dokładnie taką samą zawartość, jak pierwotna - konwersja nie powoduje utraty części zapisanych informacji;
Pliki binarne zawierać mogą te same elementy, co pliki tekstowe;
1.1. Forma tekstowa
Forma ta służy do tworzenia otwartych konfiguracji, umożliwiając tworzenie plików w dowolnych edytorach, a także umoliżliwiając użytkownikowi swobodę wprowadzania modyfikacji;
Pliki w formie tekstowej budowane są w sposób liniowy - jedna linia może zawierać tylko jedną informację (np. nagłówek drzewa, deklarację atrybutu itd.); Kolejnym atutem jest bardzo czytelna składnia, oparta na niedużej ilości słów i fraz kluczowych, a także znikomej liczby używanych znaków specjalnych; Dzięki temu zawartość plików tekstowych jest bardzo przyjazna dla człowieka, a zapisywane do atrybutów dane mogą zawierać praktycznie dowolne znaki, z wyjątkiem kilku zarezerwowanych;
Przykładowy plik: https://tsinfo.4programmers.net/pl/format/1.0.htm#idSampleFile
Główną zaletą plików tekstowych jest możliwość dzielenia drzewa konfiguracji na mniejsze części, co może znacząco wpłynąć na ich czytelność; Dzielenie drzewa odbywa się za pomocą referencjonowania elementów - ich deklaracje określają miejsce elementów w drzewie, zaś definicje posiadają już konkretną zawartość;
Fragmentacja drzewa z wykorzystaniem referencjonowanych elementów to pierwszy z dwóch metod dzielenia drzew; Drugim sposobem jest podział drzewa na wiele plików, powiązanych ze sobą na podstawie dowiązań (linków do plików dołączanych);
Więcej: https://tsinfo.4programmers.net/pl/format/1.0.htm#idTextForm
1.2. Forma binarna
Forma binarna służy do przechowywania takich samych konfiguracji jak forma tekstowa, jednak odróżnia ją mniejszy (czasem znacząco) rozmiar, a także dużo większa szybkość ładowania zawartości plików do pamęci; Dzieje się tak dlatego, że do plików binarnych nie są zapisywane takie informacje jak słowa kluczowe czy wcięcia, a przetwarzanie tych plików odbywa się bardzo prostą i szybką rekurencyjną techniką;
Forma ta przeznaczona jest dla zamkniętych konfiguracji, zawartych w większych plikach, dzięki czemu ich ładowanie jest po prostu krótsze, prostsze i szybsze; Natomiast w żadnym wpadku nie służy do maskowania danych, dlatego że zawartość nie jest szyfrowana;
Więcej: https://tsinfo.4programmers.net/pl/format/1.0.htm#idBinaryForm
2. Elementy drzew
Do budowy drzew wykorzystywane są trzy typy elementów: atrybuty, węzły oraz linki do plików dołączanych; Przeznaczenie poszczególnych elementów:
- atrybuty - służą do przechowywania pojedynczych danych; Przechowywane mogą być dane wielu typów i w wielu postaciach, jako wartości jednoliniowe lub wieloliniowe;
- węzły - umożliwiają grupowanie elementów oraz tworzenia drzewiastej struktury informacji;
- linki do plików dołączanych - udostępniają możliwość dowiązania w ich miejscu innych drzew, zawartych w osobnych plikach; Dołączane drzewa z zewnętrznych plików mogą być zapisane w dowolnej formie (tekstowej lub binarnej); Elementami łączącymi drzewa w miejscu linków są tzw. węzły wirtualne;
Więcej: https://tsinfo.4programmers.net/pl/format/1.0.htm#idBasicElements
3. Komentarze
Format ten zezwala na używanie komentarzy zarówno jednoliniowych, jak i wieloliniowych; Same komentarze nie są postrzegane jako osobne elementy - są integralną częścią elementów drzew, a także samych drzew i nie mogą istnieć w dowolnych miejscach plików;
Komentarze dzielą się na dwie grupy - główny komentarz drzewa, zapisywany na samym początku plików, a także komentarze elementów, zapisywane zawsze ponad deklaracjami lub definicjami elementów;
Elementy referencjonowane (których ciała definiowane sa poza głównym ciałem drzewa) mogą posiadać dwa komentarze - jeden deklaracji i jeden definicji; Mogą być jedno lub wieloliniowe; Elementy te nie muszą posiadać ich obu - mogą posiadać tylko jeden (deklaracji lub definicji), lub nie posiadać go wcale;
Wszelkie komentarze są informacjami dodatkowymi i nieobowiązkowymi, bez względu na ich typ;
Więcej: https://tsinfo.4programmers.net/pl/format/1.0.htm#idComments
4. Tworzenie systemów konfiguracyjnych
Format umożliwia także tworzenie rozbudowanych, wieloplikowych konfiguracji; Z racji tej, że dowolne pliki TreeStructInfo nie zawierają w sobie informacji o tym, czy egzystują jako pojedyncze pliki, czy są dołączane przez inne pliki, do budowy systemów konfiguracyjnych można wykorzystać zarówno pliki tekstowe, jak i binarne;
Pliki natomiast mogą posiadać informację o tym, czy same linkują inne pliki; Informacje te zapisywane są za pomocą linków do plików dołączanych;
Liczba plików, z których budowane są systemy konfiguracyjne nie jest ustalona, więc można wykorzystać dowolną ich ilość; Nie zaleca się jednak tworzenia zbyt wielkich systemów - główny plik nie powinien linkować więcej, niż kilkanaście plików; Jeśli istnieć będzie potrzeba przechowywania dużo większych konfiguracji - rozwiązaniem jest stworzenie po prostu większej liczby głównych plików;
5. Dostęp do elementów drzew
Kolejnym atutem formatu jest dostęp do elementów drzew na podstawie standardowych ścieżek, na podobieństwo śieżek do elementów rejestru Windows; Ścieżki dostępu tworzone są z nazw elementów oraz znaków separatora - znaku \
;
Ścieżki do elementów drzew posiadają zawsze taką samą formę; Zawsze - bez względu na to, czy odwołujemy się do elementu w tym samym drzewie, czy do elementu z drzewa linkowanego; A jeśli z drzewa linkowanego, to bez względu na poziom dowiązania (drzewo linkowane także może linkować następne, a następne także następne);
Dzięki takiemu rozwiązaniu, pliki formatu TreeStructInfo stają się bardziej przyjazne i jeszcze prostsze w użyciu we własnych programach;
Ścieżki dostępu nie są używane do budowy plików konfiguracyjnych - wykorzystywane sa jedynie w API, podczas zapisu lub odczytu danych;
Więcej: https://tsinfo.4programmers.net/pl/format/1.0.htm#idElementsPaths
6. Podsumowanie
Powyższy, mocno skrócony opis formatu przedstawia tylko najważniejsze jego możliwości; Funkcjonalność formatu jest na tyle bogata, że pliki konfiguracyjne TreeStructInfo posiadają szeroki wachlarz zastosowań; Zastosowane zabiegi zależą głównie od potrzeb oraz wyobraźni;
Szczegółowy opis możliwości formatu przedstawiony jest specyfikacji pierwszej wersji formatu, do której link znajduje się na samej górze tego posta;
API do obsługi plików TreeStructInfo
Sam format miałby niewielką wartość, gdyby nie było żadnej możliwości jego wykorzystania we własnych programach; Dlatego też stworzyłem bibliotekę, która pozwala na wykorzystywanie plików konfiguracyjnych w obu formach, w pełnej zgodzie ze specyfikacją; Biblioteka ta umożliwia wykorzystanie wszystkich aspektów formatu;
Co umożliwia oficjalne API:
- ładowanie plików konfiguracyjnych w obu formach z różnych źródeł - z plików dyskowych, z list lub strumieni, a także z zasobów plików wykonywalnych lub bibliotek DLL, na podstawie nazwy lub ID;
- zapis i odczyt danych wszystkich opisanych w specyfikacji typów danych:
- wartości logiczne - różne łańcuchy,
- liczby całkowite - różne systemy liczbowe (dec, hex, oct i bin)
- liczby rzeczywiste - różne notacje,
- walutę - różna precyzja,
- pojedyncze znaki - wartość znaku lub jego kod w różnych systemach liczbowych,
- łańcuchy znaków - jednoliniowe lub wieloliniowe,
- data i czas - dowolny format, wraz z dodatkowymi, nieformatowanymi ciągami,
- współrzędne punktów - różne systemy liczbowe,
-
listy - zawartość dowolnych list dziedziczących po klasie
TStrings
, -
strumienie - zawartości dowolnych strumieni dziedziczących po klasie
TStream
, - dowolnych buforów - możliwość zapisu dowolnych danych w postaci mapy heksadecymalnej;
- obsługę dowolnych systemów konfiguracyjnych;
- znacznie, znacznie więcej;
Biblioteka ta napisana została w Lazarusie, pod FPC 2.6.2, ale ze względów na wykorzystane podstawowe elementy kodu, możliwe jest jej użycie we wcześniejszych wersajch FPC; Nie jest też uzależniona od platformy, więc nadaje się nie tylko dla Windows;
Do przygotowanego API stworzona została także dokumentacja, opisująca dosłownie każdy element API (od stałych, przez typy i wpólne procedury i funkcje, po klasy i ich składowe); Wszystkie informacje o API są w dokumentacji on-line, dlatego też nie było potrzeby komentowania kodu;
Oprócz samej dokumentacji przygotowany został tutorial, przedstawiający różne sposoby wykorzystania oficjalnej biblioteki; Opisuje on wszystkie metody i właściwości klas do obsługi plików - klasy TSimpleTSInfoFile
z podstawową funkcjonalnością oraz TTSinfoFile
, zawierającej metody dodatkowe, rzadziej używane;
Oficjalne API do pobrania: https://tsinfo.4programmers.net/pl/download/index.htm
Dokumentacja API: [link nieaktywny]
Tutorial API: [link nieaktywny]
Bibliotekę udostępniam na warunkach licencji GNU Lesser GPL 3, więc z otwartym źródłem i możliwością wykorzystania jej w dowolnych projektach - otwartych lub zamkniętych, darmowych lub komercyjnych; Korzystajcie więc jak Wam się podoba;
To tyle jeśli chodzi o ogólne informacje na temat projektu TreeStructInfo; Wszystkich zainteresowanych zachęcam do zapoznania się ze specyfikacją formatu, a Pascalowców programujących w Lazarusie, o zapoznanie się i przetestowanie oficjalnego API;
Mam nadzieję, że projekt przypadnie do gustu i że znajdą się chętni do jego wykorzystania we własnych aplikacjach czy grach;Pozostałych zachęcam do pomocy w rozwijaniu projektu - być może ktoś miałby czas i chciałby wspomóc projekt swoim API, napisanym w innym języku niż Object Pascal;
Przygotowałem ten format i API także dla siebie - z tego formatu będę korzystał w swoich przyszłych programach; No i grach, bo SnakeASCII już został przystosowany do tego formatu - dane dotyczące podstawowych plansz będą zapisane w plikach TreeStructInfo i wrzucone do zasobów pliku wykonywalnego, skąd API umożliwia odczyt plików w bardzo prosty sposób;
Przy okazji dziękuję wszystkim za pomoc przy pracy nad tym projektem, głównie @babubabu - który poświęcił czas na przetestowanie biblioteki;
Życzę więc miłej lektury specyfikacji i przyjemnego korzystania z oficjalnej biblioteki :]