TTSInfoTree

Artykuł ten zawiera kurs obsługi rozszerzonej klasy do obsługi plików TreeStructInfo, która zawiera metody udostępniające rzadziej stosowane możliwości modyfikacji zawartość drzew. Opisuje wszystkie publiczne metody klasy TTSInfoTree, przedstawiając różne sposoby ich wykorzystania. Zobrazowane są przykładami kodów oraz ewentualną zawartością plików konfiguracyjnych, przed i po wykonaniu danych metod, w zgodnej z formatem składni. Opisy składowych przedstawione są w takiej kolejności, w jakiej są zaimplementowane w klasie drzewa.

W opisach poszczególnych metod wykorzystywany jest poniższy termin:

Aby móc używać rozszerzonej klasy do obsługi plików konfiguracyjnych, do sekcji uses dodać należy moduł TSInfoFiles. W przedstawionych przykładach wykorzystania metod klasy użyte są typy danych, zadeklarowane w module TSInfoTypes. Aby móc z nich skorzystać, moduł ten także musi zostać dodany do sekcji uses.

W przykładach użycia metod wykorzystane są nazwy plików, zawierające rozszerzenia .tsinfo, oznaczające pliki w formie tekstowej, a także .tsibin, informujące o ich binarnej zawartości. Rozszerzenia te są umowne i nieobowiązkowe, stąd pliki zawierające drzewa TreeStructInfo mogą posiadać inne rozszerzenia, bądź nie posiadać ich w ogóle. Nie wpłynie to w żaden sposób na poprawność funkcjonowania mechanizmów biblioteki.

spis treści

1. zmiana nazw elementów

Rozszerzona klasa umożliwia zmianę nazw elementów, bez rozróżniania ich stanu referencjonowania. Do dyspozycji są dwie metody, pozwalające na zmianę identyfikatora pojedynczego atrybutu lub węzła potomnego.

Metody zmieniające nazwy elementów drzewa nie sprawdzają, czy w danym węźle istnieje już element o takiej nazwie, jak podawana nowa. Należy więc pamiętać, aby w jednym węźle nie istniały dwa elementy z identycznymi identyfikatorami.

1.1. zmiana nazwy atrybutu

Do zmiany identyfikatora pojedynczego atrybutu służy metoda RenameAttribute. Pobiera ona w parametrze AAttrPath ścieżkę lub nazwę atrybutu do zmiany nazwy, a także łańcuch znaków z nowym identyfikatorem w argumencie ANewAttrName.

Poniżej przykład deklaracji standardowego atrybutu:

attr Name "Value"

Aby zmienić nazwę powyższego atrybutu, w przypadku gdy znajduje się on w aktualnie otwartym lub głównym węźle drzewa, w parametrze AAttrPath podać należy samą nazwę atrybutu, natomiast w argumencie ANewAttrName przekazać należy nowy jego identyfikator:

tsiConfig.RenameAttribute('Name', 'New Name');

Jeżeli atrybut ten nie znajduje się wewnątrz aktualnie otwartego lub głównego węzła, w argumencie AAttrPath podać należy jego ścieżkę:

tsiConfig.RenameAttribute('First\Name', 'New Name');

Metoda wywołana w powyższy sposób zmieni nazwę atrybutu Name na New Name, znajdującego się w węźle o identyfikatorze First. Po zapisie danych, nowa deklaracja atrybutu wyglądać będzie następująco:

attr New Name "Value"

1.2. zmiana nazwy węzła potomnego

Zmianę identyfikatora dowolnego węzła potomnego umożliwia metoda RenameChildNode. Pobiera ona w parametrze ANodePath ścieżkę lub nazwę węzła potomnego do zmiany nazwy, a także ciąg znaków nowego identyfikatora w argumencie ANewNodeName.

Poniżej przykład deklaracji standardowego węzła potomnego:

node Name
end node

Aby zmienić jego nazwę, w przypadku gdy znajduje się on wewnątrz aktualnie otwartego lub głównego węzła drzewa, w parametrze ANodePath przekazać należy samą jego nazwę, natomiast nową podać w argumencie ANewNodeName:

tsiConfig.RenameChildNode('Name', 'New Name');

Jeżeli docelowy węzeł nie jest zawarty w aktualnie otwartym lub głównym węźle, w argumencie ANodePath podać należy jego ścieżkę:

tsiConfig.RenameChildNode('First\Name', 'New Name');

Metoda wywołana w powyższy sposób spowoduje zmianę identyfikatora węzła potomnego Name na New Name, znajdującego się wewnątrz węzła o nazwie First. Po zapisie danych, deklaracja węzła przyjmie poniższą postać:

node New Name
end node

2. zapisywanie komentarzy elementów

Klasa TTSInfoTree umożliwia zapis jednoliniowych oraz wieloliniowych komentarzy dla atrybutów oraz węzłów potomnych, a także zapis głównego komentarza drzewa. W przypadku elementów drzew, możliwy jest zapis komentarza deklaracji i definicji z osobna.

Zapis komentarza wieloliniowego od jednoliniowego odróżnia określenie i podanie ciągu separatora, na podstawie którego dzielony jest wejściowy łańcuch znaków na składowe. W przypadku komentarza jednoliniowego, jako łańcuch separatora podaje się pusty ciąg znaków, dzięki czemu linia nie jest dzielona.

2.1. zapis głównego komentarza drzewa

