Dokumentacja TreeStructInfoParser PHP

Parser strukturalnego formatu tekstowego TreeStructInfo, umożliwiający przetwarzanie atrybutów, węzłów zagnieżdżonych, odniesień, automatyczne rzutowanie typów oraz opcjonalne cachowanie wyników.

Licencja: BSD 3-Clause
Wersja parsera: 2.0
Autor: Dariusz Rorat

Wymagania

PHP 5.4 lub nowszy
Brak zewnętrznych zależności

Instalacja

Dodaj klasę TreeStructInfoParser do swojego projektu, lub załaduj ją przy użyciu autoloadera (np. PSR-4).

require_once 'TreeStructInfoParser.php';

Podstawowe użycie

$parser = new TreeStructInfoParser();
$parser->setAutoCasting(true); // włącza automatyczne rzutowanie

$input = file_get_contents('plik.tsi');
$result = $parser->parse($input);

print_r($result);

Funkcje publiczne

`parse(string $input): array`

Parsuje tekst w formacie TreeStructInfo i zwraca go jako tablicę PHP.

`parseWithCache(string $inputFile, string $cacheFile): array`

Parsuje plik i buforuje wynik jako plik PHP. Jeśli plik cache jest nowszy niż wejściowy, zostanie użyty bez parsowania.

`setAutoCasting(bool $value): void`

Włącza lub wyłącza automatyczne rzutowanie wartości (np. "true" → true, "0xFF" → 255).

`setMultilineJoinChar(string $char): void`

Określa znak, którym będą łączone wieloliniowe wartości atrybutów.

`setBoolValues(array $trueValues, array $falseValues): void`

Definiuje własne reprezentacje wartości logicznych (np. ["yes"], ["no"]).

Format TreeStructInfo

Przykład:

treestructinfo "2.0" name "Example"

:: komentarz
attr name "Example Tree"
"wielolinia
ciąg dalszy"

node settings
    attr enabled "true"
end node

end tree

Składnia:

treestructinfo "2.0" name "OptionalName" — nagłówek
attr <nazwa> "<wartość>" — atrybut
node <nazwa>...end node — węzeł
"..." — kontynuacja wartości atrybutu w nowej linii
:: — komentarz
end tree — zakończenie drzewa

Obsługa referencji

Biblioteka wspiera odniesienia (referencje) do atrybutów i węzłów:

ref attr description "Common description"
"wielolinia"

ref node common
    node child
        attr value "42"
    end node
end ref node

W głównym drzewie można używać:

ref attr description
ref node common

Rzutowanie typów

W trybie autoCasting = true, parser próbuje zinterpretować dane jako:

true, false → bool
0xABCD, 0b1010, 0o77 → liczby
123, -4.5, 1e3 → liczby całkowite i zmiennoprzecinkowe
a1b2c3... (hex string) → binarne
base64encoded== → binarne

Działa również na współrzędne:

attr position "+10,+20"

Zostanie zinterpretowane jako: [10, 20]

Cachowanie

Dzięki parseWithCache() możliwe jest buforowanie wyniku parsowania w pliku PHP:

$parser->parseWithCache('data.tsi', 'cache/data.php');

Licencja

Projekt udostępniony na licencji BSD 3-Clause.

BSD-3-Clause
Сopyright (c) 2025 Dariusz Rorat

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.