Dokumentacja TreeStructInfoExporterJS

Autor: Dariusz Rorat
Rok: 2025
Licencja: BSD 3-Clause
Opis: Eksporter danych w formacie TreeStructInfo z obiektów JavaScript.

Opis

TreeStructInfoExporterJS to klasa służąca do serializacji zagnieżdżonych obiektów JS do czytelnego formatu tekstowego TreeStructInfo, zachowując strukturę drzewiastą, atrybuty i referencje. Umożliwia:

• definiowanie wcięć,
• eksport atrybutów referencyjnych (ref attr),
• poprawne cytowanie tekstów i konwersję typów (number, boolean, base64).

Instalacja

Nie wymaga żadnych zależności — wystarczy skopiować klasę do projektu JS/TS.

Użycie

const exporter = new TreeStructInfoExporterJS();

exporter.setIndent("    "); // 4 spacje
exporter.setRefAttributes({
  license: "BSD",
  source: "internal"
});

const data = {
  version: "1.0",
  name: "MyTree",
  data: {
    settings: {
      enabled: true,
      threshold: 0.85
    },
    meta: {
      note: "Zapisane \"lokalnie\""
    }
  }
};

const output = exporter.export(data);
console.log(output);

Metody publiczne

setIndent(indentString: string): void

Ustawia ciąg znaków stosowany jako wcięcie dla zagnieżdżonych węzłów.
Domyślnie: " " (2 spacje)

setRefAttributes(refs: Object.<string, string>): void

Ustawia pary klucz-wartość, które zostaną zapisane jako ref attr po drzewie.

export(obj: { version: string, name?: string, data: object }): string

Eksportuje obiekt TreeStructInfo do tekstu.

Parametry:

• version – obowiązkowy numer wersji (string)
• name – opcjonalna nazwa drzewa
• data – struktura zagnieżdżona (object)

Zwraca:

Ciąg tekstowy w formacie .tsi

Błędy:

Rzuca Error, jeśli:

• obj nie zawiera version,
• data nie jest poprawnym obiektem.

Wewnętrzne metody prywatne

exportTree(data: object, level: number): string[]

Rekurencyjnie eksportuje węzły i atrybuty na odpowiednim poziomie wcięcia.

stringify(value: any): string

Konwertuje wartość JS do tekstu:

• true → "true"
• false → "false"
• 123 → "123"
• Uint8Array / Buffer → base64
• string → z odpowiednim \" dla cudzysłowów

escape(str: string): string

Ucieczka znaków ", np. Zapis "lokalny" → Zapis \"lokalny\"

isPlainObject(obj: any): boolean

Zwraca true tylko dla zwykłych obiektów ({}), nie tablic czy nulli.

Przykład wygenerowanego formatu .tsi

treestructinfo "1.0" name "MyTree"
  node settings
    attr enabled "true"
    attr threshold "0.85"
  end node
  node meta
    attr note "Zapisane \"lokalnie\""
  end node
end tree
ref attr license "BSD"
ref attr source "internal"

Licencja

Kod objęty jest licencją BSD 3-Clause License.

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

All rights reserved.

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

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. 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.

3. 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.