Do zapisu lub usunięcia głównego komentarza drzewa służy metoda WriteTreeComment. W parametrze AComment pobiera ciąg znaków jednoliniowego lub wieloliniowego komentarza, natomiast w argumencie ADelimiter pobiera łańcuch znaków, na podstawie którego ciąg komentarza dzielony jest na składowe.

Aby zapisać główny komentarz drzewa w postaci jednoliniowej, w parametrze AComment przekazać należy ciąg znaków komentarza, natomiast w argumencie ADelimiter podać należy pusty łańcuch:

tsiConfig.WriteTreeComment('this is main tree comment', '');

Po zapisie danych, przed nagłówkiem drzewa widnieć będzie poniższy komentarz:

:: this is main tree comment

Jeśli podany w parametrze AComment ciąg znaków zawiera komentarz wieloliniowy, w argumencie ADelimiter podać należy łańcuch znaków separatora składowych komentarza:

tsiConfig.WriteTreeComment('this is main tree comment||it is last comment line', '|');

Powyższa instrukcja spowoduje zapisanie głównego komentarza drzewa, składającego się z trzech linii, z czego druga linia będzie pusta. Po zapisie danych, główny komentarz przestawiać się będzie następująco:

:: this is main tree comment
::
:: it is last comment line

Aby usunąć komentarz, należy w obu parametrach przekazać puste łańcuchy znaków:

tsiConfig.WriteTreeComment('', '');

2.2. zapis komentarza atrybutu

Do zapisu lub usunięcia komentarza deklaracji lub definicji atrybutu służy metoda WriteAttributeComment. Pobiera ona ścieżkę lub nazwę atrybutu w parametrze AAttrPath, ciąg znaków jednoliniowego lub wieloliniowego komentarza w parametrze AComment, łańcuch znaków separatora składowych w argumencie ADelimiter oraz typ komentarza w parametrze AType typu TCommentType.

Poniżej przykład deklaracji standardowego atrybutu, któremu zostanie nadany komentarz:

attr Foo "Value"

Aby zapisać jednoliniowy komentarz do atrybutu, w przypadku gdy znajduje się on wewnątrz aktualnie otwartego lub głównego węzła drzewa, w argumencie AAttrPath podać należy samą jego nazwę, w parametrze AComment przekazać łańcuch znaków komentarza, w argumencie ADelimiter podać pusty łańcuch, natomiast w argumencie AType przekazać wartość ctDeclaration:

tsiConfig.WriteAttributeComment('Foo', 'this is attribute comment', '', ctDeclaration);

Metoda wywołana w powyższy sposób spowoduje zapisanie komentarza jednoliniowego o wartości this is attribute comment do atrybutu o nazwie Foo. Po zapisie danych, deklaracja atrybutu przyjmie poniższą postać:

:: this is attribute comment
attr Foo "Value"

Jeżeli komentarz jest wieloliniowy, w parametrze ADelimiter przekazać należy ciąg znaków separatora składowych:

tsiConfig.WriteAttributeComment('Foo', 'this is attribute comment - it is second comment line', ' - ', ctDeclaration);

Łańcuch znaków z parametru AComment zostanie rozdzielony na składowe, na podstawie podciągu  - , czego efektem będzie rozdzielenie komentarza na dwie linie. Deklaracja atrybutu po zapisie danych przyjmie poniższą postać:

:: this is attribute comment
:: it is second comment line
attr Foo "Value"

Zapis komentarza definicji atrybutu referencjonowanego możliwy jest dzięki wartości ctDefinition, podanej w parametrze AType. Natomiast aby usunąć dany komentarz, w parametrach AComment oraz ADelimiter przekazać należy puste ciągi znaków.

2.3. zapis komentarza węzła potomnego

Do zapisu lub usunięcia komentarza deklaracji lub definicji węzła potomnego służy metoda WriteChildNodeComment. Przyjmuje ona w parametrze ANodePath ścieżkę lub nazwę węzła potomnego, ciąg znaków komentarza w argumencie AComment, łańcuch znaków separatora składowych w parametrze ADelimiter oraz typ komentarza w argumencie AType typu TCommentType.

Poniżej przykład deklaracji standardowego węzła potomnego, któremu nadany zostanie komentarz:

node First
end node

Aby zapisać jednoliniowy komentarz do węzła potomnego, znajdującego się wewnątrz aktualnie otwartego lub głównego węzła drzewa, w argumencie ANodePath podać należy samą nazwę węzła, w parametrze AComment przekazać ciąg znaków komentarza, w argumencie ADelimiter podać pusty łańcuch znaków, natomiast w parametrze AType przekazać wartość ctDeclaration:

