TreeStructInfo 2.0
TreeStructInfo (ang. Tree Structure Information — drzewiasta struktura informacji) — to uniwersalny format tekstowych i binarnych plików konfiguracyjnych, przeznaczonych do przechowywania różnego rodzaju konfiguracji aplikacji i gier w formie drzew danych.
Format TreeStructInfo zaprojektowany został tak, aby był przyjazny dla człowieka, ale także jak najbardziej funkcjonalny i prosty do przetwarzania. Tekstowa forma plików konfiguracyjnych ma być przyjazna i dla programistów, i dla użytkowników, dzięki bardzo prostej składni oraz liniowej budowie pliku. Natomiast forma binarna sprzyjać ma szybkości przetwarzania plików, z zachowaniem kompatybilnej z formą tekstową struktury danych w pamięci.
główne założenia formatu
- ma być przyjazny dla człowieka
- łatwy do analizy
- łatwy do wprowadzania modyfikacji
- ma posiadać bardzo prostą składnię
- ma przechowywać dane w strukturze drzewiastej
- ma umożliwiać przechowywanie danych w różnych formach
- ma pozwalać na komentowanie zawartości
- ma umożliwiać dzielenie drzewa na mniejsze fragmenty
- ma być bardzo prosty w użyciu
- prosty do stworzenia API
- prosty do obsługi przez API
- ma być uniezależniony od języków programowania i platform programowych
- ma umożliwiać tworzenie i modyfikowanie plików w formie tekstowej w dowolnych edytorach
Pomniejsze założenia opisane są w dalszej części specyfikacji, podczas omawiania konkretnych elementów formatu.
- może — słowo to oznacza, że dane zachowanie jest dopuszczalne, jednak nie jest obowiązkowe.
- należy/zaleca się — oznacza, że dane zachowanie jest wskazane i proponowane, ale nie jest bezwzględnym wymogiem.
- musi — oznacza, że opisywane zachowanie jest bezwzględnym wymogiem, a każde odstępstwo jest niedozwolone.
status dokumentu
Copyright © Jarosław Baran, furious programming 2015—2018. All rights reserved.
Dokument ten zawiera oficjalną specyfikację formatu TreeStructInfo w wersji 2.0 — może być dowolnie kopiowany i udostępniany. Jedynym warunkiem rozpowszechniania kopii specyfikacji jest jej oryginalna forma (niezmieniona treść).
Ostatnia aktualizacja: 8 lutego 2018.
spis treści
1. przykładowy plik
:: to jest przykładowy plik tekstowy TreeStructInfo :: :: możesz komentować dowolne elementy drzewa, tworząc :: komentarze jednoliniowe lub wieloliniowe treestructinfo "2.0" name "Sample Tree" :: trochę informacji o autorze node Owner :: tak, elementy mogą mieć wieloczłonowe nazwy attr Real Name "Jarosław Baran" attr Known As "furious programming" :: dane jako data i czas mogą mieć dowolną formę attr DoB "poniedziałek, 24.10.2011, godzina 19:20" attr Profile "http://4programmers.net/Profile/49548" end node :: dane typów prostych node Data Types :: wartości logiczne — możliwe różne łańcuchy node Boolean attr First "True" attr Turned "Off" end node :: liczby całkowite, zmiennoprzecinkowe i waluta node Numbers :: system heksadecymalny, oktalny, binarny? czemu nie? attr Integer "0xC0FFEE" attr Float "3,1415926535" attr Cigarettes Price "12,80 zł" end node :: znaki i łańcuchy znaków node Characters :: pojedynczy znak lub ciąg znaków attr Char Value "?" attr Single String "Informácie o stromová štruktúra" :: lub wieloliniowa wartość — wydzielamy atrybut z ciała drzewa ref attr Multiline String end node :: inne typy danych — definiujemy węzeł poza ciałem drzewa ref node Other Data Types end node end tree :: wieloliniowy łańcuch znaków :: żadnych terminatorów, bo po co komplikować? ref attr Multiline String "Tree Structure Information" "format tekstowych i binarnych plików konfiguracyjnych" :: inne typy danych ref node Other Data Types :: współrzędne punktu, rozdzielczość ekranu itp. attr Resolution "0o2000,0o1400" :: dane binarne — znów możemy wydzielić ciało węzła, czemu by tego zabraniać? ref node Binary Buffers end ref node :: zawartość strumieni lub dowolnych innych buforów danych ref node Binary Buffers :: można referencjonować bez końca — bo po co ograniczać? ref attr Some Stream Data ref attr Any Buffer Data end ref node :: jakiś strumień danych binarnych ref attr Some Stream Data "54726565537472756374496E666F202D" "20666F726D61742074656B73746F7779" "636820692062696E61726E7963682070" :: lub zawartość dowolnego bufora binarnego :: liczba bajtów w jednej linii wartości jest dowolna — bo po co ją ustalać? ref attr Any Buffer Data "F8D1470F126C16F074EFC8379DBEF08D8F83199F216C5053BAC8970CA829A7A8" "0F5821EA9DE0E5DC207FFC27F6EC8DEA2E5DFD32AFC32D4ED57B823CF6E93B52" "622D033FFFE76EB24D"
Aby zobaczyć zawartość innego tekstowego pliku konfiguracyjnego TreeStructInfo — przejdź do działu z mapą strony.
2. forma tekstowa
Tekstowa forma plików konfiguracyjnych służy przede wszystkim do łatwego wglądu na zgromadzone w plikach dane, a także do ich łatwej modyfikacji, za pomocą dowolnych edytorów tekstowych. Dzięki składni opartej na słowach kluczowych oraz możliwości komentowania wszystkich elementów drzewa, struktura tekstowych plików konfiguracyjnych staje się przyjazna dla człowieka.
Pliki w formie tekstowej dają wiele korzyści, m.in. czytelną dla człowieka strukturę danych oraz prostotę analizy i modyfikacji konfiguracji. Jednak w przeciwieństwie do formy binarnej, zawierają prócz faktycznych danych dużą ilość danych dodatkowych, takich jak słowa kluczowe, wcięcia czy puste linie. Objętość danych dodatkowych zależy głównie od struktury drzewa — im więcej poziomów zagłębienia, tym większe wcięcia, im więcej elementów referencjonowanych, tym więcej pustych linii, itd.
Tekstowe pliki konfiguracyjne TreeStructInfo przeznaczone są dla otwartych konfiguracji, dając użytkownikom możliwość ręcznej modyfikacji ich zawartości, spychając na dalszy plan szybkość ładowania plików do pamięci i zapisu drzew z pamięci do plików. Natomiast jeśli szybkość ładowania i zapisu plików ma większą wagę niż możliwość ich ręcznej edycji (np. przy długich plikach, zawierających tysiące elementów), lepszym rozwiązaniem może się okazać zastosowanie formy binarnej.
Tekstowe pliki konfiguracyjne kodowane są w UTF-8.
2.1. składnia plików tekstowych
Składnia tekstowych plików konfiguracyjnych opiera się na niedużej liczbie słów i fraz kluczowych, w stylu zaczerpniętym z takich języków jak Object Pascal oraz Visual Basic. Każdy element drzewa opisywany jest przez inny zestaw słów i/lub fraz kluczowych, dzięki czemu rozróżnienie danych elementów nie stanowi najmniejszego problemu.
2.1.1. słowa i frazy kluczowe
Poniżej znajduje się lista wszystkich słów i fraz kluczowych, opisujących składnię tekstowych plików TreeStructInfo:
treestructinfo :: zapoczątkowuje nagłówek drzewa name :: stoi przed nazwą drzewa w jego nagłówku end tree :: fraza zakańczająca główne ciało drzewa attr :: oznacza deklarację standardowego atrybutu node :: oznacza nagłówek deklaracji standardowego węzła potomnego end node :: oznacza zakończenie ciała standardowego węzła potomnego ref attr :: oznacza deklarację oraz definicję referencjonowanego atrybutu ref node :: oznacza deklarację lub nagłówek ciała definicji referencjonowanego węzła potomnego end ref node :: oznacza zakończenie ciała definicji referencjonowanego węzła potomnego
Wszelkie słowa i frazy kluczowe składają się jedynie z małych liter, przy czym człony we frazach kluczowych rozdzielone są pojedynczymi znakami 0x20. Do opisu składni tekstowych plików konfiguracyjnych, wykorzystywana jest także specjalna wartość:
"2.0" :: wartość w nagłówku drzewa, określająca wersję 2.0 formatu
nieduża liczba zarezerwowanych znaków specjalnych:
" :: znak otwierający i zamykający wszelkie wartości , :: separator współrzędnych punktów lub części dziesiętnej w liczbach zmiennoprzecinkowych #9 :: zarezerwowany znak dla pojedynczej pustej linii jako wieloliniowej wartości atrybutu
oraz jeden ciąg znaków, pełniący funkcję słowa kluczowego, jednak składający się wyłącznie ze znaków specjalnych:
:: :: prefiks poprzedzający wartość komentarza
2.1.2. wcięcia
Rozmiar pojedynczego wcięcia to domyślnie dwa znaki o kodzie 0x20, jednak może się ono składać także ze znaków tabulatora (znaków o kodzie 0x09). Wcięcia nie są obowiązkowe, jednak należy je stosować, aby drzewiasta struktura konfiguracji była widoczna.
Forma tekstowa dopuszcza także wstawianie dowolnej liczby pustych linii, służących do formatowania zawartości.
2.1.3. budowa pliku
Oprócz wyżej wymienionych cech, tekstowe pliki TreeStructInfo charakteryzują się także budową liniową. Oznacza to, że w jednej linii musi być zawarta tylko jedna, konkretna i kompletna informacja:
- nagłówek drzewa (w formie skróconej lub pełnej)
- fraza kluczowa zakańczająca główne ciało drzewa
- nagłówek deklaracji standardowego atrybutu
- nagłówek deklaracji standardowego węzła potomnego
- fraza kluczowa zakańczająca ciało standardowego węzła potomnego
- nagłówek deklaracji referencjonowanego atrybutu
- nagłówek definicji referencjonowanego atrybutu
- nagłówek deklaracji referencjonowanego węzła potomnego
- fraza kluczowa zakańczająca definicję referencjonowanego węzła potomnego
- pojedyncza wartość atrybutu (w przypadku wielu wartości lub wieloliniowej wartości atrybutu)
- komentarz (jednoliniowy lub pojedyncza linia wieloliniowego komentarza)
- pusta linia (służąca do formatowania zawartości)
Niedozwolone jest rozdzielenie pojedynczej informacji (np. deklaracji standardowego atrybutu) na kilka linii.
2.2. identyfikatory
Pod pojęciem identyfikatorów należy rozumieć nazwy wszelkich elementów drzewa. Swoje nazwy muszą posiadać wszystkie atrybuty oraz węzły potomne. Identyfikatorem jest także opcjonalna nazwa drzewa, mogąca znajdować się w otwierającym ciało drzewa nagłówku.
Identyfikatory elementów mogą być praktycznie dowolne — minimalna ich długość to jeden znak, maksymalna nie jest określona. Mogą być wieloczłonowe, gdzie poszczególne człony mogą być oddzielone znakami o kodzie 0x20. Nazwy elementów mogą także zawierać znaki specjalne, jednak nie zaleca się ich używania, z racji obniżenia czytelności zawartości pliku.
Poniżej znajduje się lista niedozwolonych znaków do użycia w identyfikatorach:
0x00 .. 0x1F :: zbiór znaków kontrolnych, nie posiadających graficznej reprezentacji \ :: znak separatora składowych ścieżek dostępu do elementów " :: znak otwierający i zamykający wszelkie wartości ~ :: znak określający (w ścieżce dostępu) odwołanie do bieżącego węzła
Częściowo zarezerwowanym znakiem jest symbol ~. Wykorzystywany jest w ścieżkach dostępu do określenia bieżącej ścieżki węzła. Łańcuch znaków zawierający tylko jeden taki znak lub składający się z samych znaków kontrolnych jest niepoprawnym identyfikatorem.
Wszelkie znaki specjalne oraz cyfry mogą być użyte w nazewnictwie elementów drzewa oraz samego drzewa. Poniższa lista zawiera przykładowe poprawne i niepoprawne identyfikatory:
:: poprawne: X :: pojedynczy znak Name :: pojedyncze słowo Element Name :: człony oddzielone kilkoma białymi znakami Milk & Nuts :: dozwolone jest użycie znaku & 1024:768 :: zarówno cyfry, jak i znak dwukropka są dozwolone Żółwiątko :: znaki diakrytyczne także są dopuszczalne ...?! :: wykorzystane znaki specjalne są dozwolone
:: niepoprawne: C:\File.ext :: zawiera niedozwolony znak \, zarezerwowany dla ścieżek dostępu Foo "Bald" Bar :: zawiera niedozwolony znak ", zarezerwowany dla wszelkich wartości :: identyfikator nie może składać się wyłącznie z białych znaków
2.3. rama drzewa
Ramą drzewa określa się dwie linie — otwierającą oraz zamykającą główne ciało drzewa. Linia otwierająca nazywana jest nagłówkiem drzewa i może występować w pliku w tylko jednym, ściśle określonym miejscu. Nagłówek drzewa może być zapisany w dwóch formach oraz musi zawierać zestaw określonych słów kluczowych i specjalnych wartości.
Podstawowa deklaracja nagłówka drzewa składa się ze słowa kluczowego treestructinfo oraz numeru wersji formatu (ciągu 2.0), objętym znakami cudzysłowu — całość nie powinna zawierać wcięcia:
treestructinfo "2.0"
Nagłówek w formie rozszerzonej może dodatkowo posiadać nazwę drzewa, która nie musi być unikalna, nawet w skali całego pliku:
treestructinfo "2.0" name "Name of Tree"
W takim przypadku, po numerze wersji formatu musi występować słowo kluczowe name, a po nim w znakach cudzysłowu nazwa drzewa. Należy pamiętać, że nazwa drzewa powinna być zgodna z zasadami tworzenia identyfikatorów. Jeśli drzewo nie posiada nazwy, powinno się skorzystać z podstawowej formy nagłówka. Podanie pustego identyfikatora jest dopuszczalne, jednak zbyteczne.
Linia zakańczająca ciało drzewa musi zawierać jedynie frazę kluczową end tree, która także nie powinna być poprzedzona wcięciem:
end tree
Fraza ta musi się składać z wyżej wymienionych członów, rozdzielonych tylko jednym znakiem 0x20. Najkrótszy tekstowy plik TreeStructInfo zawiera jedynie linię nagłówka drzewa oraz linię zakańczającą ciało drzewa:
treestructinfo "2.0" end tree
Plik posiadający mniejszą liczbę linii lub mniejszą ilość informacji w odpowiednich liniach jest niepoprawny według specyfikacji.
2.4. podstawowe elementy drzewa
Do grona podstawowych elementów, z których mogą być budowane drzewa, zaliczają się standardowe i referencjonowane atrybuty, służące do przechowywania konkretnych danych, a także standardowe i referencjonowane węzły potomne, umożliwiające grupowanie zawartości tworzącej drzewiastą strukturę.
Dodatkowym elementem jest główny węzeł drzewa — każde drzewo posiada taki węzeł, przy czym nie jest on w żaden sposób opisywany — nie posiada swojej deklaracji ani identyfikatora. Rolą głównego węzła jest przechowywanie wszelkich elementów zerowego poziomu zagłębienia, czyli elementów zawartych bezpośrednio w ramie drzewa.
Do podstawowych elementów nie zalicza się natomiast komentarzy, dlatego że są one opcjonalną i jednocześnie integralną częścią komentowanych elementów, stąd nie mogą istnieć samodzielnie. Zasada ta dotyczy zarówno podstawowych elementów drzewa, jak i samego drzewa, które także może posiadać swój komentarz.
2.4.1. atrybuty
Atrybuty służą do przechowywania konkretnych danych określonego typu. Dzielą się na standardowe, posiadające deklarację i definicję w tym samym miejscu drzewa, a także referencjonowane, których deklaracja określa ich miejsce w drzewie, jednak zdefiniowane są poza jego głównym ciałem. Mogą zawierać wartości puste, jednoliniowe lub wieloliniowe, sformatowane w odpowiedni sposób.
2.4.1.1. deklaracja atrybutów
Linia deklaracji standardowego atrybutu musi zawierać słowo kluczowe attr, następnie identyfikator atrybutu oraz jego wartość w znakach cudzysłowu. Słowo kluczowe musi być oddzielone od identyfikatora co najmniej jednym białym znakiem. Nazwa atrybutu może być odseparowana od wartości białymi znakami, ale nie musi. Niemniej jednak zaleca się oddzielanie składowych deklaracji atrybutu pojedynczym znakiem 0x20.
Deklaracja standardowego atrybutu powinna zawierać poprzedzające słowo kluczowe wcięcie, uzależnione od poziomu jego zagłębienia. Jeśli dany atrybut znajduje się w głównym węźle drzewa, powinien zawierać pojedyncze wcięcie. Przy kolejnych poziomach zagłębienia, wcięcie powinno być odpowiednio zwiększane.
Najprostsza postać deklaracji standardowego atrybutu zawiera odpowiednie słowo kluczowe, identyfikator oraz pustą wartość:
attr Name ""
Atrybuty mogą także posiadać wieloczłonowe identyfikatory, zawierające dowolne znaki (z wyjątkiem tych zarezerwowanych):
attr This Is a Very Long Attribute Name ""
Jeśli identyfikator atrybutu jest wieloczłonowy, białe znaki stojące przed i po nim nie należą do ciągu identyfikatora. Dlatego też w powyższym przykładzie, nazwą atrybutu jest This Is a Very Long Attribute Name.
2.4.1.2. wartości atrybutów
Każda deklaracja standardowego atrybutu lub definicja atrybutu referencjonowanego musi zawierać wartość, umieszczoną na końcu linii deklaracji lub definicji w znakach cudzysłowu. Wartość ta może zawierać dowolne znaki, łącznie ze znakami cudzysłowu. Z racji tej, że wartość atrybutu zawarta jest na końcu linii jego deklaracji lub definicji, rozpoczyna się po pierwszym znaku cudzysłowu, a kończy przed ostatnim cudzysłowem.
Jeśli atrybut zawiera pustą wartość, na końcu deklaracji atrybutu muszą się znajdować dwa znaki cudzysłowu:
attr Name ""
W przypadku każdej wartości jednoliniowej, musi ona być zapisana tak samo w znakach cudzysłowu, po identyfikatorze atrybutu:
attr Name "Simple Attribute Value"
Każdy atrybut może także posiadać wartość wieloliniową lub kilka wartości. Zapis takich wartości jest uniwersalny, dokładnie taki sam w obu przypadkach. Pierwsza linia wartości lub pierwsza wartość musi być zapisana w taki sam sposób jak wartość jednoliniowa, natomiast każda kolejna wartość lub linia wartości musi być zapisana w kolejnych liniach w znakach cudzysłowu. Wartości powinno poprzedzać stosowne wcięcie, wyrównujące znaki cudzysłowu, które otwierają ciągi wartości.
Poniżej przykładowy zapis atrybutu zawierającego wartość wieloliniową lub kilka wartości:
attr Name "First Value (Line)" "Second Value (Line)" "" "Last Value (Line)"
Poszczególne kolejne (linie) wartości mogą także być puste, co widać w powyższym zapisie. Jednak każda kolejna wartość lub kolejna linia wartości musi być zapisana w osobnej linii, a odstępstwo od tej reguły jest niedozwolone.
2.4.1.3. typy danych wartości
Atrybuty mogą zawierać dane wielu typów, zapisane w wielu z możliwych postaci. Mogą posiadać dane typów prostych, takich jak wartości logiczne, liczby całkowite, stałoprzecinkowe i zmiennoprzecinkowe; dane typów znakowych, takich jak pojedyncze znaki oraz ciągi znaków; a także dane typów takich jak data i czas czy współrzędne punktów. Istnieje także możliwość przechowywania danych binarnych, w postaci map heksadecymalnych.
Dodatkowo istnieje możliwość zapisu danych typu bliżej nieokreślonego, w postaci wartości wieloliniowych.
2.4.1.3.1. wartości logiczne
Wartości logiczne mogą być zapisane na wiele różnych sposobów. Oprócz standardowych wartości True i False, wykorzystywane mogą być także inne ciągi znaków, takie jak Yes i No czy On i Off. Dozwolone są także wartości znakowe, np. T i F, a także cyfry 1 lub 0.
Pełna lista dopuszczalnych ciągów znaków lub pojedynczych znaków dla wartości logicznych:
"True" "Yes" "On" "T" "Y" "1" :: prawda "False" "No" "Off" "F" "N" "0" :: fałsz
Zachowanie zgodnej wielkości liter z powyższymi łańcuchami lub wartościami znakowymi nie jest wymagane, jednak zaleca się stosowanie wielkich liter dla wartości znakowych i zapisu z wielkiej litery wartości łańcuchowych.
W przypadku wartości liczbowych, niedozwolone jest wykorzystanie cyfr innych, niż wymienione.
2.4.1.3.2. liczby całkowite
Wartości całkowitoliczbowe mogą być zapisywane w najpopularniejszych systemach liczbowych, do których należą: system decymalny, heksadecymalny, oktalny oraz binarny. W przypadku liczb całkowitych, zapisanych w systemach innych niż dziesiętny, przed ich wartością musi znajdować się podciąg znaków, zawierający prefiks danego systemu liczbowego w postaci uniwersalnej:
- 0x — prefiks liczb heksadecymalnych
- 0o — prefiks liczb oktalnych
- 0b — prefiks liczb binarnych
Liczby zapisane we wszystkich wymienionych systemach liczbowych mogą być poprzedzone znakiem + lub -. W przypadku liczb zapisanych w systemach innych niż decymalny, znak + lub - musi się znajdować przed prefiksem określającym system liczbowy.
Poniżej znajdują się przykłady zapisu kilku liczb całkowitych, we wszystkich obsługiwanych systemach liczbowych:
:: liczba 64206: "64206" lub "+64206" :: system decymalny "0xFACE" lub "+OxFACE" :: system heksadecymalny "0o175316" lub "+0o175316" :: system oktalny "0b1111101011001110" lub "+0b1111101011001110" :: system binarny
:: liczba -2989: "-2989" :: system decymalny "-0xBAD" :: system heksadecymalny "-0o5655" :: system oktalny "-0b101110101101" :: system binarny
:: liczba 0: "0" :: system decymalny "0x00" :: system heksadecymalny "0o00" :: system oktalny "0b0000" :: system binarny
W przypadku zapisu liczby w systemie innym niż decymalny, liczba znaków stojących po prefiksie systemu nie musi być zgodna z powyższym zapisem. Zaleca się stosowanie dwóch znaków dla systemów heksadecymalnego i oktalnego, oraz czterech dla systemu binarnego. Nie zmienia to faktu, że dopuszczalne jest użycie tylko jednego znaku, np. 0b1 zamiast 0b0001.
Format zapisu liczb we wszystkich systemach jest ściśle określony, a każde odstępstwo od wymienionych reguł jest niedozwolone.
2.4.1.3.3. liczby zmiennoprzecinkowe
Liczby zmiennoprzecinkowe mogą być zapisane w dwóch różnych formach — w formie uniwersalnej (notacji dziesiętnej) lub w notacji naukowej, a same liczby mogą być poprzedzone znakami + lub -. Dodatkowo istnieje możliwość zapisania specjalnych liczb zmiennoprzecinkowych w postaci określonych ciągów znaków, takich jak wartość nieskończoności lub nie-liczby.
Poniżej przykłady zapisu kilku losowych liczb:
:: liczba 1009.1989: "1009,1989" lub "+1009,1989" :: notacja dziesiętna "1,0091989E3" lub "+1,0091989E+03" :: notacja naukowa
:: liczba -1009.1989: "-1009,1989" :: notacja dziesiętna "-1,0091989E3" lub "-1,0091989E+03" :: notacja naukowa
:: liczba 0: "0" lub "0,0000" :: notacja dziesiętna "0E0" lub "0,0E0" lub "0,00E+00" :: notacja naukowa
Znakiem separatora dziesiętnego nie musi być znak ,. Jest on uzależniony głównie od ustawień lokalizacyjnych, dlatego też separatorem części dziesiętnej może być inny znak, np. ..
Istnieje także możliwość zapisu liczb specjalnych w postaci ciągów znaków, takich jak wartość nieskończoności dodatniej lub ujemnej oraz wartość tzw. nie-liczby. Poniżej znajduje się lista sposobów zapisu takich wartości:
"Inf" lub "+Inf" :: nieskończoność dodatnia "-Inf" :: nieskończoność ujemna "Nan" :: nie-liczba
Zachowanie zgodnej wielkości liter z powyższymi ciągami znaków nie jest obowiązkowe, jednak zalecane. Inne sposoby prezentacji zarówno wartości specjalnych, jak i standardowych liczb zmiennoprzecinkowych nie są dozwolone.
2.4.1.3.4. waluta
Wartości walutowe (czyli liczby stałoprzecinkowe) posiadają odrębne sposoby zapisu. Waluta może zostać zapisana z dowolną precyzją (maksymalnie cztery cyfry po separatorze dziesiętnym), po której musi występować nazwa lub symbol waluty (np. zł czy $). Nazwa waluty musi się znajdować po kwocie, z odstępem co najmniej jednego znaku o kodzie 0x20. Kwota może być poprzedzona znakiem + lub -.
Poniżej przykłady zapisu kwot w dozwolonych formach:
:: liczba 4,1784: "4 zł" lub "+4 zł" :: kwota pełna "4,18 zł" lub "+4,18 zł" :: format cenowy "4,1784 zł" lub "+4,1784 zł" :: format giełdowy
:: liczba -3,0350: "-3 $" :: kwota pełna "-3,04 $" :: format cenowy "-3,0350 $" :: format giełdowy
:: liczba 0: "0 ¥" :: kwota pełna "0,00 ¥" :: format cenowy "0,0000 ¥" :: format giełdowy
Podobnie jak w przypadku liczb zmiennoprzecinkowych, znak separatora dziesiętnego może być inny, odpowiedni według danej lokalizacji. Natomiast liczba cyfr po znaku separatora nie może być większa niż cztery.
2.4.1.3.5. ciągi znaków
Łańcuchy znaków mogą zostać zapisane w sposób dwojaki — jako pojedynczy łańcuch wartości, lub jako wieloliniowy ciąg znaków. Jedynym ograniczeniem jest niemożność użycia znaków kontrolnych i znaków zarezerwowanych (które muszą być escapowane, w sposób dowolny, nienaruszający strukturę danych). Ciągi mogą być puste, a w przypadku wieloliniowych łańcuchów, także ich niektóre lub wszystkie składowe mogą być puste. Łańcuchy mogą zawierać dowolną liczbę znaków cudzysłowu, które nie muszą być escapowane.
Poniżej znajduje się lista przykładowych jednoliniowych i wieloliniowych łańcuchów znaków:
:: łańcuchy jednoliniowe: "" :: pusty ciąg znaków " " :: łańcuch składający się wyłącznie ze białych znaków "Simple Value" :: tekst wieloczłonowy " TreeStructInfo " :: ciąg poprzedzony i zakończony znakami spacji " "32" "64" "128" " :: łańcuch zawierający znaki cudzysłowu
:: łańcuchy wieloliniowe: "" "" :: wieloliniowy ciąg znaków, składający się z dwóch pustych podciągów "" "TreeStructInfo" "" :: wieloliniowy łańcuch, zawierający w sobie puste podciągi "Tree" "Structure" "Information" :: łańcuch wieloliniowy, zawierający trzy słowa
Zasada zapisu wieloliniowych łańcuchów znaków jest taka sama jak innych wieloliniowych wartości. Poszczególne podciągi mogą być zapisane w dokładnie taki sam sposób jak proste, jednoliniowe łańcuchy (jako jedna linia wartości), używając wybranego znaku lub sekwencji znaków jako separatora linii. Wszelkie nieostatnie podciągi wartości nie są zakańczane żadnymi znakami terminatora.
2.4.1.3.6. data i czas
Zapis wartości określających datę i czas jest mocno elastyczny. Format daty i czasu nie jest ściśle określony, stąd kolejność składowych daty i/lub czasu jest dowolna. Numer roku może zostać zapisany na dwa sposoby — w formacie pełnym (czterocyfrowym) lub skróconym (dwucyfrowym). Do zapisu numeru godziny należy użyć jednego z dwóch formatów — 24-godzinnego lub 12-godzinnego. W przypadku użycia formatu 12-godzinnego, w łańcuchu wartości (w dowolnym jego miejscu) musi się znajdować znak lub sekwencja znaków, określająca porę dnia, czyli np. am lub pm.
Istnieje także możliwość zapisu nazwy dnia lub nazwy miesiąca w formie skróconej lub pełnej, przy czym nazwa miesiąca może zastępować jego numer. Aby data była uznana za pełną, dozwolone jest podanie numerów dnia i roku, a zamiast numeru miesiąca jego pełną lub skróconą nazwę.
Łańcuchy wartości daty i/lub czasu mogą zawierać dodatkowe podciągi, niebędące składowymi daty i czasu. Mogą znajdować się w dowolnych miejscach łańcucha wartości i zawierać praktycznie dowolne znaki, z wyjątkiem znaków kontrolnych lub innych, mogących naruszyć strukturę drzewa w pliku.
Poniżej przykłady kilku dat i/lub czasów w dozwolonych formach zapisu:
:: data: "24-10-11" :: data w formie skróconej, dwucyfrowy format roku "24-10-2011" :: data w formie skróconej, czterocyfrowy format roku "24 paź 2011" :: data w dłuższej formie, skrócona nazwa miesiąca "24 października 2011" :: data w formie długiej, pełna nazwa miesiąca
:: czas: "19:20" :: czas w formie krótkiej, liczba godzin i minut "19:20:04" :: czas w formie dłuższej, liczba godzin, minut i sekund "19:20:04:127" :: czas w długiej formie, wszystkie składowe czasu "07:20 PM" :: czas w formie krótkiej, 12-godzinny format zegara
:: data i czas: "24.10.2011 19:20" :: data i czas w formie skróconej "24 october 2011, 19:20" :: data i czas w formie dłuższej, pełna nazwa miesiąca "monday, 24.10.2011 (19:20)" :: data i czas w formie długiej, pełna nazwa dnia tygodnia "monday, 24 mon 2011 (07:20 PM)" :: data i czas w formie długiej, pełna nazwa dnia tygodnia, krótka nazwa miesiąca i 12-godzinny format zegara
Możliwe jest także wstawienie dodatkowych podciągów, niebędących składowymi daty i czasu, np.:
"dziś jest poniedziałek, 24-10-2011, godzina 19:20" :: rozszerzona wersja daty i czasu, z dodatkowymi podciągami
2.4.1.3.7. współrzędne punktów
Zasady zapisu współrzędnych punktów są praktycznie takie same jak w przypadku liczb całkowitych. Jedyną różnicą są dwie liczby, które muszą być oddzielone od siebie separatorem ,. Tak samo jak w przypadku wartości całkowitoliczbowych, pojedyncze koordynaty mogą być zapisane w jednym z czterech systemów liczbowych — decymalnym, heksadecymalnym, oktalnym lub binarnym. Mogą być poprzedzone znakiem + lub -.
Współrzędne w łańcuchu wartości muszą być rozdzielone separatorem, bezpośrednio przylegającym do nich. Oznacza to, że zarówno po lewej jak i po prawej stronie separatora, nie mogą się znajdować białe znaki.
Poniżej znajduje się lista przykładowych współrzędnych punktu, zapisanych na różne dopuszczalne sposoby:
:: współrzędne 163,141: "163,141" lub "+163,+141" :: współrzędne w systemie decymalnym "0xA3,0x8D" lub "+0xA3,+0x8D" :: współrzędne w systemie heksadecymalnym "0o243,0o215" lub "+0o243,+0o215" :: współrzędne w systemie oktalnym "0b10100011,0b10001101" lub "+0b10100011,+0b10001101" :: współrzędne w systemie binarnym
:: współrzędne -94,-75: "-94,-75" :: współrzędne w systemie decymalnym "-0x5E,-0x4B" :: współrzędne w systemie heksadecymalnym "-0o136,-0o113" :: współrzędne w systemie oktalnym "-0b1011110,-0b1001011" :: współrzędne w systemie binarnym
:: współrzędne 0,0: "0,0" :: współrzędne w systemie decymalnym "0x00,0x00" :: współrzędne w systemie heksadecymalnym "0o00,0o00" :: współrzędne w systemie oktalnym "0b0000,0b0000" :: współrzędne w systemie binarnym
Tak samo jak w przypadku zapisu pojedynczych liczb całkowitych, minimalna liczba znaków stojących po prefiksie systemu liczbowego nie musi zgodna z powyższym zapisem. Jednak zaleca się stosowanie minimum dwóch znaków dla systemów heksadecymalnego i oktalnego, oraz czterech znaków dla systemu binarnego.
Do zapisu współrzędnych punktów zaleca się używania tego samego systemu liczbowego dla obu współrzędnych. Jednak dozwolony jest ich zapis w różnych systemach, np. zapis współrzędnej X w systemie heksadecymalnym, a współrzędnej Y w oktalnym.
2.4.1.3.8. dane binarne
Format TreeStructInfo umożliwia zapis danych dowolnego typu pod postacią mapy heksadecymalnej. Dane binarne mogą być opisane za pomocą jednej linii lub wielu linii, w postaci ciągów znaków heksadecymalnych, gdzie każdy bajt danych binarnych zawsze opisuje para znaków szesnastkowych. Łączna liczba znaków wartości binarnej musi być parzysta.
Poniżej różne zapisy przykładowych danych binarnych, jako wartości jednoliniowych i wieloliniowych:
"" :: pusty strumień binarny "54726565537472756374496E666F202D" :: 16 bajtów strumienia, wartość jednoliniowa "5472656553747275" "6374496E666F202D" "20666F726D617420" "706C696BF377206B" "6F6E666967757261" "63796A6E796368" :: 47 bajtów strumienia, wieloliniowa wartość "5472656" "5537472" :: 7 bajtów strumienia, wartość wieloliniowa
2.4.1.3.9. pozostałe typy danych
Kwestia przechowywania w atrybutach danych o niewymienionych typach jest otwarta i nieograniczona. Z racji tej, że serializacja i deserializacja natywnych danych do i z łańcuchów znaków w różnych językach programowania jest odmienna, wartości atrybutów mogą przechowywać praktycznie dowolne dane, pod warunkiem, że będą zapisane w ściśle określony sposób, nie wpływających na liniową budowę pliku oraz drzewiastą strukturę informacji.
2.4.2. węzły
Węzły służą do grupowania elementów oraz do budowy drzewiastej struktury. Dzielą się na standardowe, posiadające deklarację i definicję w tym samym miejscu w drzewie, a także referencjonowane, charakteryzujące się wydzieloną definicją poza główne ciało drzewa, a których miejsce w drzewie określa ich deklaracja. Węzły mogą zawierać dowolną liczbę elementów potomnych, jak również mogą być puste.
Główny węzeł drzewa także jest jego elementem, służącym do grupowania elementów najniższego poziomu zagłębienia. Jednak nie posiada on swojej deklaracji — należące do niego elementy zawarte są bezpośrednio pomiędzy liniami ramy drzewa.
2.4.2.1. deklaracja węzłów
Linia deklaracji standardowego węzła potomnego, otwierającego jego ciało zawiera słowo kluczowe node, po którym musi się znajdować identyfikator węzła. Słowo kluczowe musi być oddzielone od identyfikatora co najmniej jednym znakiem 0x20. Ciało deklaracji standardowego węzła potomnego zamyka linia z frazą kluczową end node.
Deklaracja standardowego węzła powinna być poprzedzona odpowiednim dla danego poziomu zagłębienia wcięciem, takim samym dla linii nagłówka deklaracji i linii zamykającej ciało węzła. Przy kolejnych poziomach zagłębienia, wcięcie powinno być odpowiednio zwiększane o jeden poziom.
Deklaracja pustego węzła potomnego zawiera dwie linie — nagłówek ciała węzła oraz linię zamykającą jego ciało:
node Name end node
Tak samo jak atrybuty, węzły potomne mogą posiadać wieloczłonowe identyfikatory:
node This Is a Very Long Node Name end node
Wszelkie białe znaki stojące przed i po identyfikatorze do niego nie należą.
2.4.2.2. zawartość węzłów
Zawartość każdego niepustego węzła potomnego musi być zapisana pomiędzy linią jego nagłówka, a linią zamykającą ciało węzła. Elementy potomne danego węzła powinny posiadać wcięcie o jeden poziom większe niż linie otwierająca i zamykająca ciało węzła.
Poniżej zapis przykładowego węzła, zawierającego kilka atrybutów:
node Some Numbers attr Integer "0xFACE" attr Float "3,14" attr Currency "12,80 zł" end node
Jeżeli dany węzeł zawiera własne węzły potomne, powinny być zapisane z odpowiednio powiększonym wcięciem:
node First node Second end node node Third node Fourth end node end node end node
2.4.2.3. kolejność elementów w węzłach
Wszystkie elementy znajdujące się w drzewie muszą być zapisane w określonej kolejności, według rodzajów elementów. Najpierw zapisywane są wszystkie atrybuty należące do danego węzła, a po nich wszystkie węzły potomne.
Przykładowe drzewo ilustrujące wymaganą kolejność elementów:
treestructinfo "2.0" name "Order of Elements" :: wszystkie atrybuty attr Foo "Value" attr Bar "Value" :: wszystkie węzły potomne node First :: wszystkie atrybuty attr Foo "Value" attr Bar "Value" :: wszystkie węzły potomne node Second :: wszystkie atrybuty attr Foo "Value" attr Bar "Value" end node node Third end node end node node Fourth :: wszystkie atrybuty attr Foo "Value" attr Bar "Value" :: wszystkie węzły potomne node Fifth :: wszystkie atrybuty attr Foo "Value" attr Bar "Value" end node end node end tree
Jeżeli dany węzeł posiada elementy tego samego typu, różniące się stanem referencjonowania, nie jest wymagane ich segregowanie. Czyli dla przykładu zapis w pierwszej kolejności atrybutów standardowych, a następnie listy deklaracji atrybutów referencjonowanych nie jest obowiązkiem.
2.5. elementy referencjonowane
Elementy referencjonowane pełnią dokładnie taką samą rolę jak elementy standardowe. W skład elementów mogących posiadać postać referencjonowaną wchodzą atrybuty oraz węzły potomne.
Referencjonowane elementy od standardowych odróżnia jedynie sposób zapisu. Każdy taki element posiada swoją deklarację, określającą jego umiejscowienie w drzewie, a także definicję, zawierającą już właściwe jego ciało. Do zapisu zarówno ich deklaracji jak i definicji wykorzystuje się osobne frazy kluczowe, zawierające prefiksy ref.
Referencjonowanie elementów przeznaczone jest głównie do zwiększenia czytelności plików (tylko w formie tekstowej), poprzez możliwość wydzielania definicji elementów poza główne ciało drzewa. W każdym drzewie możliwe jest stworzenie teoretycznie dowolnej liczby takich elementów, jednak kolejność zapisu ich definicji jest ściśle określona, aby możliwe było prawidłowe ich przypisanie do właściwych deklaracji.
2.5.1. referencjonowane atrybuty
Atrybuty referencjonowane służą do tego samego celu co standardowe atrybuty, jednak różni je sposób zapisu. Atrybuty te posiadają swoje deklaracje, informujące o ich umiejscowieniu w strukturze drzewa, a także definicje, zawierające dodatkowo ich wartości. Ponadto, referencjonowane atrybuty mogą posiadać dwa komentarze — jeden dla deklaracji i jeden dla definicji.
Główną zaletą stosowania referencjonowanych atrybutów jest zwiększenie czytelności plików konfiguracyjnych w formie tekstowej. Dzięki temu atrybuty posiadające np. bardzo długie wieloliniowe wartości, nie będą zaciemniać struktury drzewa.
2.5.1.1. deklaracja referencjonowanych atrybutów
Linia deklaracji referencjonowanego atrybutu posiada frazę kluczową ref attr, po której podany musi być jedynie identyfikator. Początkowa fraza kluczowa musi być oddzielona od identyfikatora co najmniej jednym znakiem 0x20. W odróżnieniu od atrybutu standardowego, deklaracja atrybutu referencjonowanego nie zawiera jego wartości. Wartość ta zapisywana jest w definicji atrybutu.
Deklaracja referencjonowanego atrybutu powinna zawierać stosowne wcięcie, uzależnione od poziomu zagłębienia elementu. Atrybuty znajdujące się w głównym węźle drzewa powinny posiadać pojedyncze wcięcie. Przy kolejnych poziomach zagłębienia, wielkość wcięcia powinna być odpowiednio zwiększana.
Poniżej przykładowa deklaracja referencjonowanego atrybutu:
ref attr Name
Referencjonowane atrybuty także mogą posiadać wieloczłonowe identyfikatory:
ref attr This Is a Very Long Referenced Attribute Name
Białe znaki znajdujące się pomiędzy frazą kluczową a identyfikatorem nie należą do ciągu nazwy atrybutu.
2.5.1.2. definicja referencjonowanych atrybutów
Tak samo jak linia deklaracji, pierwsza linia definicji referencjonowanego atrybutu musi zawierać frazę kluczową ref attr. Po niej musi znajdować się oddzielony co najmniej jednym znakiem 0x20 identyfikator, a na końcu pierwsza linia wartości lub pierwsza wartość. Kolejne linie wartości muszą być zapisane dokładnie tak samo jak w przypadku standardowych atrybutów, posiadających wartości wieloliniowe.
Najprostsza postać definicji referencjonowanego atrybutu powinna zawierać frazę kluczową ref attr, następnie dokładnie taki sam identyfikator jak w jego deklaracji oraz pustą wartość — całość bez wcięcia:
ref attr Name ""
Jeżeli dany atrybut posiada wartość wieloliniową, musi ona być zapisana tak samo jak w atrybutach standardowych — każda linia wartości lub kolejna wartość musi być w osobnej linii, objęta w znaki cudzysłowu oraz poprzedzona stosownym wcięciem wyrównującym:
ref attr Name "Referenced" "Attribute" "Value"
2.5.1.3. pełny zapis
Deklaracja referencjonowanego atrybutu służy do określenia jego miejsca w drzewie, natomiast definicja zawiera jego konkretne dane (zdefiniowane ciało atrybutu). Deklaracja może się znajdować w głównym węźle drzewa, w ciele deklaracji standardowego węzła potomnego, a także w ciele definicji węzła referencjonowanego.
Natomiast definicja atrybutu referencjonowanego musi być zapisana poza głównym ciałem drzewa oraz poza ciałem definicji referencjonowanego węzła. Dzięki temu podział drzewa na mniejsze fragmenty jest bardziej widoczny.
Poniżej przykład pełnego zapisu atrybutu referencjonowanego, znajdującego się w głównym węźle drzewa:
treestructinfo "2.0" ref attr Name end tree ref attr Name "Value"
W przypadku, gdy referencjonowany atrybut znajduje się w dowolnym węźle potomnym, zmienia się jedynie miejsce jego deklaracji:
treestructinfo "2.0" node First ref attr Name end node end tree ref attr Name "Value"
Jeżeli w drzewie znajdują się co najmniej dwa elementy referencjonowane, zapis ciał ich definicji jest ściśle określony. Kolejność definicji referencjonowanych elementów uzależniona jest od ich umiejscowienia w drzewie oraz w ciałach definicji referencjonowanych węzłów.
2.5.2. referencjonowane węzły
Referencjonowane węzły służą do tego same celu co standardowe węzły potomne — do grupowania elementów i budowania drzewiastej struktury konfiguracji. Jednak od standardowych węzłów odróżnia je odmienny zapis. Węzły referencjonowane posiadają swoje deklaracje, informujące o ich umiejscowieniu w drzewie, a także definicje, zawierające zdefiniowane ich ciała, wraz z ich zawartością. Ponadto, węzły referencjonowane posiadać mogą dwa komentarze — jeden dla deklaracji i jeden dla definicji.
Główną zaletą stosowania referencjonowanych węzłów jest możliwość zwiększenia czytelności plików konfiguracyjnych w formie tekstowej. Dzięki takiemu zabiegowi, węzły posiadające dużą liczbę elementów potomnych nie będą zaciemniać struktury drzewa, w zamian uwidoczniając fragmentację konfiguracji.
2.5.2.1. deklaracja referencjonowanych węzłów
Linia deklaracji referencjonowanego węzła potomnego posiada frazę kluczową ref node, po której musi znajdować się identyfikator węzła. Początkowa fraza kluczowa musi być oddzielona od nazwy węzła co najmniej jednym znakiem 0x20. Deklaracja referencjonowanego węzła potomnego nie zawiera zdefiniowanego jego ciała.
Deklaracja takiego węzła powinna zawierać stosowne wcięcie, uzależnione od poziomu zagłębienia elementu w drzewie. Elementy znajdujące się w głównym węźle drzewa powinny posiadać pojedyncze wcięcie. Przy kolejnych poziomach zagłębienia, wielkość wcięcia powinna być odpowiednio powiększana.
Poniżej znajduje się przykładowa deklaracja referencjonowanego węzła potomnego:
ref node Name
Węzły referencjonowane (tak samo jak standardowe węzły potomne) mogą posiadać wieloczłonowe identyfikatory:
ref node This Is a Very Long Referenced Node Name
Białe znaki znajdujące się pomiędzy frazą kluczową a nazwą węzła, nie należą do ciągu jego identyfikatora.
2.5.2.2. definicja referencjonowanych węzłów
Tak samo jak linia deklaracji, linia nagłówka definicji referencjonowanego węzła potomnego zawiera frazę kluczową ref node. Po niej musi znajdować się identyfikator, oddzielony co najmniej jednym białym znakiem. Linia nagłówka definicji nie powinna zawierać wcięcia. Ciało definicji referencjonowanego węzła potomnego musi zamykać linia z frazą end ref node.
Definicja pustego węzła referencjonowanego zawiera tylko dwie linie — nagłówek ciała węzła oraz linię zamykającą:
ref node Name end ref node
Jeżeli dany węzeł referencjonowany posiada własne elementy potomne, muszą one być zapisane w taki sam sposób jak zawartość węzłów standardowych, z zalecaną kolejnością elementów:
ref node Some Numbers attr Integer "0xFACE" node Real attr Float "3,14" attr Currency "12,80 zł" end node end ref node
2.5.2.3. pełny zapis
Deklaracja referencjonowanego węzła potomnego służy do określenia jego miejsca w drzewie, natomiast definicja zawiera kompletne jego ciało. Linia deklaracji może się znajdować w głównym węźle drzewa, w ciele deklaracji standardowego węzła potomnego lub w ciele definicji węzła referencjonowanego.
Definicja węzła musi być zapisana poza głównym ciałem drzewa oraz poza definicją referencjonowanego węzła. Dzięki temu podział drzewa na mniejsze części jest bardziej widoczny.
Poniżej przykład pełnego zapisu pustego węzła referencjonowanego, znajdującego się w głównym węźle drzewa:
treestructinfo "2.0" ref node Name end tree ref node Name end ref node
W przypadku gdy referencjonowany węzeł znajduje się w dowolnym węźle potomnym, zmienia się jedynie miejsce jego deklaracji:
treestructinfo "2.0" node First ref node Name end node end tree ref node Name end ref node
Jeżeli w drzewie znajdują się co najmniej dwa elementy referencjonowane, zapis ciał ich definicji jest ściśle określony. Kolejność definicji referencjonowanych elementów uzależniona jest od ich umiejscowienia w drzewie oraz w ciałach definicji referencjonowanych węzłów.
2.5.3. kolejność definicji referencjonowanych elementów
Istnieją dwie zasady dotyczące kolejności zapisu definicji elementów referencjonowanych:
- im wcześniej element zadeklarowany jest w drzewie, tym wcześniej musi być zdefiniowany poza ramą drzewa
- jeżeli w ciele węzła referencjonowanego znajdują się kolejne referencjonowane elementy, ich definicje zapisuje się bezpośrednio pod ciałem tego węzła, zachowując kolejność rekurencyjną
Jeżeli wszystkie elementy referencjonowane znajdują się w głównym węźle drzewa i/lub w węzłach standardowych, kolejność zapisu ich definicji jest dokładnie taka sama jak kolejność ich deklaracji. Poniższy przykład obrazuje zapis definicji wszystkich referencjonowanych elementów drzewa:
treestructinfo "2.0" ref attr Integer node First ref attr Float ref attr Currency node Second ref attr Point end node ref node Third end node end tree ref attr Integer "0xFACE" ref attr Float "3,14" ref attr Currency "12,80 zł" ref attr Point "0o00,0o00" ref node Third end ref node
W przypadku gdy elementy referencjonowane zadeklarowane są także wewnątrz referencjonowanych węzłów potomnych, obowiązuje dodatkowo kolejność rekurencyjna — zawartość węzłów referencjonowanych definiowana jest od razu, pod ich ciałem. Poniższy przykład ilustruje sposób zapisu definicji elementów, znajdujących się także wewnątrz referencjonowanych węzłów:
treestructinfo "2.0" ref attr Integer ref node First ref node Third end tree ref attr Integer "0xFACE" ref node First ref attr Float ref attr Currency ref node Second end ref node ref attr Float "3,14" ref attr Currency "12,80 zł" ref node Second ref attr Point end ref node ref attr Point "0o00,0o00" ref node Third end ref node
W pierwszej kolejności zdefiniowany jest atrybut Integer, w następnej kolejności węzeł First. Z racji tej, że węzeł ten zawiera referencjonowane elementy potomne, zostają one zdefiniowane jako następne. Choć w głównym ciele drzewa następny w kolejności jest węzeł Third, obowiązuje zasada definiowania rekurencyjnego.
Węzeł First także zawiera elementy referencjonowane, więc zostają one zdefiniowane jako następne. Kolejnym referencjonowanym elementem grupującym jest zawarty w nim węzeł Second, stąd definiowany jest jako kolejny. Węzeł ten także zawiera elementy referencjonowane, dlatego też ich definicje zostają zapisane jako następne.
Dopiero na samym końcu, po zdefiniowaniu ciał wszystkich elementów referencjonowanych znajdujących się wewnątrz węzła First, zapisywana jest definicja węzła Third i jego zawartości.
2.6. komentarze
Komentarze są informacjami dodatkowymi, nie wchodzącymi w skład elementów drzewa. Służyć mogą do różnych celów, np. do tworzenia opisów zawartości plików konfiguracyjnych czy opisów konkretnych elementów drzew. Jednak każdy komentarz jest własnością danego elementu drzewa lub samego drzewa i nie może istnieć w pliku samodzielnie.
Komentarze mogą poprzedzać linię nagłówka drzewa, a także nagłówki wszystkich standardowych elementów takich jak atrybuty i węzły potomne. Wszystkie elementy standardowe posiadają jedynie swoje deklaracje, stąd zawierać mogą tylko po jednym komentarzu. Natomiast elementy referencjonowane posiadają swoje deklaracje i definicje, dlatego też posiadać mogą po dwa komentarze — komentarz deklaracji i definicji.
2.6.1. deklaracja komentarzy
Każda linia komentarza musi zawierać prefiks ::, po którym powinna się znajdować treść komentarza. Treść ta może zawierać dowolne znaki (także białe oraz te zarezerwowane dla składni). Prefiks powinien być oddzielony co najmniej jednym znakiem 0x20 od treści komentarza. Białe znaki stojące pomiędzy prefiksem komentarza a jego treścią, nie należą do wartości komentarza.
Linia komentarza powinna zawierać poprzedzające prefiks wcięcie, takie samo jak wcięcie komentowanego elementu. Uzależnione jest ono od typu komentowanego elementu oraz od poziomu jego zagłębienia w drzewie. Główny komentarz drzewa nie powinien go zawierać, dlatego że nagłówek ramy drzewa także go nie posiada. Wcięcia również nie powinny posiadać komentarze definicji referencjonowanych atrybutów oraz komentarze definicji referencjonowanych węzłów.
Pojedyncza linia komentarza musi zawierać prefiks oraz jego treść:
:: this is the single-line comment
W przypadku komentarza wieloliniowego, każda jego linia musi zawierać określony prefiks:
:: this is the multiline comment
:: its second line
:: its third line
:: its fourth line
Linia komentarza może być pusta — w takim przypadku musi zawierać prefiks oraz opcjonalnie wcięcie:
::
Komentarze wieloliniowe również mogą posiadać w sobie puste wartości, które mogą się znajdować w dowolnym jego miejscu:
::
:: this is the multiline comment
::
:: its fourth line
:: its fifth line
:: its sixth line
::
2.6.2. główny komentarz drzewa
Jeśli drzewo ma posiadać główny komentarz, musi on być zapisany na samym początku pliku konfiguracyjnego, ponad linią nagłówka ciała drzewa. Główny komentarz drzewa może być jednoliniowy lub wieloliniowy i zawierać dowolne wartości, także puste. Zaleca się, aby komentarz ten był oddzielony od nagłówka drzewa jedną pustą linią, bez względu na jego długość.
Poniżej przykład zapisu jednoliniowego głównego komentarza drzewa:
:: this is the single-line tree comment treestructinfo "2.0" end tree
oraz komentarza wieloliniowego:
:: this is the multiline tree comment :: :: its third line :: its fourth line treestructinfo "2.0" end tree
2.6.3. komentarze atrybutów
Każdy atrybut może posiadać komentarz, zarówno jednoliniowy jak i wieloliniowy. Standardowe atrybuty mogą posiadać tylko jeden komentarz, natomiast atrybuty referencjonowane mogą posiadać dwa — komentarz deklaracji oraz definicji. W każdym przypadku komentarz musi być zapisany bezpośrednio nad linią nagłówka deklaracji lub definicji. Wszystkie linie komentarzy atrybutów powinny mieć takie samo wcięcie jak komentowane elementy.
Poniżej przykład komentarza deklaracji standardowego atrybutu, umieszczonego w węźle potomnym drzewa:
treestructinfo "2.0" node First :: this is the multiline comment :: of standard attribute declaration attr Integer "0o2000" end node end tree
Jeśli komentowany atrybut zawarty jest w głównym ciele drzewa, nie powinien być poprzedzony pustą linią. W przypadku atrybutów referencjonowanych, oprócz komentarzy deklaracji mogą one także posiadać osobne komentarze definicji:
treestructinfo "2.0" :: this is the multiline comment of :: referenced attribute declaration ref attr Integer end tree :: this is the multiline comment of :: referenced attribute definition ref attr Integer "0o2000"
Komentarz deklaracji referencjonowanego atrybutu nie powinien być poprzedzony pustą linią. Natomiast w przypadku gdy atrybut posiada komentarz definicji, powinien zawierać dwie puste linie — jedną przed komentarzem definicji i jedną po całej definicji elementu:
2.6.4. komentarze węzłów
Każdy węzeł potomny posiadać może jednoliniowy lub wieloliniowy komentarz. Węzły referencjonowane mogą posiadać dwa komentarze — po jednym deklaracji i definicji. We wszystkich przypadkach, komentarze muszą być zapisane bezpośrednio nad liniami nagłówków deklaracji lub definicji. Wszystkie linie komentarzy węzłów powinny mieć takie samo wcięcie jak komentowane elementy.
Poniżej przykład wieloliniowego komentarza deklaracji standardowego węzła, zawartego w głównym węźle drzewa:
treestructinfo "2.0" :: this is the multiline comment :: of standard node declaration node Second end node end tree
Jeżeli komentowany węzeł zawarty jest w głównym węźle drzewa, nie powinien być poprzedzony pustą linią. W przypadku węzłów referencjonowanych, oprócz komentarzy deklaracji mogą także posiadać osobne komentarze definicji:
treestructinfo "2.0" node First :: this is the multiline comment of :: referenced node declaration ref node Second end node end tree :: this is the multiline comment of :: referenced node definition ref node Second end ref node
Komentarz deklaracji referencjonowanego węzła nie powinien być poprzedzony pustą linią. Natomiast jeśli węzeł posiada komentarz definicji, cała definicja powinna być poprzedzona i zakończona pustymi liniami.
2.7. ścieżki dostępu do elementów
Każdy element drzewa (główny jego węzeł również) posiada swoją ścieżkę, określającą jego umiejscowienie w drzewie. Ścieżka jest ciągiem znaków, zawierającym zestaw identyfikatorów rozdzielonych znakami separatora \.
Ścieżki dostępu do elementów mają służyć jedynie bibliotece do obsługi plików TreeStructInfo i nie są zapisywane w plikach.
2.7.1. ścieżki dostępu do atrybutów
Jeżeli atrybut znajduje się w głównym węźle drzewa, jego ścieżka zawiera jedynie jego identyfikator. Natomiast w przypadku gdy atrybut znajduje się wewnątrz dowolnego węzła potomnego, nazwa atrybutu musi być poprzedzona identyfikatorami węzłów, a wszystkie identyfikatory muszą być rozdzielone znakami separatora \.
Bez względu na to, czy dany atrybut jest standardowy czy referencjonowany, ścieżka zawsze wygląda tak samo. Poniżej znajduje się przykładowa zawartość pliku konfiguracyjnego z atrybutami, do których ścieżki dostępu podane są w ich komentarzach:
treestructinfo "2.0" :: Integer attr Integer "0xBADFACE" node First :: First\Float attr Float "3,14" :: First\Currency ref attr Currency end node ref node Second end tree :: First\Currency ref attr Currency "12,80 zł" ref node Second :: Second\Character attr Character "?" node Third :: Second\Third\Point attr Point "0o2000,0o1400" end node end ref node
Ścieżki dostępu do atrybutów nie są zakańczane znakami separatora identyfikatorów.
2.7.2. ścieżki dostępu do węzłów
Jeżeli węzeł potomny znajduje się w głównym węźle drzewa, jego ścieżka dostępu musi zawierać jedynie jego identyfikator oraz znak \. Natomiast jeśli węzeł znajduje się w dowolnym innym węźle potomnym, identyfikator węzła musi być poprzedzony nazwami węzłów, wszystkie identyfikatory muszą być rozdzielone znakami \, a cała ścieżka musi być także tym znakiem zakończona.
Poniżej znajduje się zawartość przykładowego pliku konfiguracyjnego z węzłami, do których ścieżki podane są w ich komentarzach:
treestructinfo "2.0" :: First\ node First :: First\Second\ ref node Second end node :: Fourth\ ref node Fourth end tree :: First\Second\ ref node Second :: First\Second\Third\ node Third end node end ref node :: Fourth\ ref node Fourth :: Fourth\Fifth\ node Fifth :: Fourth\Fifth\Sixth\ node Sixth end node end node end ref node
Ścieżki dostępu do węzłów zawsze zakańczane są znakami separatora identyfikatorów \.
2.8. przetwarzanie plików tekstowych
Przetwarzanie plików konfiguracyjnych TreeStructInfo w formie tekstowej nie jest zadaniem skomplikowanym. Z racji liniowej budowy plików oraz oznaczania konkretnych elementów drzewa i komentarzy specjalnymi słowami i frazami kluczowymi oraz prefiksami, proces przetwarzania źródeł poszczególnych plików nie jest trudny w implementacji.
Elementami nieco utrudniającymi przetwarzanie plików tekstowych są referencjonowane elementy. Jednak poprawną analizę elementów referencjonowanych rozwiązać można dzięki pomocniczym kolekcjom elementów oraz umiejętnemu posługiwaniu się rekursją.
2.8.1. zapis pliku tekstowego
Zapis natywnego drzewa z pamięci do pliku tekstowego odbywa się w kilku głównym krokach. W zapisie drzewa pośredniczy konwerter tekstowy, który posiadając referencję do obiektu drzewa, analizuje go i generuje wyjściowy strumień znaków. Tak przygotowany strumień zawiera kompletne i sformatowane drzewo konfiguracji.
diagram procesu serializacji drzewa do formy tekstowej
W pierwszej kolejności zapisywany jest główny komentarz drzewa, jeśli jest zdefiniowany. Następnie zapisywana jest linia nagłówka drzewa z wersją formatu, w formie skróconej lub pełnej. Forma pełna używana jest tylko w przypadku, gdy drzewo posiada zdefiniowany identyfikator. Linia ta otwiera główne ciało drzewa, po której zapisywane są informacje o jego elementach.
Jeżeli drzewo nie jest puste, kolejnym krokiem jest zapis wszelkich standardowych elementów, a także deklaracje wszystkich elementów referencjonowanych pierwszego poziomu. W przypadku elementów referencjonowanych, zapisywane są tylko ich deklaracje, a referencje do obiektów tych elementów dodawane są na koniec listy pomocniczej. Dzięki temu po zakończeniu procesu zapisu głównego ciała drzewa, pomocnicza lista zawiera wszystkie elementy referencjonowane pierwszego poziomu, gotowe do zdefiniowania poza głównym ciałem drzewa. Po zapisie zawartości głównego ciała drzewa, zapisywana jest linia ze specjalną frazą kluczową, zamykającą ramę drzewa.
Kolejnym krokiem w procesie serializacji drzewa jest zapis definicji referencjonowanych elementów. Jeśli pomocnicza lista nie jest pusta, kolejne referencje do obiektów tych elementów zdejmowane są z początku listy i zapisywane są ich definicje. Jeśli wewnątrz aktualnie zapisywanego referencjonowanego węzła potomnego znajdują się kolejne referencjonowane elementy, zapisywane są ich deklaracje, a ich obiekty dodawane są na początek tej samej listy pomocniczej. Dzięki temu po zdefiniowaniu aktualnie zapisywanego węzła, nowo napotkane referencjonowane elementy znajdują się na początku listy pomocniczej i mogą być zdefiniowane jako następne. W ten sposób poprawna kolejność definicji zostaje zachowana.
Po wykonaniu wyżej wymienionych kroków, proces serializacji drzewa zostaje zakończony.
2.8.2. odczyt pliku tekstowego
Proces odczytu pliku tekstowego i zbudowanie na podstawie jego źródła drzewa w pamięci, przebiega w praktyce tak samo jak proces zapisu drzewa z pamięci do pliku. Odczyt pliku wykonywany jest tak samo w kilku krokach, w których także pośredniczy konwerter. Konwerter ten posiadając strumień wejściowy oraz referencję do instancji klasy drzewa, analizuje strumień i konstruuje w pamięci odpowiednią strukturę drzewa konfiguracji.
diagram procesu konstrukcji drzewa z formy tekstowej
Pierwszym krokiem jest wczytanie głównego komentarza drzewa, pod warunkiem, że znajduje się on na początku źródła. Następnie analizowany jest nagłówek drzewa i znajdująca się w nim wersja formatu jest walidowana. Jeśli nagłówek zapisany jest w wersji rozszerzonej, wyodrębniany jest identyfikator drzewa.
Jeśli drzewo nie jest puste, następnym krokiem jest odczyt wszystkich zawartych w głównym ciele drzewa standardowych elementów, a także referencjonowanych pierwszego poziomu. W przypadku elementów referencjonowanych, wczytywane są takie informacje jak komentarze deklaracji oraz identyfikatory. Utworzone obiekty tych elementów i uzupełnione w szczątkowe dane dodawane są do pomocniczej listy. Dzięki temu po zakończeniu odczytu informacji z głównego ciała drzewa, pomocnicza lista zawiera wszystkie referencjonowane elementy pierwszego poziomu, gotowe do uzupełnienia w następnym kroku. Wczytywanie informacji z głównego ciała drzewa wykonywane jest do napotkania linii ze specjalną frazą kluczową, zamykającą główne ciało drzewa.
Następnym krokiem deserializacji drzewa jest skompletowanie niepełnych danych wszystkich referencjonowanych elementów, znajdujących się w liście pomocniczej. Jeżeli lista ta nie jest pusta, kolejne obiekty tych elementów zostają zdjęte z początku listy i kompletowane są ich informacje. Jeśli wewnątrz aktualnie uzupełnianego referencjonowanego węzła potomnego znajdują się kolejne referencjonowane elementy, tworzone są ich obiekty, uzupełniane w szczątkowe informacje i dodawane są na początek pomocniczej listy. W rezultacie po odczycie aktualnie kompletowanego węzła, nowo napotkane elementy referencjonowane znajdują się na początku listy pomocniczej i to one zostają uzupełnione w brakujące dane jako następne. Dzięki temu poprawna kolejność definicji zostaje zachowana.
Po wykonaniu wyżej wymienionych kroków, proces deserializacji drzewa dobiega końca.
3. forma binarna
Forma binarna plików konfiguracyjnych zaprojektowana została tak, aby zwiększyć szybkość procesu ładowania plików do pamięci oraz proces zapisu drzewa z pamięci do pliku. Nie jest czytelna dla człowieka, dlatego że przedstawiana jest w plikach amorficznych, w których zapisywane są jedynie wymagane dane.
W odróżnieniu od formy tekstowej, forma binarna plików konfiguracyjnych nie wykorzystuje informacji dodatkowych, takich jak słowa kluczowe, wcięcia czy puste linie. Natomiast tak samo jak w formie tekstowej, przechowywane są komentarze elementów, aby zachować zgodność pomiędzy formami.
Binarne pliki konfiguracyjne TreeStructInfo przeznaczone są dla zamkniętych konfiguracji, nie dającej użytkownikowi ich łatwej modyfikacji, stawiając na pierwszym planie szybkość ładowania plików i zapisu drzew do plików. Natomiast jeśli przyjazna dla człowieka forma zapisu i możliwość łatwego modyfikowania konfiguracji ma większą wagę niż szybkość obsługi plików, lepszym rozwiązaniem może okazać się forma tekstowa.
Ciągi znaków w binarnych plikach konfiguracyjnych kodowane są w UTF-8.
3.1. struktura plików binarnych
Binarne pliki konfiguracyjne składają się z ciągów bajtów, w których opisane są obowiązkowe informacje, służące do identyfikowania pliku jako konfiguracja TreeStructInfo oraz do rozpoznania wersji formatu drzewa, zapisanego w pliku. Do zbioru danych obowiązkowych należą także identyfikator drzewa oraz główny komentarz drzewa. Danymi dynamicznymi są informacje na temat zawartych w strukturze drzewa elementów, a także ich komentarzy.
3.1.1. typ i format danych
Do każdego pliku binarnego zapisywane są dane trzech typów — liczby całkowite, wartości logiczne oraz łańcuchy znaków.
1-bajtowe liczby naturalne służą do zapisu wersji formatu w nagłówku pliku binarnego, natomiast 4-bajtowe wykorzystywane są do zapisu liczby elementów znajdujących się w węzłach, a także do zapisu długości łańcuchów komentarzy, ciągów wartości atrybutów oraz identyfikatorów elementów. 1-bajtowe wartości logiczne używane są do zapisu stanu referencjonowania elementów drzewa.
Ciągi znaków zapisywane są jako pary buforów — w pierwszej kolejności zapisywana jest na 4 bajtach długość łańcucha (w bajtach, nie znakach), a następnie faktyczna jego zawartość. Jeśli łańcuch znaków jest pusty, jego zapis ogranicza się jedynie do 4-bajtowej długości o wartości 0.
schemat struktury zapisu pojedynczego łańcucha znaków
Jeśli ciąg znaków zawiera wieloliniową wartość atrybutu lub wieloliniowy komentarz, poszczególne linie muszą być oddzielone znakami o kodzie 0x0A i zapisane jako jeden ciąg bajtów. Poniżej znajduje się przykład zapisu dwuliniowej wartości atrybutu, zawierającej linie foo oraz bar:
schemat struktury zapisu dwuliniowej wartości atrybutu
3.1.2. dane obowiązkowe
W skład danych obowiązkowych, istniejących w każdym pliku binarnym, wchodzą przede wszystkim sygnatura, składająca się z 14-bajtowej wartości TREESTRUCTINFO, a także numer wersji formatu, jako dwie 1-bajtowe liczby naturalne o wartościach odpowiednio 2 oraz 0. Kolejnymi danymi są ciągi identyfikatora drzewa oraz głównego komentarza drzewa. Ciągi te mogą być puste — w takim przypadku zapisywana jest tylko i wyłącznie ich zerowa długość (jako 4-bajtowe liczby 0). Ostatnimi obowiązkowymi danymi są liczby elementów według danego typu, zawartych w głównym węźle drzewa — jeśli drzewo jest puste, są to dwie 4-bajtowe liczby naturalne o wartościach 0.
Poniżej znajduje się schemat struktury ramy pliku binarnego, zawierającego puste drzewo, bez określonego identyfikatora drzewa a także bez głównego komentarza drzewa:
schemat struktury ramy pliku binarnego, zawierającego puste drzewo
Plik binarny zawierający puste drzewo konfiguracyjne, zajmuje dokładnie 32 bajty.
Jeżeli drzewo nie jest puste, zapis sygnatury pliku, wersji formatu, identyfikatora drzewa oraz głównego komentarza drzewa nie zmienia się. Natomiast zmianie ulega zapis listy elementów potomnych zawartych w głównym węźle i wygląda tak jak w przypadku zapisu zawartości innych węzłów.
3.1.3. dane dynamiczne
Do zbioru informacji dynamicznych zalicza się zapis wszystkich elementów zawartych w głównym węźle drzewa, czyli wszelkich standardowych oraz referencjonowanych atrybutów i węzłów potomnych. Każdy z elementów reprezentowany jest inną sekwencją bajtów, z racji posiadania różnych i różnej ilości informacji.
3.1.3.1. zapis atrybutów
Sekwencja bajtów opisujących pojedynczy standardowy lub referencjonowany atrybut musi zawierać zapis stanu referencjonowania, identyfikatora, wartości oraz zapis obu komentarzy. Jeśli atrybut posiada wartość wieloliniową, poszczególne jej linie muszą być oddzielone od siebie znakiem o kodzie 0x0A, według zasad zapisu ciągów znaków.
schemat struktury zapisu pojedynczego standardowego lub referencjonowanego atrybutu
3.1.3.2. zapis węzłów potomnych
Zapis pojedynczego standardowego lub referencjonowanego węzła to sekwencja bajtów, zawierająca reprezentację stanu referencjonowania, identyfikatora węzła, obu komentarzy oraz listy elementów potomnych, zawartych w zapisywanym węźle.
schemat struktury zapisu pojedynczego standardowego lub referencjonowanego węzła potomnego
Zapis elementów potomnych jest ściśle określony. W pierwszej kolejności na 4 bajtach zapisywana jest liczba atrybutów, a po niej dane poszczególnych atrybutów. Następnie na kolejnych 4 bajtach zapisywana jest liczba węzłów potomnych, a po niej zapis wszystkich potomnych węzłów.
Natomiast zapis głównego węzła drzewa obejmuje tylko i wyłącznie listę elementów potomnych. Główny węzeł nie posiada swojego stanu referencjonowania, nie posiada także swojego identyfikatora oraz komentarzy, stąd zapis pustych ich odpowiedników byłby nadmiarowy.
3.2. przetwarzanie plików binarnych
Przetwarzanie plików konfiguracyjnych TreeStructInfo w formie binarnej jest znacznie prostsze i szybsze, niż przetwarzanie plików tekstowych. Pliki binarne nie posiadają danych dodatkowych, takich jak słowa i frazy kluczowe, wcięcia czy puste linie, a także nie posiadają zapisu wydzielonych z ramy drzewa ciał elementów referencjonowanych.
3.2.1. zapis pliku binarnego
Zapis natywnego drzewa z pamięci do pliku binarnego także odbywa się w kilku głównych krokach. W zapisie drzewa pośredniczy konwerter binarny, który posiadając referencję do obiektu drzewa, analizuje go i generuje wyjściowy strumień bajtów. Tak przygotowany strumień zawiera kompletne drzewo z rekurencyjnie zapisanymi danymi elementów.
diagram procesu serializacji drzewa do formy binarnej
Pierwszym krokiem zapisu drzewa do strumienia binarnego jest zapis nagłówka. Pierwszą zapisywaną wartością jest specjalna sygnatura jako ciąg znaków TREESTRUCTINFO, następnie wersja formatu. Kolejnymi danymi są identyfikator drzewa oraz główny komentarz drzewa.
Następnym krokiem jest rekurencyjny zapis kompletnych informacji wszystkich standardowych i referencjonowanych elementów. Z racji tej, że w plikach binarnych nie wykorzystuje się osobnego zapisu deklaracji i definicji referencjonowanych elementów, pomocnicza lista do przechowywania referencji do obiektów tych elementów nie jest wymagana.
Po wykonaniu wyżej wymienionych kroków, proces serializacji drzewa zostaje zakończony.
3.2.2. odczyt pliku binarnego
Proces odczytu pliku binarnego przebiega za pośrednictwem konwertera binarnego, który posiadając referencję do obiektu drzewa, analizuje binarne źródło i konstruuje w pamięci odpowiednią natywną strukturę drzewa konfiguracji. Proces ten przebiega praktycznie tak samo jak proces serializacji drzewa z pamięci do pliku.
diagram procesu konstrukcji drzewa z formy binarnej
Wstępnym krokiem deserializacji drzewa jest odczyt i walidacja nagłówka. Pierwszą wczytywaną wartością jest specjalna sygnatura jako ciąg TREESTRUCTINFO, następnie wersja formatu. Następnymi wyodrębnianymi danymi są identyfikator drzewa oraz główny komentarz drzewa.
Kolejną i ostatnią fazą deserializacji jest rekurencyjny odczyt kompletnych danych wszystkich standardowych i referencjonowanych elementów. Dzięki temu, że w plikach binarnych elementy referencjonowane zapisane są w całości (bez wydzielonych definicji w innych miejscach), pomocnicza lista do przechowywania referencji do ich obiektów nie jest wymagana.
Po wykonaniu wyżej wymienionych czynności, proces deserializacji drzewa dobiega końca.
4. sugestie dotyczące API
Format tekstowych i binarnych plików konfiguracyjnych TreeStructInfo został zaprojektowany tak, aby był przyjazny zarówno dla użytkowników, jak i dla programistów tworzących oprogramowanie. Dlatego też podczas tworzenia nowych API do obsługi plików zaleca się, aby były bardzo proste w użyciu i zarazem jak najbardziej funkcjonalne, a przede wszystkim zgodne ze specyfikacją formatu.
Poniżej znajduje się lista głównych sugestii dla programistów zainteresowanych stworzeniem nowego API.
obsługa plików konfiguracyjnych
Zaleca się, aby nowe API umożliwiało ładowanie drzew TreeStructInfo z różnych źródeł — z plików dyskowych, z zasobów plików wykonywalnych i bibliotek (np. DLL), a także bezpośrednio ze strumieni znaków (dla plików tekstowych) lub ze strumieni binarnych (dla plików tekstowych i binarnych). Zapis drzew z pamięci powinien być możliwy zarówno do plików dyskowych, jak i zewnętrznych strumieni.
budowa drzew w pamięci
Klasa opisująca pojedyncze drzewo powinna być zaprojektowana tak, aby zawierała zagnieżdżone w sobie listy elementów. Główne węzły drzew oraz standardowe i referencjonowane węzły potomne powinny być tego samego typu (np. tej samej klasy).
dostęp do elementów drzew
Dostęp do wszystkich elementów drzew powinien wykorzystywać mechanizm standardowych ścieżek dostępu.
dostęp do komentarzy
Z racji tej, że wszelkie komentarze są własnościami drzew oraz elementów drzew, dostęp do nich także powinien być możliwy na podstawie standardowych ścieżek dostępu. Komentarze istniejące w pliku samodzielnie są niezgodne ze specyfikacją.
typy danych i ich format w wartościach atrybutów
Zaleca się, aby API umożliwiało zapis danych do wartości atrybutów we wszystkich wymienionych w specyfikacji typach danych, a także w wymienionych formatach zapisu. Natomiast wsparcie dla innych typów danych niż wymienione w specyfikacji to kwestia otwarta. Jednak zapis poszczególnych wartości lub linii wartości musi być zgodny z opisanymi zasadami ich reprezentacji.