Title: Interfejs wyjścia

---

TypeFriendly pozwala łatwo tworzyć własne systemy wyjścia, które będą mogły być później użyte do generowania dokumentacji. Do ich tworzenia wymagana jest pewna znajomość języka PHP.

Zasada parsowania
=================

TypeFriendly rozpoczyna działanie od utworzenia obiektu projektu, za pomocą którego możliwe są wszelkie manipulacje na dokumentacji. Odczytywana jest konfiguracja, a następnie wszystkie rozdziały są przetwarzane i układane w odpowiedniej kolejności. Na końcu skrypt ładuje wszystkie wyjścia, które będa wykorzystywane i nakazuje każdemu z nich przetwarzać wstępnie obrobione wyniki.

Każde wyjście zapisane jest w niezależnym pliku PHP w katalogu `outputs/`. Ma postać klasy o takiej samej nazwie, jak nazwa pliku (z pominięciem rozszerzenia) i musi rozszerzać klasę `standardOutput` definiującą trzy metody opisane niżej. Zadaniem wyjścia jest opakowanie meta-danych w kod HTML lub inny bazujący na nim format. Niestety, obecnie wykorzystywany parser Markdown nie potrafi generować kodu wynikowego w niczym innym, stąd póki co niemożliwe jest napisanie wyjścia np. do formatu LaTeX. Prace nad umożliwieniem tego zostaną podjęte w niedalekiej przyszłości.

Wyjście samo musi dbać o zapisanie wyniku do odpowiednich plików - TypeFriendly nie narzuca tu żadnych ograniczeń i jedynie przekazuje katalog, w którym wszystko ma się znaleźć. Do dyspozycji programisty jest kilka interfejsów skryptu.

API
===

`standardOutput`
----------------

Jest to klasa abstrakcyjna, którą musi rozszerzać i implementować klasa wyjścia. Zawiera metody:

+ `init($project, $path)` - wywoływana przed rozpoczęciem przetwarzania podstron. Jako parametry dostaje obiekt projektu oraz ścieżkę, do której należy zapisać pliki wynikowe.
+ `generate($page)` - wywoływana dla każdego rozdziału. Wyjście dostaje tablicę `$page` ze wszystkimi meta-danymi dotyczącymi rozdziału. Indeksy odpowiadają nazwom użytych tagów w pliku. Dodatkowe tagi opisane są niżej.
+ `close()` - wywoływana na zakończenie przetwarzania danego wyjścia.

Dodatkowe tagi w meta-danych rozdziału

* `Id` - identyfikator rozdziału
* `Content` - przetworzona treść rozdziału
* `Next` - identyfikator następnej strony dokumentacji lub NULL
* `Prev` - identyfikator poprzedniej strony dokumentacji lub NULL
* `Parent` - identyfikator rozdziału nadrzędnego lub NULL

`tfTranslate`
-------------

Obiekt tej klasy służy do tłumaczenia interfejsu dokumentacji na różne języki.

+ `tfTranslate::get()` - zwraca obiekt interfejsu tłumaczeń.
+ `_($group, $id, ...)` - pobiera tekst w danym języku o identyfikatorze `$id` w grupie `$group`. Opcjonalnie można podać więcej argumentów, które zostaną umieszczone w komunikacie, o ile zawiera on odpowiednie do tego celu pola.

`tfProject`
-----------

Obiekt projektu.

+ `$fs` - obiekt klasy `tfFilesystem` obrazujący katalog projektu.
+ `$tree` - publiczna struktura opisująca drzewo. Jako indeks podajemy identyfikator żądanego rozdziału i otrzymujemy tablicę z pełnymi danymi wszystkich zawartych w nim podstron.
+ `getMetaInfo($name[, $exception = true])` - zwraca wszystkie meta-informacje dotyczące rozdziału o nazwie `$name`. Domyślnie w przypadku nieznalezienia generowany jest wyjątek. Jeżeli ostatni argument ustawiony jest na **false**, wtedy w przypadku braku zwracana jest wartość **NULL**.

`tfFilesystem`
--------------

Klasa reprezentująca system plików w obrębie podanego katalogu. Umożliwia szybką i prostą manipulację plikami oraz katalogami. W opisie przez ''system plików'' będziemy rozumieć folder, na który został ustawiony obiekt tej klasy i w obrębie którego możemy dokonywać manipulacji.

+ `get($name)` - zwraca rzeczywistą ścieżkę do podanego pliku w systemie plików. W razie nieznalezienia generowany jest wyjątek `SystemException`.
+ `read($name)` - zwraca zawartość podanego pliku w systemie plików. W razie nieznalezienia generowany jest wyjątek.
+ `readAsArray($name)` - jw. lecz zwraca tablicę z poszczególnymi linijkami pliku pozbawionymi końcowych białych znaków.
+ `write($name, $content)` - zapisuje podaną zawartość do podanego pliku w obrębie systemu plików.