tsiConfig.WriteChildNodeComment('First\', 'this is child node comment', '', ctDeclaration);

Powyższa instrukcja spowoduje zapisanie komentarza jednoliniowego o wartości this is child node comment do węzła First. Po zapisie danych, deklaracja węzła przedstawiać się będzie następująco:

:: this is child node comment
node First
end node

Jeśli podawany komentarz jest wieloliniowy, w parametrze ADelimiter podać należy ciąg znaków separatora składowych:

tsiConfig.WriteChildNodeComment('First\', 'this is child node comment, it is second comment line', ', ', ctDeclaration);

Ciąg znaków komentarza z parametru AComment zostanie podzielony na składowe, na podstawie podciągu , , czego efektem będzie rozdzielenie komentarza na dwie linie. Deklaracja węzła potomnego po zapisie danych będzie wyglądać następująco:

:: this is child node comment
:: it is second comment line
node First
end node

Aby zapisać komentarz definicji referencjonowanego węzła potomnego, w parametrze AType podać należy wartość ctDefinition. Usunięcie danego komentarza możliwe jest za pomocą tej samej metody — w takim przypadku w parametrach AComment oraz ADelimiter przekazać należy puste ciągi znaków.

3. odczytywanie komentarzy elementów

Rozszerzona klasa do obsługi plików konfiguracyjnych TreeStructInfo, oprócz zapisu lub modyfikacji komentarzy, umożliwia także ich odczytywanie. Posiada metody służące do odczytania głównego komentarza drzewa, a także komentarzy standardowych i referencjonowanych atrybutów oraz węzłów potomnych.

Metody te umożliwiają odczytanie zarówno komentarzy jednoliniowych, jak i wieloliniowych.

3.1. odczyt głównego komentarza drzewa

Do odczytu jednoliniowego lub wieloliniowego głównego komentarza drzewa służy metoda ReadTreeComment. Jedynym jej parametrem jest ADelimiter, służący do określenia ciągu znaków, który rozdzielać będzie linie komentarza w łańcuchu zwracanym przez metodę.

Poniżej znajduje się przykład jednoliniowego komentarza drzewa:

:: this is main tree comment

Aby odczytać jego wartość, w parametrze ADelimiter przekazać należy pusty ciąg znaków:

var
  strComment: String;

{..}

strComment := tsiConfig.ReadTreeComment('');

Poniżej przykład wieloliniowego głównego komentarza drzewa:

:: this is main tree comment
::
:: it is last comment line

Aby odczytać jego wartość, w argumencie ADelimiter należy podać znak lub łańcuch separatora składowych:

strComment := tsiConfig.ReadTreeComment('|');

Do zmiennej zostanie wpisany ciąg znaków o wartości this is main tree comment||it is last comment line.

3.2. odczyt komentarza atrybutu

Do odczytu jednoliniowego lub wieloliniowego komentarza deklaracji lub definicji atrybutu służy metoda ReadAttributeComment. Pobiera w parametrze AAttrPath ścieżkę lub nazwę atrybutu, którego komentarz zostanie odczytany, w argumencie ADelimiter przyjmuje ciąg separatora składowych, natomiast w parametrze AType typu TCommentType pobiera typ komentarza do odczytania.

Poniżej przykład deklaracji atrybutu, zawierającego komentarz jednoliniowy:

:: this is attribute comment
attr Foo "Value"

Aby odczytać wartość komentarza, w przypadku gdy atrybut znajduje się wewnątrz aktualnie otwartego lub głównego węzła drzewa, w parametrze AAttrPath przekazać należy samą nazwę atrybutu, w parametrze ADelimiter należy podać pusty łańcuch znaków, natomiast w argumencie AType podać trzeba wartość ctDeclaration:

var
  strComment: String;

{..}

strComment := tsiConfig.ReadAttributeComment('Foo', '', ctDeclaration);

Jeżeli atrybut nie znajduje się w aktualnie otwartym lub głównym węźle, w argumencie AAttrPath przekazać należy jego ścieżkę:

strComment := tsiConfig.ReadAttributeComment('First\Foo', '', ctDeclaration);

Metoda wywołana w powyższy sposób spowoduje odczytanie komentarza z atrybutu Foo, znajdującego się wewnątrz węzła o nazwie First. Poniżej przykład deklaracji atrybutu, zawierającego wieloliniowy komentarz:

:: this is attribute comment
:: it is second comment line
attr Foo "Value"

Aby odczytać komentarz z powyższego atrybutu, w przypadku gdy znajduje się w aktualnie otwartym lub głównym węźle drzewa, a także rozdzielić jego składowe, należy przekazać samą nazwę atrybutu w parametrze AAttrPath oraz podać ciąg znaków separatora w argumencie ADelimiter:

strComment := tsiConfig.ReadAttributeComment('Foo', ' - ', ctDeclaration);

Do zmiennej zostanie wpisany łańcuch this is attribute comment - it is second comment line. Jeżeli odczytany ma zostać komentarz definicji atrybutu referencjonowanego, w parametrze AType przekazać należy wartość ctDefinition.

3.3. odczyt komentarza węzła potomnego

Do odczytu jednoliniowego lub wieloliniowego komentarza węzła potomnego służy metoda ReadChildNodeComment. Pobiera ona w parametrze ANodePath ścieżkę lub nazwę węzła potomnego, zawierającego komentarz do odczytania, ciąg znaków separatora składowych w argumencie ADelimiter oraz typ komentarza w parametrze AType typu TCommentType.

Poniżej przykład deklaracji węzła potomnego, zawierającego jednoliniowy komentarz:

:: this is child node comment
node Second
end node

Aby odczytać komentarz powyższego węzła, w przypadku gdy znajduje się on w aktualnie otwartym lub głównym węźle drzewa, w parametrze ANodePath przekazać należy samą nazwę węzła potomnego, podać pusty łańcuch znaków w argumencie ADelimiter oraz przekazać w parametrze AType wartość ctDeclaration.

var
  strComment: String;

{..}

strComment := tsiConfig.ReadChildNodeComment('Second\', '', ctDeclaration);

Jeśli węzeł nie znajduje się w aktualnie otwartym lub głównym węźle, w argumencie ANodePath podać należy jego ścieżkę:

strComment := tsiConfig.ReadChildNodeComment('First\Second\', '', ctDeclaration);

Tak wywołana metoda spowoduje odczytanie komentarza z węzła Second, zawartego wewnątrz węzła o nazwie First. Poniżej drugi przykład deklaracji węzła potomnego, tym razem zawierającego wieloliniowy komentarz:

:: this is child node comment
:: it is second comment line
node Second
end node

Aby odczytać wartość komentarza z powyższego węzła, w przypadku gdy znajduje się on wewnątrz aktualnie otwartego lub głównego węzła drzewa, a także rozdzielić jego składowe, w argumencie ANodePath przekazać należy samą jego nazwę, natomiast w parametrze ADelimiter podać należy zadany ciąg znaków separatora:

strComment := tsiConfig.ReadChildNodeComment('Second\', ', ', ctDeclaration);

Do zmiennej zostanie wpisany ciąg znaków this is child node comment, it is second comment line. Jeśli metoda ma odczytać komentarz definicji referencjonowanego węzła potomnego, w parametrze AType należy podać wartość ctDefinition.

4. modyfikowanie stanu referencjonowania elementów

Klasa TTSInfoTree posiada zestaw metod, odpowiedzialnych za zmianę stanu referencjonowania dowolnych atrybutów oraz węzłów potomnych. Zmiana ta może być dokonywana dynamicznie (podczas działania programu), bez konieczności ręcznej edycji plików konfiguracyjnych.

4.1. zmiana stanu referencjonowania atrybutu

Do zmiany stanu referencjonowania atrybutu służy metoda SetAttributeReference. Pobiera ona w parametrze AAttrPath ścieżkę lub nazwę atrybutu oraz wartość nowego stanu referencjonowania w argumencie AReference.

Poniżej przykład pliku konfiguracyjnego, zawierającego zagnieżdżony atrybut:

treestructinfo "2.0"
  node First
    attr Foo "Value"
  end node
end tree

Aby zmienić stan referencjonowania atrybutu, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze AAttrPath przekazać należy samą nazwę atrybutu, natomiast w argumencie AReference podać wartość nowego stanu:

tsiConfig.SetAttributeReference('Foo', True);

Jeśli węzeł nie został wcześniej otwarty, w argumencie AAttrPath podać należy ścieżkę atrybutu:

tsiConfig.SetAttributeReference('First\Foo', True);

Po zapisie danych, zawartość pliku konfiguracyjnego przyjmie poniższą postać:

treestructinfo "2.0"
  node First
    ref attr Foo
  end node
end tree

ref attr Foo "Value"

Aby uczynić atrybut Foo z powrotem standardowym, w argumencie AReference należy podać wartość False:

tsiConfig.SetAttributeReference('First\Foo', False);

4.2. zmiana stanu referencjonowania węzła potomnego

Do zmiany stanu referencjonowania węzła potomnego służy metoda SetChildNodeReference. Pobiera ona ścieżkę lub nazwę węzła potomnego w argumencie ANodePath oraz nowy stan referencjonowania w parametrze AReference.

Poniżej przykładowa zawartość pliku konfiguracyjnego, zawierającego zagnieżdżony węzeł potomny:

treestructinfo "2.0"
  node First
    node Second
    end node
  end node
end tree

Aby zmienić stan referencjonowania węzła Second, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze ANodePath przekazać należy samą nazwę węzła, natomiast w argumencie AReference podać należy wartość nowego stanu:

tsiConfig.SetChildNodeReference('Second\', True);

Jeśli żaden węzeł nie jest otwarty, w parametrze ANodePath podać należy pełną ścieżkę:

tsiConfig.SetChildNodeReference('First\Second\', True);

Zawartość pliku konfiguracyjnego po zapisie danych przedstawiać się będzie następująco:

treestructinfo "2.0"
  node First
    ref node Second
  end node
end tree

ref node Second
end ref node

Aby uczynić węzeł Second z powrotem standardowym, w parametrze AReference należy przekazać wartość False:

tsiConfig.SetChildNodeReference('First\Second\', False);

5. pobieranie stanu referencjonowania elementów

Rozszerzona klasa do obsługi plików TreeStructInfo posiada dwie metody, umożliwiające pobranie (odczytanie) stanu referencjonowania atrybutów oraz węzłów potomnych. Do odczytu stanu referencjonowania wymagana jest jedynie sama nazwa lub pełna ścieżka elementu drzewa.

5.1. odczyt stanu referencjonowania atrybutu

Pobranie wartości logicznej określającej stan referencjonowania atrybutu możliwe jest za pomocą metody GetAttributeReference. Jedynym parametrem tej metody jest AAttrPath, w którym pobierana jest ścieżka lub nazwa atrybutu, które stan referencjonowania ma zostać odczytany.

Poniżej przykładowa zawartość pliku konfiguracyjnego, zawierającego zagnieżdżony atrybut:

treestructinfo "2.0"
  node First
    ref attr Foo
  end node
end tree

ref attr Foo "Value"

Aby odczytać stan referencjonowania atrybutu, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze AAttrPath podać należy ciąg znaków z samą nazwą atrybutu:

var
  boolReference: Boolean;

{..}

boolReference := tsiConfig.GetAttributeReference('Foo');

Jeśli żaden węzeł nie jest otwarty, w parametrze AAttrPath przekazać należy pełną ścieżkę atrybutu:

boolReference := tsiConfig.GetAttributeReference('First\Foo');

Wywołanie metody w powyższy sposób spowoduje odczytanie stanu referencjonowania atrybutu Foo. Do zmiennej wpisana zostanie wartość True, dlatego że atrybut ten jest referencjonowany.

5.2. odczyt stanu referencjonowania węzła potomnego

Do odczytu stanu referencjonowania węzła potomnego służy metoda GetChildNodeReference. Pobiera ona ścieżkę lub nazwę węzła potomnego w parametrze ANodePath. Wartością domyślną tego argumentu jest symbol ~, oznaczający sprawdzenie stanu referencjonowania aktualnie otwartego węzła.

Poniżej przykładowa zawartość pliku konfiguracyjnego, zawierającego zagnieżdżony węzeł potomny:

treestructinfo "2.0"
  node First
    ref node Second
  end node
end tree

ref node Second
end ref node

Aby odczytać stan referencjonowania węzła Second, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze ANodePath przekazać należy samą nazwę węzła potomnego:

var
  boolReference: Boolean;

{..}

boolReference := tsiConfig.GetChildNodeReference('Second\');

Jeżeli żaden węzeł nie jest w danej chwili otwarty, w parametrze ANodePath podać należy pełną ścieżkę:

boolReference := tsiConfig.GetChildNodeReference('First\Second\');

Metoda wywołana w powyższy sposób spowoduje odczytanie stanu referencjonowania węzła Second. Do zmiennej wpisana zostanie wartość True, dlatego że węzeł ten jest referencjonowany.

6. usuwanie elementów

Rozszerzona klasa TTSInfoTree posiada szereg metod, służących do usuwania pojedynczych elementów drzewa. Umożliwiają usunięcie standardowych i referencjonowanych atrybutów oraz węzłów potomnych. Metody te usuwają istniejące elementy drzewa na podstawie standardowych ścieżek dostępu, bez względu na ich stan referencjonowania oraz umiejscowienie w drzewie.

6.1. usunięcie pojedynczego atrybutu

Do usunięcia pojedynczego atrybutu z drzewa służy metoda RemoveAttribute. Jedynym parametrem tej metody jest AAttrPath, w którym przekazywany jest łańcuch znaków ze ścieżką lub samą nazwą atrybutu do usunięcia.

Poniżej znajduje się przykładowa zawartość drzewa, zawierającego zagnieżdżony atrybut:

treestructinfo "2.0"
  node First
    attr Foo "Value"
  end node
end tree

Aby usunąć powyższy standardowy atrybut, w przypadku gdy węzeł o identyfikatorze First jest aktualnie otwarty, w argumencie AAttrPath przekazać należy ciąg znaków z samą nazwą atrybutu:

tsiConfig.RemoveAttribute('Foo');

Jeżeli żaden węzeł nie jest otwarty, w parametrze AAttrPath przekazać należy pełną ścieżkę atrybutu:

tsiConfig.RemoveAttribute('First\Foo');

Metoda wywołana w powyższy sposób spowoduje usunięcie atrybutu Foo, znajdującego się wewnątrz węzła o nazwie First. Po zapisie danych, zawartość pliku konfiguracyjnego przedstawiać się będzie następująco:

treestructinfo "2.0"
  node First
  end node
end tree

6.2. usunięcie pojedynczego węzła potomnego

Do usunięcia pojedynczego węzła potomnego służy metoda RemoveChildNode. W parametrze ANodePath pobiera łańcuch znaków ze ścieżką lub nazwą potomnego węzła do usunięcia z drzewa.

Poniżej przykład drzewa, zawierającego zagnieżdżony węzeł potomny:

treestructinfo "2.0"
  node First
    node Second
    end node
  end node
end tree

Aby usunąć węzeł Second, w przypadku gdy węzeł First jest aktualnie otwarty, w argumencie ANodePath podać należy ciąg znaków z samą nazwą węzła:

tsiConfig.RemoveChildNode('Second\');

Jeżeli żaden węzeł nie jest otwarty, w parametrze ANodePath przekazać należy pełną ścieżkę:

tsiConfig.RemoveChildNode('First\Second\');

Tak wywołana metoda spowoduje usunięcie węzła potomnego Second, zawartego wewnątrz węzła o nazwie First. Po zapisie danych, drzewo przedstawiać się będzie następująco:

treestructinfo "2.0"
  node First
  end node
end tree

7. usuwanie wszystkich elementów jednego typu

Klasa TTSInfoTree posiada metody umożliwiające usunięcie z danego węzła wszystkich elementów tego samego typu, czyli wszystkich atrybutów oraz wszystkich węzłów potomnych. Usuwanie elementów jednego typu bazuje jedynie na ścieżce lub nazwie węzła-rodzica, z którego elementy mają zostać usunięte.

7.1. usunięcie wszystkich atrybutów

Do usunięcia wszystkich atrybutów z danego węzła służy metoda RemoveAllAttributes. Jedynym jej parametrem jest ANodePath, w którym pobiera ścieżkę lub nazwę węzła, z którego atrybuty mają zostać usunięte.

Poniżej podana jest zawartość przykładowego drzewa, zawierającego atrybuty:

treestructinfo "2.0"
  node First
    attr Foo "Value"
    attr Bar "Value"
  end node
end tree

Aby usunąć powyższe atrybuty, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze ANodePath przekazać należy pusty łańcuch znaków, symbol ~ lub skorzystać z wartości domyślnej:

tsiConfig.RemoveAllAttributes();

Jeżeli żaden węzeł nie jest otwarty, w parametrze ANodePath należy określić jego ścieżkę:

tsiConfig.RemoveAllAttributes(First\);

Metoda wywołana w powyższy sposób spowoduje usunięcie atrybutów Foo oraz Bar z węzła o nazwie First. Po zapisie danych, zawartość pliku konfiguracyjnego przedstawiać się będzie następująco:

treestructinfo "2.0"
  node First
  end node
end tree

7.2. usunięcie wszystkich węzłów potomnych

Usunięcie wszystkich węzłów potomnych możliwe jest za pomocą metody RemoveAllChildNodes. Pobiera ona w parametrze ANodePath ścieżkę lub nazwę węzła, z którego węzły potomne mają być usunięte.

Poniżej przykład zawartości pliku konfiguracyjnego, zawierającego węzły potomne:

treestructinfo "2.0"
  node First
    node Second
    end node
    node Third
    end node
  end node
end tree

Aby usunąć wszystkie węzły potomne znajdujące się w węźle First, w przypadku gdy jest on aktualnie otwarty, w parametrze ANodePath podać należy pusty ciąg znaków, symbol ~ lub użyć wartości domyślnej:

tsiConfig.RemoveAllChildNodes();

Jeżeli żaden węzeł nie jest otwarty, w argumencie ANodePath przekazać należy jego ścieżkę lub nazwę:

tsiConfig.RemoveAllChildNodes('First\');

Metoda wywołana w powyższy sposób spowoduje usunięcie węzłów Second oraz Third, zawartych wewnątrz węzła o nazwie First. Zawartość pliku po zapisie danych przyjmie poniższą postać:

treestructinfo "2.0"
  node First
  end node
end tree

8. sprawdzanie istnienia elementów

Klasa TTSInfoFile posiada metody, służące do sprawdzania istnienia pojedynczych standardowych lub referencjonowanych atrybutów oraz węzłów potomnych, jedynie na podstawie standardowych ścieżek dostępu.

8.1. sprawdzenie istnienia pojedynczego atrybutu

Do sprawdzenia istnienia w drzewie pojedynczego atrybutu służy metoda AttributeExists. Pobiera w parametrze AAttrPath ścieżkę lub nazwę atrybutu, którego istnienie ma zostać sprawdzone.

Poniżej zawartość przykładowego pliku konfiguracyjnego, zawierającego zagnieżdżony atrybut:

treestructinfo "2.0"
  node First
    attr Foo "Value"
  end node
end tree

Aby sprawdzić, czy atrybut o nazwie Foo istnieje w drzewie, w przypadku gdy węzeł First jest aktualnie otwarty, w argumencie AAttrPath podać należy samą jego nazwę:

var
  boolExists: Boolean;

{..}

boolExists := tsiConfig.AttributeExists('Foo');

Jeżeli żaden węzeł nie jest otwarty, w parametrze AAttrPath podać należy pełną ścieżkę atrybutu:

boolExists := tsiConfig.AttributeExists('First\Foo');

Atrybut o identyfikatorze Foo istnieje pod zadaną ścieżką, więc metoda zwróci wartość True.

8.2. sprawdzenie istnienia pojedynczego węzła potomnego

Do sprawdzenia istnienia w drzewie pojedynczego węzła potomnego służy metoda ChildNodeExists. Przyjmuje ona w argumencie ANodePath ścieżkę lub nazwę węzła potomnego, którego sprawdzenie istnienia ma zostać wykonane.

Poniżej zawartość przykładowego drzewa konfiguracji, zawierającego zagnieżdżony węzeł potomny:

treestructinfo "2.0"
  node First
    node Second
    end node
  end node
end tree

Aby sprawdzić istnienie węzła potomnego, w przypadku gdy węzeł o nazwie First jest aktualnie otwarty, w parametrze ANodePath podać należy łańcuch znaków z samą nazwą węzła:

var
  boolExists: Boolean;

{..}

boolExists := tsiConfig.ChildNodeExists('Second\');

Jeżeli żaden węzeł nie jest otwarty, w argumencie ANodePath podać należy pełną ścieżkę węzła:

boolExists := tsiConfig.ChildNodeExists('First\Second\');

Węzeł potomny o identyfikatorze Second istnieje pod zadaną ścieżką, więc metoda zwróci i wpisze do zmiennej wartość True.

9. pobieranie liczby elementów jednego typu

Rozszerzona klasa do obsługi plików TreeStructInfo posiada metody, służące do pobrania liczby wszystkich elementów tego samego typu, znajdujących się wewnątrz głównego węzła drzewa lub dowolnego węzła potomnego. Metody te wymagają podania standardowych ścieżek dostępu do węzłów, zakończonych znakiem separatora identyfikatorów \.

9.1. pobranie liczby atrybutów

Pobranie liczby wszystkich atrybutów zawartych w danym węźle umożliwia metoda GetAttributesCount. W parametrze ANodePath pobiera ścieżkę lub nazwę dowolnego węzła. Parametr ten posiada wartość domyślną, oznaczającą odwołanie do aktualnie otwartego lub głównego węzła drzewa.

Poniżej przykładowe drzewo konfiguracji, zawierające zagnieżdżone atrybuty:

treestructinfo "2.0"
  node First
    attr Foo "Value"
    attr Bar "Value"
    attr Bald "Value"
  end node
end tree

Aby policzyć powyższe atrybuty, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze ANodePath przekazać należy pusty łańcuch znaków, symbol ~ lub skorzystać z wartości domyślnej:

var
  intCount: Integer;

{..}

intCount := tsiConfig.GetAttributesCount();

Jeżeli żaden węzeł nie jest otwarty, w parametrze ANodePath podać należy ścieżkę lub nazwę węzła:

intCount := tsiConfig.GetAttributesCount('First\');

Wywołanie metody w powyższy sposób spowoduje zwrócenie i wpisanie do zmiennej wartości 3.

9.2. pobranie liczby węzłów potomnych

Do pobrania liczby wszystkich węzłów potomnych, znajdujących się w dowolnym węźle drzewa, służy metoda GetChildNodesCount. Pobiera ona w parametrze ANodePath ścieżkę lub nazwę węzła-rodzica, zawierającego węzły potomne do policzenia. Argument ten posiada wartość domyślną, oznaczającą odwołanie do aktualnie otwartego lub głównego węzła drzewa.

Poniżej przykład zawartości drzewa, zawierającego zagnieżdżone węzły potomne:

treestructinfo "2.0"
  node First
    node Second
    end node
    node Third
    end node
  end node
end tree

Aby policzyć powyższe zagnieżdżone węzły potomne, w przypadku gdy węzeł First jest aktualnie otwarty, w parametrze ANodePath podać należy pusty ciąg znaków, symbol ~ lub skorzystać z wartości domyślnej:

var
  intCount: Integer;

{..}

intCount := tsiConfig.GetChildNodesCount();

Jeśli żaden węzeł nie jest otwarty, w argumencie ANodePath podać należy jego ścieżkę lub samą nazwę:

intCount := tsiConfig.GetChildNodesCount('First\');

Metoda wywołana w powyższy sposób zwróci i wpisze do zmiennej wartość 2.

10. pobieranie nazw i wartości elementów

Rozszerzona klasa udostępnia metody, służące do odczytu nazw węzłów potomnych, a także nazw i wartości atrybutów, zawartych bezpośrednio w zadanym węźle. Kompletny zestaw identyfikatorów elementów lub wartości atrybutów dodawany jest do listy klasy dziedziczącej z TStrings.

Metody odczytujące nazwy lub wartości elementów nie usuwają istniejącej zawartości listy wejściowej, przed jej uzupełnieniem.

10.1. pobranie nazw atrybutów

Do pobrania identyfikatorów wszystkich standardowych i referencjonowanych atrybutów, zawartych bezpośrednio w danym węźle, służy metoda ReadAttributesNames. Pobiera ona w parametrze ANames obiekt listy klasy dziedziczącej po TStrings, a także ścieżkę lub nazwę węzła w argumencie ANodePath.

Poniżej zawartość przykładowego drzewa, zawierającego atrybuty zagnieżdżone:

treestructinfo "2.0"
  node First
    attr Foo "Value"
    attr Bald "Value"
    attr Bar "Value"
  end node
end tree

Aby odczytać nazwy atrybutów z węzła First, w przypadku gdy węzeł ten jest aktualnie otwarty, w argumencie ANames należy podać utworzony w pamięci obiekt listy, natomiast w parametrze ANodePath przekazać należy pusty łańcuch znaków, symbol ~ lub skorzystać z wartości domyślnej:

uses
  Classes;

{..}

var
  slNames: TStringList;

{..}

slNames := TStringList.Create();
tsiConfig.ReadAttributesNames(slNames);

Jeżeli żaden węzeł nie jest aktualnie otwarty, w argumencie ANodePath przekazać należy jego pełną ścieżkę:

tsiConfig.ReadAttributesNames(slNames, 'First\');

Metoda wywołana w powyższy sposób spowoduje odczytanie nazw atrybutów zawartych bezpośrednio w węźle First. Do listy zostaną dodane identyfikatory Foo, Bald oraz Bar. Jeśli w parametrze ANames przekazana zostanie niepusta lista, identyfikatory atrybutów dodane zostaną na jej koniec.

10.2. pobranie wartości atrybutów

Do pobrania wartości wszystkich standardowych i referencjonowanych atrybutów, zawartych bezpośrednio w zadanym węźle, służy metoda ReadAttributesValues. Pobiera ona referencję do obiektu listy klasy dziedziczącej po TStrings w argumencie AValues oraz ścieżkę lub nazwę węzła w parametrze ANodePath.

Poniżej przykładowa zawartość pliku konfiguracyjnego, z drzewem zawierającym atrybuty zagnieżdżone:

treestructinfo "2.0"
  node First
    attr Foo "Foo Value"
    attr Bald "Bald Value"
    attr Bar "Bar Value"
  end node
end tree

Aby odczytać wartości atrybutów znajdujących się w węźle o nazwie First, w przypadku gdy węzeł ten jest aktualnie otwarty, w parametrze AValues podać należy obiekt listy, natomiast w argumencie ANodePath przekazać pusty ciąg znaków, symbol ~ lub wykorzystać jego wartość domyślną:

uses
  Classes;

{..}

var
  slValues: TStringList;

{..}

slValues := TStringList.Create();
tsiConfig.ReadAttributesValues(slValues);

Jeśli żaden węzeł nie jest otwarty, w argumencie ANodePath przekazać należy ciąg znaków z pełną ścieżką węzła:

tsiConfig.ReadAttributesValues(slValues, 'First\');

W ten sposób wywołana metoda spowoduje odczytanie wartości atrybutów zawartych bezpośrednio w węźle First. Do listy dodane zostaną wartości Foo Value, Bald Value oraz Bar Value.

Jeżeli atrybuty posiadają wartości wieloliniowe, do ich odczytu należy wykorzystać mechanizm tokenizowania atrybutów.

10.3. pobranie nazw węzłów potomnych

Do pobrania identyfikatorów wszystkich standardowych i referencjonowanych węzłów potomnych, zawartych bezpośrednio w danym węźle, służy metoda ReadChildNodesNames. Pobiera ona obiekt listy z klasy dziedziczącej po TStrings w argumencie ANames, a także ścieżkę lub nazwę węzła-rodzica w parametrze ANodePath.

Poniżej znajduje się zawartość przykładowego drzewa, posiadającego zagnieżdżone węzły potomne:

treestructinfo "2.0"
  node First
    node Second
    end node
    node Third
    end node
    node Fourth
    end node
  end node
end tree

Aby odczytać identyfikatory węzłów potomnych zawartych w węźle o nazwie First, w przypadku gdy jest on aktualnie otwarty, w argumencie ANames podać należy utworzony w pamięci obiekt listy, natomiast w parametrze ANodePath przekazać należy pusty ciąg znaków, symbol ~ lub skorzystać z wartości domyślnej:

uses
  Classes;

{..}

var
  slNames: TStringList;

{..}

slNames := TStringList.Create();
tsiConfig.ReadChildNodesNames(slNames);

Jeżeli żaden węzeł nie jest aktualnie otwarty, w argumencie ANodePath należy podać ciąg znaków z pełną jego ścieżką:

tsiConfig.ReadChildNodesNames(slNames, 'First\');

Tak wywołana metoda spowoduje dodanie do listy identyfikatorów węzłów Second, Third i Fourth, które znajdują się bezpośrednio w węźle o nazwie First.

11. eksportowanie drzew

Klasa TTSInfoTree udostępnia metody, umożliwiające wyeksportowanie głównego drzewa do osobnego pliku, a także do listy z klasy dziedziczącej po TStrings lub strumienia, dziedziczącego z klasy TStream. Metody eksportujące drzewo do pliku dyskowego lub strumienia, umożliwiają dodatkowo określenie jego formy — tekstowej lub binarnej.

11.1. eksport drzewa do pliku dyskowego

Do wyeksportowania drzewa z pamięci do osobnego pliku dyskowego służy metoda ExportTreeToFile. Pobiera ona w parametrze AFileName ścieżkę lub nazwę docelowego pliku, do którego zostanie zapisane eksportowane drzewo. Dodatkowym parametrem jest AFormat typu TExportFormat, w możliwe jest określenie docelowej formy drzewa.

Aby zapisać drzewo z pamięci do pliku w formie tekstowej, w parametrze AFileName należy podać łańcuch znaków ze ścieżką lub nazwą pliku docelowego, natomiast w parametrze AFormat można przekazać wartość efTextTree lub skorzystać z wartości domyślnej:

tsiConfig.ExportTreeToFile('Exported.tsinfo');

Jeśli drzewo ma być zapisane do pliku w formie binarnej, w argumencie AFormat podać należy wartość efBinaryTree:

tsiConfig.ExportTreeToFile('Exported.tsibin', efBinaryTree);

11.2. eksport drzewa do listy

Do wyeksportowania drzewa z pamięci do listy służy metoda ExportTreeToList. Jedynym jej argumentem jest AList, przyjmujący referencję do instancji klasy listy dziedziczącej po TStrings. Metoda nie umożliwia określenia docelowej formy eksportowanego drzewa.

Aby zapisać główne drzewo konfiguracyjne z pamięci do listy, w parametrze AList przekazać należy obiekt listy:

uses
  Classes;

{..}

var
  slExportedTree: TStringList;

{..}

slExportedTree := TStringList.Create();
tsiConfig.ExportTreeToList(slExportedTree);

11.3. eksport drzewa do strumienia

Do wyeksportowania drzewa z pamięci do strumienia służy metoda ExportTreeToStream. Pobiera ona w parametrze AStream obiekt strumienia z klasy dziedziczącej po TStream. Metoda ta umożliwia także określenie docelowej formy drzewa, przyjmując w parametrze AFormat wartość typu TExportFormat.

Aby zapisać drzewo z pamięci do strumienia w formie tekstowej, w argumencie AStream należy przekazać utworzony w pamięci obiekt strumienia, natomiast w parametrze AFormat można podać wartość efTextTree lub skorzystać z wartości domyślnej:

uses
  Classes;

{..}

var
  msExportedTree: TMemoryStream;

{..}

msExportedTree := TMemoryStream.Create();
tsiConfig.ExportTreeToStream(msExportedTree);

Jeśli drzewo ma zostać zapisane w strumieniu w formie binarnej, w argumencie AFormat podać należy wartość efBinaryTree:

tsiConfig.ExportTreeToStream(msExportedTree, efBinaryTree);

Zobacz też:

copyright © furious programming 2013—2018