Invenzzia... po polsku - Tag - development

Co nowego w Invenzzii?

Zyx — nie, 22 mar 2009 10:38:00 +0100

Witam wszystkich! W ostatnich dniach sporo się działo wokół Invenzzii oraz jej projektów. Postanowiłem w tym zbiorczym wpisie omówić krótko najważniejsze rzeczy, dostępnym również w języku angielskim. Poruszymy temat OPT 2.0, nowego TypeFriendly, nowej strony Invenzzii oraz aktywności Invenzzii w "serwisach wspomagania open-source", że tak to ładnie nazwę.

Open Power Template 2

Kilkanaście minut temu na SVN-ie znalazła się kolejna rewizja oznaczona numerem 66, efekt ostatnich czterech dni pracy. Jak na tak krótki okres, zakres wnoszonych poprawek i nowości jest zaiste imponujący.

Zdecydowałem się przepisać na nowo kod odpowiedzialny za kompilację sekcji. Poprzedni miał poważny problem z obsługą specyficznych atrybutów, którego nie dało się w takiej postaci przeskoczyć w żaden sposób. Dzięki tej akcji, poprawiłem znacznie prostotę oraz czytelność kodu, m.in. wyposażając go w phpdoc i upraszczając strukturę. Aby upewnić się, że nowy kod nie wyprodukuje nowych błędów w tym, co dotychczas działało, pojawiło się ponad 20 nowych testów sekcji sprawdzających poprawność obsługi rozmaitych warunków brzegowych oraz współpracy z innymi instrukcjami. Dlatego nowa implementacja nie powinna sprawiać większych niespodzianek, aczkolwiek błąd #51 w dalszym ciągu pozostaje nienaprawiony.
Przy okazji ostatecznie uporządkowałem projekt formatów danych, który też w końcu uzyskał formę, z której jestem zadowolony. Trzeba jeszcze napisać do tego wszystkiego kupę unit testów, ale jesteśmy już na dobrej drodze, by takie testy faktycznie powstały.
Kolejna, dość spora partia kodu PHP została wyposażona w phpdoc. Dzięki temu IDE typu NetBeans i Eclipse będą w stanie jeszcze lepiej podpowiadać semantykę i użycie poszczególnych metod. Phpdoc w kodzie źródłowym został w większości wymuszony właśnie tą potrzebą, gdyż normalna i właściwa dokumentacja pisana jest w oparciu o TypeFriendly.
Usunięte zostało kilka irytujących błędów.

Ponadto, ulepszenia pojawiły się również w podręczniku użytkownika, gdzie pojawił się zupełnie nowy rozdział nazwany "Podręcznik programisty" (ang. "Programmer's guide"). Celem jest stworzenie kompletnego przewodnika po poszczególnych możliwościach OPT, który można czytać jak książkę i który zawiera różne praktyczne wskazówki, nie zawsze dające się opisać w zwykłej dokumentacji API. W poczet nowego rozdziału został włączony stary "API Issues". Obecnie z nowego rozdziału można dowiedzieć się następujących rzeczy:

Jak przygotować OPT do pracy?
Jak pracować z widokami?
Jak pracować z systemami wyjścia?
Jak obsługiwać błędy oraz rozszerzać ich domyślną obsługę?
Jak pracować z formatami danych.
Jak tworzyć wielojęzyczne witryny.
Jak podłączyć własną funkcję do escape'owania HTML-a w danych ze skryptu i zapobiegania atakom XSS?

Lektura dostępna jest wyłącznie w języku angielskim.

TypeFriendly 0.1.1

Niecały tydzień temu został wydany TypeFriendly 0.1.1, nowa wersja systemu generowania podręczników użytkownika. Koncentruje się on przede wszystkim na poprawie znalezionych błędów. Teraz nasze wysiłki kierują się już ku wydaniu wersji 0.2 i mamy nadzieję, że ukaże się ona znacznie szybciej :).

Nowa witryna Invenzzii

W końcu jesteśmy prawie gotowi do uruchomienia nowej strony Invenzzii. Wczoraj eXtreme odpalił ją na naszym serwerze i w chwili obecnej trwają testy oraz implementacja ostatnich funkcji. Witryna posiada zupełnie nowy design, logo (można je już podziwiać na wiki), nową, czytelniejszą nawigację oraz układ treści. Mamy nadzieję, że w przeciągu kilku następnych dni uda się ją udostępnić internautom.

OPT w Ohloh.net

Ohloh.net to nowatorski katalog projektów open-source założony przez dwójkę byłych pracowników Microsoftu, który nie tylko podaje informacje, że coś istnieje, ale pozwala również na szeroko rozumianą interakcję między użytkownikami i twórcami. Kilka dni temu założyłem w nim profil projektu Open Power Template 2. W chwili obecnej monitoruje on RSS-y, pozwala śledzić bieżący dziennik prac uaktualniany przez Jabbera (jeśli jesteś ciekaw, co aktualnie, w tej konkretnej chwili grzebiemy w kodzie, zaprenumeruj go :)) oraz przejrzeć statystyki dotyczące bieżącego kodu źródłowego (niestety tylko w repozytorium "trunk", które na razie się nie rozwija z wiadomych przyczyn). Jeśli posiadasz konto na Ohloh i jesteś użytkownikiem OPT, nie zapomnij zgłosić tego oraz ocenić projektu, gdyż m.in. dzięki temu projekt ma możliwość przyciągnięcia większej ilości użytkowników, co przełoży się na jakość samego kodu i dostępnych materiałów. Planujemy wydelegować na Ohloh również system downloadu tak, aby nie obciążać tym zadaniem naszego serwera i umożliwić zainteresowanym pobieranie projektu z rozmaitych mirrorów.

PS. Przypominam prenumeratorom RSS-a, żeby przepisali się na wersję anglojęzyczną bloga, gdzie nowe wpisy pojawiają się znacznie częściej!

OPT: Raport z prac

Zyx — pią, 19 wrz 2008 14:13:00 +0200

Przyszła pora na złożenie kolejnego raportu z prac nad OPT. W ostatnim czasie biblioteka wzbogaciła się o kilka nowych opcji, zamkniętych zostało również kilka błędów z bugtrackera. Z najważniejszych zmian można powitać (w końcu) tryb tekstowy figurujący w anglojęzycznej terminologii jako Quirks Mode. Pojawiła się nowa sekcyjna instrukcja: opt:selector, która zastępuje opt:paginator. Natomiast jeśli chodzi o funkcje, dodane zostało pełne wsparcie dla zmiany kolejności argumentów wykonywanej przez kompilator, co pozwala uniknąć tworzenia nakładek tylko po to, by ujednolicić wszystko.

Istotna zmiana dotyczy zasobów oraz dyrektywy sourceDir. Zrezygnowałem z pojęcia zasobu oraz interfejsu Opt_Resource_Interface na rzecz strumieni PHP, które również można dowolnie oprogramowywać, a przy okazji oferują one znacznie większe możliwości przy wykorzystaniu standardowych funkcji. Ich konfigurowanie odbywa się teraz poprzez dyrektywę sourceDir, która może teraz przyjmować jako wartość również tablicę asocjacyjną:

$tpl->sourceDir = array(
   'file' => '/sciezka/templates/',
   'db' => 'database://moja_baza/'
);

// system plików
$tpl->parse('szablon.tpl');

// baza danych
$tpl->parse('db:szablon.tpl');

Oczywiście we wspomnianym przykładzie trzeba ręcznie sobie strumień "db" utworzyć, a szczegóły znajdują się w dokumentacji PHP.

Nowa instrukcja, opt:selector, jest połączeniem sekcji oraz czegoś w rodzaju instrukcji "switch". Umożliwia proste definiowanie różnych wariantów wyświetlenia elementu, a wybór odpowiedniego następuje na podstawie jednego z pól elementu, domyślnie o nazwie "item". Od strony kodu, wygląda to bardzo podobnie do składni dawnej instrukcji opt:paginator, którą nawiasem mówiąc można bardzo łatwo odtworzyć:

<opt:selector name="strony">
  <opt:page>[ <a parse:href="$strony.adres">{$strony.numer}</a> ]</opt:page>
  <opt:active>[ <a parse:href="$strony.adres" class="active">{$strony.numer}</a> ]</opt:active>
  <opt:dots>...</opt:dots>
</opt:selector>

Całość współpracuje ze snippetami i posiada wszystkie inne właściwości sekcji, włącznie z opt:selectorelse, a nawet atrybutem opt:selector pozwalającym zmienić dowolny znacznik w tę instrukcję.

System dziedziczenia szablonów został wzbogacony o nową możliwość, mianowicie dołączanie dodatkowego szablonu, tylko że w przeciwną stronę (coś na wzór szablonów kompilacyjnych z OPT 1.x):

<!-- szablon.tpl -->
<opt:root include="inny_szablon.tpl">
  <p>Tutaj mamy jakiś kod...</p>
  <p>I możemy użyć snippetów z pliku inny_szablon.tpl</p>
  <opt:insert snippet="foo" />
</opt:root>

<!-- inny_szablon.tpl -->
<opt:root>
  <opt:snippet name="foo">
    Treść snippetu.
  </opt:snippet>
</opt:root>

Niestety, ta jedna rzecz musi być kompilowana rekurencyjnie, przynajmniej na razie, dlatego odradzam robienie jakichś super-długich łańcuchów w stylu "A dołącza B, który dołącza C, który dołącza D, który dołącza E" itd. Na pocieszenie dodam, że i tutaj został zamontowany wykrywacz nieskończonej rekurencji, który przerwie dołączanie, jeśli stwierdzi, że doprowadzi to do zapętlenia.

Ostatnia zmiana, to tryb quirks. Nie wiem, czy oczekiwany przez wszystkich, ale na pewno potrzebny, by OPT mógł sięgać tam, gdzie żaden zwykły kompilator XML nie sięgnie - do przetwarzania dowolnych dokumentów tekstowych. W skrócie - kompilator wyłapuje wtedy wyłącznie znaczniki należące do OPT (instrukcje), cała reszta traktowana jest natomiast jak zwykły tekst, podobnie jak to miało miejsce w OPT 1.1.x. Włączyć go można globalnie albo lokalnie dla pojedynczego szablonu:

$tpl->mode = Opt_Class::QUIRKS_MODE;
$tpl->parse('szablon.tpl', Opt_Class::OUT_SCREEN, NULL, Opt_Class::QUIRKS_MODE);

Najnowsza wersja kodu dostępna jest w SVN-ie, niedługo zaś pojawi się OPL 2.0.0-dev8.

OPT 2.0.0-dev7

Zyx — śro, 20 sie 2008 11:31:00 +0200

3 miesiące i 10 dni. Tyle zajęło przepisywanie dotychczasowego kodu OPT do nowej, lepszej wersji. Dziś w końcu uznałem, że dotarł on do punktu, w którym może aspirować do miana "dev7" i odpowiednia paczka znalazła się w działach "Download". Zmian jest sporo, głównie związanych z API biblioteki, którą teraz się nieco inaczej inicjuje. Poprawiłem też nieco kompilator, dodając do szablonów parę nowych możliwości oraz znacząco rozbudowałem dokumentację, która zresztą dołączona jest do wydania.

Zmiany w API

Nowe OPT zupełnie inaczej się inicjuje. Biblioteka nie jest w pełni samodzielna - aby ułatwić późniejszą integrację z innymi produktami serii OPL, powstał pakiet OPL zawierający podstawowe interfejsy oraz klasy. Wyekspediowana tam została m.in. obsługa konsoli debugowej oraz konfiguracji, ponadto dodaje on autoloader z prawdziwego zdarzenia. Kod OPL dołączony jest domyślnie do paczki z OPT, tak więc w dalszym stopniu wystarczy skrypt tylko rozpakować.

Aby nie być gołosłownym przedstawiam odrobinę kodu:

<?php
    // OPL Initialization
    require('../../lib/opl/base.php');
    Opl_Loader::setDirectory('../../lib/');
    Opl_Registry::setState('opl_debug_console', true);
    Opl_Registry::setState('opl_extended_errors', true);
    spl_autoload_register(array('Opl_Loader', 'autoload'));
    
    try
    {
    	$tpl = new Opt_Class;
    	$tpl->sourceDir = './templates/';
    	$tpl->compileDir = './templates_c/';
    	$tpl->charset = 'utf-8';
    	$tpl->compileMode = Opt_Class::CM_REBUILD;
    	$tpl->stripWhitespaces = false;
    	$tpl->setContentType(Opt_Class::HTML);
    	$tpl->setup();
    	
    	$tpl->assign('foo', 'Blok');
    	$tpl->parse('szablon.tpl');    
    }
    catch(Opt_Exception $exception)
    {
    	Opt_Error_Handler($exception);
    }
?>

Podstawowa inicjacja polega na załadowaniu głównego pliku biblioteki OPL, ustawieniu katalogu ze źródłami oraz autoloadera. Podany katalog musi zawierać zarówno foldery "opl", jak i "opt", gdyż inaczej nic się nam nie załaduje. Przy okazji możemy ustawić ogólne aspekty funkcjonowania wszystkich bibliotek OPL.

Jak widać, zmienione zostało nazewnictwo klas. Musiałem to zrobić, ponieważ taki zapis jest znacznie łatwiej parsować w autoloaderze, a przy okazji ucieszy fanów Zend Frameworka. Zmieniłem także nazwy niektórym metodom, np. powyżej widać, że httpHeaders() został przechrzczony na setContentType(). Jeśli zajrzymy do katalogu /lib/opt/, ujrzymy, że cały kompilator został zmodularyzowany, lecz i tak nie uchroniło to głównej klasy Opt_Compiler_Class przed zajmowaniem 65 KB na dysku twardym. Tego się już bardziej odchudzić po prostu nie da, ale możecie się pocieszać, że do tego pliku właściwie tylko ja muszę zaglądać i się w nim orientować :).

Tutaj mała uwaga: z OPT wyrzuciłem system cache. Doszedłem do wniosku, że zmuszanie tej biblioteki do zajmowania się jeszcze tym to lekkie przegięcie. Zamiast tego, pozostał bardzo prosty interfejs Opt_Cache_Hook_Interface, który należy sobie zaimplementować, aby podłączyć dowolny inny system cache. W ten sposób biblioteka łatwiej będzie integrować się z frameworkami, które często obsługują ten element we własnym zakresie. Gdyby ktoś jednak czegoś takiego nie miał, dotychczasowy kod niebawem będzie dostępny z powrotem... lecz jako osobna biblioteka, dla której jeszcze nie wymyśliłem nazwy.

Zmiany w szablonach

Szablony powinny działać bez większych problemów, aczkolwiek przy okazji przepisywania pchnąłem lekko do przodu prace nad instrukcjami. Pojawił się opt:tag, a opt:extend w pełni obsługuje już escape'owanie. Nie ma jeszcze opt:tree, opt:grid i opt:pagination, gdyż zmieniłem silnik sekcji i na razie zdążyłem go przetestować jedynie na opt:section. Sekcje są teraz o tyle fajne, że obsługują tzw. klasy uchwytów (hook classes), dzięki którym można nauczyć je obsługi dowolnego formatu danych, jaki nam się tylko zamarzy. W finalnym wydaniu nie będzie żadnych problemów, żeby sekcja potrafiła odczytywać dane np. bezpośrednio z obiektów PHP-Doctrine lub różnych elementów frameworków. Wszelkie sprawy związane z wybranym formatem są zupełnie niewidoczne po stronie szablonu:

<opt:section name="sekcja">
  .... {$sekcja.blok}
</opt:section>

Format natomiast wybieramy w skrypcie, np.

$tpl->assign('sekcja', $PDOStatement, 'PDO');

OPT zajmie się całą resztą, czyli dopasowaniem formatu do sekcji, korzystając z podanej klasy uchwytów. Klasy uchwytów mogą również modyfikować działanie zwyczajnych bloków, a twórcy instrukcji mogą korzystać z ich API w swoich produkcjach. W samych sekcjach pojawił się nowy atrybut: parent, który ułatwi tworzenie relacji. Przypomnę, że w dalszym ciągu sam fakt zagnieżdżenia jednej sekcji w innej tworzy między ich elementami relację przynależności, lecz jeśli domyślne zachowanie nam nie pasuje, możemy to zmienić:

<opt:section name="sekcja1">
   <opt:section name="sekcja2">
      <opt:section name="sekcja3" parent="sekcja1">
         ....
      </opt:section>
   </opt:section>
</opt:section>

Teraz elementy sekcji3 są przyłączone do sekcji1, a nie sekcji2. Ponadto, niedawno na forum Nowaker zaproponował, aby OPT zgodnie z logiką obsługiwał następujący blok sekcji: {$sekcja.blok.elementTablicy}. Wola jego stała się faktem i teraz OPT skanuje cały taki blok w poszukiwaniu nazwy dowolnej aktywnej obecnie sekcji.

Z innych nowości należy wymienić możliwość przypisania bloku do konkretnego szablonu. Dostęp jest realizowany poprzez $this.blok.

Dokumentacja

Spędziłem niedawno dużo czasu nad dokumentacją do OPT 2, a przede wszystkim nad przekonwertowaniem dotychczasowych wyczynów na TypeFriendly. Efekt jest następujący:

Na ukończeniu jest opis składni szablonów. Jedynie dwie instrukcje nie posiadają jeszcze dokumentacji i trochę funkcji.
Opisana jest większość API biblioteki.
Opisane są wszystkie aktualnie wykorzystywane i zatwierdzone dyrektywy konfiguracyjne.
Na ukończeniu są strony opisujące migrację z: PHP, OPT 1.x oraz Smarty'ego. Szczególnie w OPT 1.1.x ludzie się krzywili na ostatni z wymienionych opisów, że głupoty opisuje, zamiast konkretów. Teraz się poprawiłem i różnica jakościowo-ilościowa powinna być widoczna gołym okiem.

Dokumentacja dołączona jest do paczki, jest także możliwość przejrzenia jej on-line: on-line. Można także zapoznać się z zalążkiem angielskiej dokumentacji do OPL.

Zakończenie

Wykaz paczek można znaleźć tutaj. Na kolejną niestety znów przyjdzie trochę poczekać. W sobotę wyjeżdżam na tydzień, a zaraz później pochłonie mnie przeprowadzka do Krakowa i egzamin na uczelni, tak więc będę "wolny" dopiero za jakiś miesiąc. W tym czasie będę wrzucać jakieś mniejsze rzeczy na SVN i tam też będzie najświeższa wersja. Z drugiej strony, eXtreme już coś tam kombinuje z Open Power Classes, a konkretniej jego klasą "Opc_Paginator" do stronicowania. Myślę, że również Radzio w końcu zrobi swoje API dla Google Charts.

Na koniec należy uczciwie zaznaczyć, że OPT 2.0.0-dev7 przeszedł z LGPL 3 na zmodyfikowaną licencję BSD, co Wam ułatwi później dodawanie go do projektów komercyjnych, a wszystkim utrudni życie z przyjmowaniem zewnętrznych patchów i poprawek. Licencja LGPL była o tyle fajna, że z definicji obejmowała sobą również wszystkie poprawki i patche. Zmodyfikowana BSD tak nie robi i będę musiał odmawiać ich dodania do SVN bez podpisanego papierka ze zgodą na wydanie ich na podanej licencji, tak jak to robi Zend ze swoim Frameworkiem. Coś za coś.

OPT zbiera się do kupy

Zyx — pią, 25 lip 2008 19:13:00 +0200

Mija trzeci miesiąc, odkąd na tym blogu pojawiły się ostatnie wieści dotyczące Open Power Template'a 2.0.0. Czas ten nie był stracony, gdyż (pomijając sesję na uczelni) upłynął na ostrym przepisywaniu całego projektu. Wieści nie było, gdyż doprowadzenie nowego kodu do stanu uruchamialności nieco trwało, ale w końcu jest. Kompilator na nowo kompiluje szablony, i to już bez użycia rekurencji, zmory poprzednich wydań nawet, jeśli po części spowodowana ona była przez błąd w samym PHP :). Ale do rzeczy...

Począwszy od dev7, OPT będzie niekompatybilny wstecz z wydaniami dev1 do dev6, ale tylko od strony API. Zmiany w sumie nie są wielkie i dotyczą bardziej mechanizmu inicjowania biblioteki. Załączam przykładowy kod:

<?php 
    // OPL Initialization 
    require('../../lib/opl/base.php'); 
    Opl_Base::setDirectory('../../lib/'); 
    Opl_Base::setDebugMode(Opl_Base::DEBUG_ERROR); 
    spl_autoload_register(array('Opl_Base', 'autoload')); 
     
    try 
    { 
    	$tpl = new Opt_Class; 
    	$tpl->sourceDir = './templates/'; 
    	$tpl->compileDir = './templates_c/'; 
    	$tpl->charset = 'utf-8'; 
    	$tpl->compileMode = Opt_Class::CM_REBUILD; 
    	$tpl->stripWhitespaces = false; 
    	$tpl->httpHeaders(Opt_Class::HTML); 
    	$tpl->setup(); 
    	 
    	$tpl->assign('foo', 'I am a value.'); 
    	$tpl->parse('test_parser_1.tpl');     
    } 
    catch(Opl_Exception $exception) 
    { 
    	Opl_Error_Handler($exception); 
    } 
?>

Jak widać, inny jest mechanizm inicjalizacji. Biblioteki doczekały się wspólnego rdzenia, autoloadera, lepszej hermetyzacji, lecz trzeba uczciwie zaznaczyć, że lekko odbije się to na wydajności. Cena postępu - albo przypakowana i zap***jąca jak gepard biblioteka, albo zwinniejsza lecz nieco wolniejsza antylopa GNU. Dokładniej, mamy:

Autoloader
Mechanizm rejestrowania obiektów (coś na wzór Zend_Registry)
Tryb debugowania, w tym ujednolicona konsola debugowa. Jeśli ktoś będzie korzystać z np. 5 bibliotek OPL i włączy sobie takową, nie będzie mu wyskakiwać 5 pop-upów, tylko jeden zbiorczy.
Ujednolicone mechanizmy konfiguracji
Grupa wspólnych interfejsów: zasoby, cache, system tłumaczeń.
Obsługa błędów, w pełni wykorzystująca możliwości systemu wyjątków.

Zmianie uległ system nazewnictwa klas, teraz jest on bardzo podobny do tego, co widzimy w Zend Framework. Różnice dotyczą drobnych szczegółów umożliwiających pakowanie kilku klas do jednego pliku i obsługę takich sytuacji przez autoloader. Wiadomo na pewno, że zmieni się sposób obsługi interfejsu tłumaczeń. Wiem, że co najmniej jedna inna biblioteka także będzie go wykorzystywać, dlatego uznałem, że zamiast rejestrować obiekt odpowiedniej klasy w każdym projekcie z osobna, wykorzystam do tego rdzeń OPL:

Opl_Base::register('opl_translate', new MojaKlasaTlumaczen);

Wielu z Was z pewnością interesuje, co w tej chwili potrafi nowy kod OPT. Do jakiegokolwiek sensownego wykorzystania nie nadaje się on dalej, chociażby z tego powodu, że nie zaimplementowałem na nowo jeszcze żadnej instrukcji. Tak naprawdę dopiero przedwczoraj udało mi się skompilować pierwszy szablon, zaś dzisiaj dostrajałem kompilator wyrażeń po jego przeróbce na wersję nierekurencyjną. Zostało mu tylko 9 z 98 testów do zaliczenia i dotyczą one w zasadzie odwracania kolejności argumentów w funkcji oraz detekcji niektórych błędów składni związanych z nawiasami. Czyli takie techniczne duperele, które można naprawić w pół godziny przy dobrych wiatrach. Przepisywanie kompilatora poszłoby znacznie szybciej, ale postanowiłem, że skoro już przepisuję wszystko, pozbędę się do końca rekurencji. I dopiąłem swego, opanowując do perfekcji iteracyjną wersję przeszukiwania drzewa w głąb, hehehe. OPT nie jest już wrażliwy na głębokość jakiegokolwiek drzewa i na komunikat "Nesting level too deep" trzeba sobie zasłużyć zbyt pazernym własnym skryptem.

Kod wraz z polską dokumentacją API kompilatora jest do ściągnięcia z repozytorium SVN. Trzymajcie kciuki za dev7...

TypeFriendly 0.1.0 wydane

Zyx — śro, 23 lip 2008 10:29:00 +0200

W końcu zakończyliśmy tłumaczenie dokumentacji na język angielski i gotowy od kilkunastu dni kod wreszcie został wydany jako pierwsza wersja systemu generowania dokumentacji TypeFriendly. Można ją pobrać w dziale Pliki na stronie głównej. Dokumentacja dostarczana jest w wersji źródłowej i robi jednocześnie za przykład, dlatego nie obawiajcie się, że czegoś brakuje. Wszystkie informacje potrzebne do zbudowania HTML-owej wersji dokumentacji znajdują się w pliku /info/README.txt - jest to kwestia wklepania jednego polecenia z konsoli. Trwają już prace nad nową stroną Invenzzii i znajdzie się tam miejsce na dokumentację on-line.

O TypeFriendly pisałem dokładniej w poprzednim wpisie i tam znajdziecie więcej informacji. Tutaj dodam tylko, że eXtreme odwalił kawał świetnej roboty, wyczerpująco opisując po polsku całą składnię Markdown z dziesiątkami przykładów. Z pewnością opis ten przyda się wielu osobom.

TypeFriendly

Zyx — śro, 02 lip 2008 20:51:00 +0200

Z eXtremem ciężko pracujemy, by pierwsza wersja ujrzała w końcu światło dzienne i jesteśmy już bardzo blisko. W związku z tym chciałbym bliżej przedstawić ten projekt, który z pewnością powinni docenić inni programiści, autorzy rozmaitych skryptów i poszukujących sensownego narzędzia do generowania dokumentacji. Pomysł na napisanie TypeFriendly zrodził się w mojej głowie po nieudanych zmaganiach z dodaniem paru niezbędnych rzeczy do parsera XSLT dla DocBook. Widać choćby po dokumentacji PHP, co można z tym zrobić (kolorowanie składni, wiele różnych formatów, ogromna ilość pomocnych znaczników), ale nie dajmy się zwariować. To są wręcz tygodnie siedzenia, by osiągnąć podobny efekt. Pomijam już fakt, że byłby on słabo przenośny... wolałem poświęcić te tygodnie na stworzenie czegoś bardziej przydatnego.

TypeFriendly jest więc systemem generowania dokumentacji, ale innego pokroju niż np. phpDocumentor, który skanuje kod źródłowy Twojego projektu i robi opisy do wszystkich napotkanych klas i funkcji. Tutaj rozdziały piszemy sami od A do Z i sami układamy je w żądanym porządku, podobnie jak w DocBooku. Na tym podobieństwa się kończą, ponieważ TF z definicji zawiera już wszystko, co potrzeba, a został tak zaprojektowany, by dokumentację pisało się intuicyjnie.

Cechy:

W TF dokumentację tworzymy, pisząc tekst w zwykłych plikach tekstowych, korzystając ze składni Markdown. Dodatkowo, na początku umieszczamy różne dodatkowe tagi, dzięki którym możemy ustawić tytuł, informacje o wersji czy np. listę "Zobacz także".
TF automatycznie układa nasze pliki w rozdziały na podstawie ich nazwy i sortuje alfabetycznie. Jednak zawsze możemy wprowadzić własny układ - w pliku "ze wskazówkami do sortowania" definiujemy własną kolejność. To, czego tam nie zapisaliśmy, pozostanie alfabetycznie.
TF posiada wbudowaną opcję kolorowania składni kodu źródłowego.
TF samodzielnie generuje pełną nawigację pomiędzy rozdziałami, podobnie jak spis treści.
TF jest zaprojektowany do rozwijania dokumentacji w kilku językach. Posiada nie tylko możliwość przetłumaczenia tekstów interfejsu, ale także proste narzędzie do sprawdzania aktualności "pochodnych wersji językowych".
TF umożliwia wygenerowanie wyjściowej dokumentacji w formacie XHTML (w wersji z wieloma podstronami lub na jednej). Przygotowujemy też specjalny format umożliwiający szybki import dokumentacji do bazy danych i udostępnienie np. możliwości jej komentowania on-line.
TF oprawia dokumentację w bardzo ładną szatę graficzną, którą możecie podziwiać np. w dokumentacji do OPTv2 (robionej właśnie w TF).

Wprawdzie wydania żadnego jeszcze nie było, ale chętni mogą już teraz połączyć się z naszym nowym SVN-em i ściągnąć projekt stamtąd. Link do polecenia checkout jest następujący: http://svn.invenzzia.org/svn/typefriendly/trunk/ - serdecznie zachęcam już teraz do testów. W repozytorium jest plik README oraz będąca już na ukończeniu dokumentacja w języku polskim.

Żeby nie być gołosłownym, pokażę co ciekawsze opcje na przykładzie paru fragmentów. Pierwszym z nich będzie jeden z plików manuala OPTv2 (library.optnode.txt):

Title: Klasa optNode
ShortTitle: optNode
Status: abstract
Extends: library.optcodebuffer
ExtendedBy:
 - library.optscannable
 - library.optcharacterdata
 - library.optexpression

----
Abstrakcyjna klasa węzła. Zapewnia obsługę podstawowych własności, jak rodzic i typ.

Pola klasy
----------
Wszystkie pola klasy są chronione.

 Nazwa         | Typ       | Opis
---------------|-----------|---------------------------------------
 $type         | Integer   | Numeryczny identyfikator typu.
 $parent       | optNode   | Rodzic węzła.

Dostępne identyfikatory typów:

1. `OPT_CDATA_NODE` - `optCharacterData`
2. `OPT_TEXT_NODE` - `optText`
3. `OPT_EXPRESSION_NODE` - `optExpression`
4. `OPT_ELEMENT_NODE` - `optElement`
5. `OPT_ROOT_NODE` - `optRoot`

Na początku pliku znajduje się nagłówek, w którym umieszczamy tzw. tagi. Tam właśnie określany jest właściwy tytuł, a w tym wypadku również zależności między klasami. Zauważmy, że do innych klas odwołujemy się, podając identyfikatory rozdziałów, które je opisują. Oczywiście każdy z tych "obiektowych" tagów posiada także wersję, gdzie nazwy możemy wpisać bezpośrednio (np. gdybyśmy dziedziczyli po klasie wbudowanej w PHP). Dostępnych tagów jest więcej. Przykładowo, można bardzo łatwo zrobić listę "Zobacz także", która wygląda mniej więcej tak:

SeeAlso:
 - chapter.text1
 - chapter.text2
 - chapter.text3

Gdy lista tagów dobiegnie końca, przechodzimy do właściwej treści pisanej w formacie Markdown. Autor zaprojektował go bazując na formatowaniu używanym powszechnie w rozmaitych plikach tekstowych czy e-mailach (można powiedzieć, że napisał parser do składni, która sama wyewoluowała :)). Tekst źródłowy jest przez to niesamowicie czytelny i na dobrą sprawę czyta się go niewiele gorzej, niż gdyby był faktycznie sformatowany. Trochę gorzej, gdy ktoś jest przyzwyczajony już do jakiejś składni wiki, bo MD nie zawsze takowe wiki przypomina (zwróćcie uwagę chociażby na sposób wykonania tabelki). Jednak można się dość łatwo przyzwyczaić - w Markdownie klepiemy również teksty na naszą stronę i muszę powiedzieć, że jest to całkiem przyjemne narzędzie, które z pewnością ujrzycie w niejednym produkcie Invenzzii. Jedyny mankament jest taki, że oficjalny parser obsługuje tylko jeden słuszny format - XHTML. O LaTeXu czy innych na razie trzeba niestety zapomnieć, ale na to już ostrzymy sobie zęby :).

Najgorszy problem przy tworzeniu dokumentacji to nawigacja. Linki "Poprzedni/Następny/W górę" załatwia TypeFriendly, sekcję "Zobacz także" robimy za pomocą znaczników, a co z klikalnymi nazwami funkcji i klas? Myślałem nad tym i wymyśliłem rozwiązanie genialne w swej prostocie. W dodatkowym pliku tekstowym definiujemy kawałki tekstów, które mają zostać zamienione na odnośnik. Przykładowo, wpisujemy tam, że `optClass::parse()` ma, oprócz nadania mu standardowego formatowania, zostać zmienione na odnośnik do library.optclass.parse i już się niczym więcej przejmować nie musimy. Niestety, do takich przeróbek Markdowna jeszcze nie doszliśmy i pierwsza wersja tego bajeru nie będzie jeszcze zawierać. Wszystko w swoim czasie.

TypeFriendly obsługiwany jest w całości z konsoli systemu operacyjnego. Testowaliśmy go na Linuksie i Windowsie - w obu systemach działa póki co bez zarzutów. Do działania potrzebny jest wyłącznie interpreter PHP. W połączeniu z intuicyjną składnią oraz wbudowanym wsparciem dla wielojęzyczności powinno to zachęcić wielu ludzi do pomocy przy tłumaczeniach, rozwoju oryginalnej wersji, a nawet tworzeniu nowych wyjść. Przetworzenie naszych plików na XHTML to kwestia wklepania jednego polecenia:

php ./typefriendly.php -l pl -o xhtml ./sciezka/do/dokumentacji/

Porównajmy to z DocBookiem - sam format jest nieco bardziej rozwlekły, ale stosunkowo łatwy do opanowania. Do konwersji jednak potrzeba trochę więcej narzędzi - DTD, sam zestaw DocBok XSL Stylesheet i wreszcie sam parser XSLT. Jego wybór jest nie bez znaczenia, gdyż ze zwykłym, szybkim i łatwym w użyciu xsltproc nie dostaniemy np. kolorowania składni. Użytkownicy Windowsa natomiast mają kompletnie prze.... jeśli autor projektu dodatkowo zrobi na DocBooku framework do budowania dokumentacji, w którym część narzędzi napisana jest w... Bashu. Nie trzeba takich kwiatków daleko szukać - jak myślicie, co odpowiada za dokumentację PHP? :) Z chęcią bym do niej coś popisał, gdyby choć raz udało mi się uruchomić ichniejszy framework i cokolwiek przetworzyć.

SVN uruchomiony

Zyx — pon, 30 cze 2008 08:08:00 +0200

Niestety porządna konfiguracja systemu kontroli wersji na naszym serwerze nie jest tak łatwa i przyjemna, jak na Sourceforge.net, aczkolwiek w końcu znalazłem czas i pomysł, jak to wykonać. Repozytorium działa pod adresem http://svn.invenzzia.org/ z tym, że nie została jeszcze zainstalowana żadna porządna jego przeglądarka. W ciągu dnia wrzucę tam aktualny kod przebudowywanych Open Power Libs oraz bliskie ukończenia pierwszej wersji 0.1.0 TypeFriendly do tworzenia dokumentacji, zaś wszystkie informacje odnośnie połączenia znajdą się na stronie głównej.

OPT 2.0.0-dev6

Zyx — sob, 10 maj 2008 14:15:00 +0200

Do ściągnięcia dostępna jest wreszcie kolejna wersja rozwojowa OPT. Jej zawartość opisałem w poprzednim wpisie, dlatego tu dodam tylko, że wbrew zapowiedziom, nie ma jeszcze instrukcji opt:grid z powodów, które zaraz wyjaśnię. Ponadto nie da się jeszcze ustawiać statusu escape'owania dla pojedynczego szablonu, ale takowy z globalnej konfiguracji i ustawień wyrażenia w klamerkach już działa ładnie. Za to dodałem implementację instrukcji opt:capture i częściową opt:cycle. Polskich użytkowników z pewnością ucieszy informacja, że podczas długiego weekendu doprowadziłem do względnego porządku nasz nowy system dokumentowania TypeFriendly i OPT 2 ma już nową, ładną dokumentację :)

Dostałem niedawno parę pytań, czy można już powoli zacząć używać OPT 2 w rzeczywistych projektach. Odpowiadałem, że większość rzeczy już jest gotowa i w nich raczej zmian nie będzie, aczkolwiek nic nie gwarantuję. W kolejnym devie okaże się, że dobrze zrobiłem, nic nie gwarantując, ponieważ OPT wymaga paru drastycznych zmian.

Sekcje

Od strony szablonu wszystko zostaje po staremu, za to zmieni się trochę interfejs skryptowy. W OPT już od pewnego czasu istnieją elementy pozwalające uniezależnić szablony od interfejsów skryptu, dzięki czemu zmiany w silniku nie muszą iść w parze z przepisywaniem wszystkich szablonów, co jest bolączką innych parserów (w tym Smarty'ego, gdzie na forach widziałem już takie cudaczne konstrukcje, że aż głowa może rozboleć). Sekcje już od dawna stanowiły jedną z nich, gdyż skrywały sposób łączenia sekcji podrzędnych i nadrzędnych, a także zawierały obsługę generowania danych "w locie" oraz alternatywny format tablic. Wszystko to było jednak zakodowane na sztywno w kodzie, a dodanie doń czegoś nowego jest kłopotliwe. Przecież formaty danych mogą być jeszcze inne, stąd pomysł, by wprowadzić modularyzację samych sekcji. Instrukcja jako taka zapewnia wyłącznie szkielet podpinający wszystko, gdzie trzeba w drzewku XML. My natomiast za pomocą pluginów możemy łatwo nauczyć sekcję, żeby np. pobierała dane np. bezpośrednio z PHP-Doctrine czy też iterowała po obiekcie :). Zastosowanie:

<opt:section name="foo">
 {$foo.bar}
</opt:section>

Nie musimy się już martwić, czy element foo jest obiektem, a my odwołujemy się do pola "bar", czy też tablicą. Po stronie szablonu foo.bar oznacza blok "bar" w elemencie "foo", natomiast zadaniem skryptu jest nadanie mu jakiegoś konkretnego znaczenia (tablica, obiekt itd.). Analogicznie, nie obchodzi nas również budowa danych dla sekcji jako takiej - czy to jest sekcja dynamiczna, czy tablica w jakimś formacie, czy też obiekt... Wszystko będzie można łatwo zaprogramować.

Po stronie skryptu pojawi się metoda w stylu setSectionType służąca do określenia, jak OPT powinien przetworzyć daną sekcję:

$tpl -> setSectionType('foo', 'mojPluginObiektowy');
$tpl -> assign('foo', new obiektPoKtorymMoznaIterowac);

Gdy nie określiliśmy typu, OPT wybierze standardową postać tablicową.

Zalety:

Po stronie szablonu już nas kompletnie nic nie obchodzi. Sekcje możemy kopiować metodą Ctrl+C, a one bez zmiany jednego znaku w pełni dostosują się do sytuacji w nowym szablonie bez naszej ingerencji.
Koniec narzekań, czemu sekcje nie obsługują czegośtam, albo że format jest debilny :)
Jednolita kontrola obsługi po stronie skryptu.

Modularyzacja kompilatora

Kompilator zostanie rozbity na większą ilość mniejszych plików, gdyż jest on ładowany raz na jakiś czas i zyski ze zbicia wszystkiego w dwa mega-pliki są znikome. Wpływ na skrypty korzystające z OPT powinien być zerowy.

Zmiany w obsłudze błędów

Niebawem pojawi się Open Power Classes 1.0.0-dev1, a w planach są też inne projekty. Jeśli ma to być coś więcej, niż tylko zbiór bibliotek o podobnej nazwie, trzeba ujednolicić niektóre elementy. Oczywiście wspólną częścią jest obsługa błędów - każda z bibliotek musi więc zawierać taki sam plik z odpowiednim współdzielonym kodem, który może być używany przez wszystkie z nich jednocześnie. Jeżeli poza przechwytywaniem wyjątku optException i kierowaniem go do optErrorHandler() nie robisz z nim nic więcej, wtedy zmiana nie powinna Cię dotknąć.

Poprawa hermetyzacji klasy głównej!!

Rzecz musi zostać ujednolicona, żeby nie powstała kolejna niedorzeczność pod postacią "dlaczego jedne dane są chronione, choć potrzebuje ich kompilator, a inne nie". Jeśli odwoływałeś się wyłącznie do pól konfiguracyjnych, zmiana nie powinna Cię dotknąć.

Nowa dokumentacja

Jak pisałem, wreszcie OPT 2 posiada nową, zapowiadaną jakiś czas temu dokumentację. Za jej generowanie odpowiada napisany w PHP silnik TypeFriendly obsługujący m.in. kolorowanie składni. Zostanie on wydany na licencji GNU GPL, gdy tylko uporządkuję trochę jego kod i napiszę dokumentację pokazującą, jak z niego korzystać. Tak czy inaczej jego obecność pozwoli nawet na takie bajery, jak wersja on-line dokumentacji z komentarzami użytkowników.

Co nowego w OPT

Zyx — nie, 27 kwi 2008 13:06:00 +0200

Minęło już trochę czasu od ostatnich wieści z frontu, dlatego naprawiam zaległości. Za jakiś tydzień pojawi się kolejna wersja developerska. Prace posunęły się jeszcze dalej do przodu. Obejmują one zaimplementowanie kolejnych "brakujących" elementów, a także (co powinno niektórych ucieszyć) - zmniejszanie zużycia zasobów serwera w trakcie kompilacji. Zobaczmy zatem, z czym będziemy mieli do czynienia.

Pochodne sekcji

Nowe pochodne sekcji: opt:tree oraz opt:grid. Pierwszą z nich znamy już z OPT 1 i służy do renderowania drzew. Zmianie uległa jej składnia, ponieważ na nowym kompilatorze nie da się tak beztrosko szlachtać HTML-a, nie domykając znaczników. Z drugiej strony wymusiło to wprowadzenie bardziej czytelnego formatu. Popatrzmy na to:

  <opt:tree name="mytree">
  	<opt:list><ul><opt:content/></ul></opt:list>
  	<opt:node><li>{$mytree.title} <opt:content /></li></opt:node>  
  </opt:tree>

Czyli innymi słowy - definiujemy wygląd listy, definiujemy wygląd węzła i mówimy, w którym miejscu mogą się one zagnieżdżać. Algorytm przetwarzania takiego drzewa, jaki OPT wstawia do skompilowanego szablonu, opiera się na pewnej sztuczce, ale jest skuteczny. Oczywiście format danych jest taki sam, jak w poprzednich wersjach - do danych sekcji musimy dołączyć pole "depth" z głębokością elementu.

Całkowitą nowość stanowi opt:grid. Jego działanie opiszę na przykładzie. Z pewnością każdy widział internetowe galerie zdjęć. Miniaturki są tam ułożone w tabelce, np. po 5 w jednym wierszu. Rzadko się zdarza, by liczba elementów była wielokrotnością tejże piątki, dlatego przeważnie część ostatniego wiersza będzie pusta. Można to rozwiązać za pomocą CSS-a (sposób podał niedawno na naszym forum eXtreme), lecz czasem po prostu trzeba narysować rzeczywistą tabelę. Sam algorytm opiera się na sprawdzaniu reszty z dzielenia indeksu, ale dlaczego ma się tym w ogóle zajmować szablon? Zgodnie z filozofią OPT, powinniśmy przecież mówić tylko, co chcemy zrobić, a nie instruować krok po kroku - JAK. Stąd też instrukcja opt:grid:

<table>
<opt:grid name="tabelka" cols="3">
 <tr>
  <opt:item>
   <td><img parse:src="$tabelka.zdjecie"/></td>
  </opt:item>
  <opt:emptyItem>
   <td>&nbsp;</td>
  </opt:emptyItem> 
 </tr>
</opt:grid>
</table>

Instrukcją obejmujemy cały wiersz, a w nim dodatkowo zaznaczamy, jak mają się wyświetlać poszczególne komórki. Mamy tu dwa warianty. opt:item mówi, jak wygląda komórka z danymi, zaś opt:emptyItem - jak komórka bez danych. Wprawieniem tego w ruch zajmuje się OPT. Instrukcja gridu przyjmuje identyczny format danych, jak zwykła sekcja.

Skoro przy sekcjach jesteśmy, zmienia się składnia wywołań z "else" w nazwie. Dotąd były to znaczniki bez treści, wizualnie rozdzielając zawartość rodzica na dwie części. Okazało się jednak, że z paru powodów muszę zrezygnować z takiego zapisu na rzecz następującej konstrukcji:

<opt:section name="foo">
  Tutaj treść sekcji

  <opt:sectionelse>
      Tutaj to, co się dzieje, gdy lista jest pusta.
  </opt:sectionelse>

</opt:section>

Miejsce umieszczenia tego znacznika jest teraz bez znaczenia - OPT sam sobie go przesunie tam, gdzie trzeba, żeby wygenerowany z tego kod PHP miał sens.

Automatyczne escape'owanie OPT 1 w ogóle nie zajmował się escape'owaniem danych ze skryptu podczas ich wyświetlania. Zmianę jakościową wprowadzi teraz OPT 2, zaś twórca szablonów będzie mieć nad tym procesem pełną kontrolę. Założenia są następujące:

Wszystko, co próbujemy wyświetlić we wnętrzu atrybutu XML, musi być escape'owane przez htmlspecialchars() i od tego nie ma "zlituj" w trybie XML.
Wyrażenia w klamerkach domyślnie także są escape'owane, lecz nad tym procesem programista ma kontrolę. Status escape'owania może być zdefiniowany globalnie w konfiguracji OPT, w głównym znaczniku szablonu (jego zasięg obejmie wtedy tylko aktualny szablon) lub też pojedyncze wyrażenie za pomocą dwóch modyfikatorów e lub u wstawionych na jego początek. Przykłady: {e:$blok} oraz {u:$blok}. Oczywiście działa to inteligentnie, tzn. jeśli włączyliśmy escape'owanie globalnie, dodanie modyfikatora nie spowoduje, że blok zostanie przetrawiony dwukrotnie. Dostępna będzie również specjalna funkcja esc() pozwalająca na escape'owanie tylko konkretnego elementu wyrażenia.

System językowy OPT 2 zawiera zmieniony interfejs do integracji z systemem językowym, lecz dotąd nie był on w ogóle nigdzie przez kod wykorzystywany. Obsługa pojawi się w najnowszym devie, w składni identycznej, jak w OPT 1.

System stronicowania Zmianom uległ także interfejs integracji z systemem stronicowania oraz po części składnia instrukcji opt:pagesystem. W tej chwili szczegóły jeszcze dopracowujemy. Obie te rzeczy pojawiają się teraz dlatego, gdyż równolegle z OPT 2.0.0-dev6 ukaże się pierwsza wersja developerska nowego projektu o nazwie Open Power Classes. Jest to zbiór niewielkich klas o różnych zadaniach, które są zbyt małe, by je pakować i szumie ogłaszać jako kolejne projekty (każdy projekt Open Power XXX musi posiadać unikalny kod literowy, a ilość liter w alfabecie jest niestety ograniczona :)). Na dzień dobry znajdą się tam dwie klasy:

opcPagination - system stronicowania kompatybilny z OPT autorstwa eXtreme'a.
opcCharts - API dla Google Charts stworzone przez Radzia

W późniejszych wersjach dojdzie jeszcze m.in. system językowy.

Optymalizacje Optymalizacji jest kilka:

Zużycie pamięci. Polega ono na wyszukiwaniu miejsc, w którym skrypt mógłby zwalniać pamięć i obiekty, ale jednak tego nie robi. W kompilatorze rezygnuję również z domyślnej inicjacji pustych tablic, gdyż każda taka struktura to strata rzędu przynajmniej 400 bajtów, a często nie są one potrzebne.
Głębokość rekurencji - jakiś czas temu pisałem o zbyt szybkim zjadaniu stosu przez OPT z powodu użycia rekurencyjnego algorytmu przetwarzania węzłów drzewa. W OPT 1 nie było z tym problemu, gdyż węzłami były jedynie instrukcje, zaś tutaj domagał się tego każdy znacznik HTML. Wdrożyłem dlatego algorytm hybrydowy, który robi rekurencyjne wywołanie tylko wtedy, gdy faktycznie jest ono do czegoś potrzebne, zaś w przeciwnym wypadku wykorzystuje mechanizm kolejki u jednego z już pracujących przetwarzaczy. W praktyce każdy znacznik, który nie jest bezpośrednio obsługiwany przez OPT, przetwarzany jest teraz w ten sposób, dzięki czemu oszczędzamy stos. Również niektóre instrukcje mogą tak pracować.

Inne Nowy dev będzie zawierać także trochę pomniejszych poprawek. Zacząłem w końcu tworzyć zestaw testów dla poszczególnych instrukcji, dzięki czemu jestem w stanie sprawdzić zachowanie biblioteki dla znacznie większej liczby możliwych kombinacji i wychwycić rozmaite kretyńskie zachowania.

PS. Pewnie niektórzy zauważyli, że mój blog zniknął z sieci. Informuję, że niebawem zostanie on przywrócony pod dotychczasowym adresem, zatem bez obaw.

Wymagania OPT

Zyx — sob, 05 kwi 2008 09:32:00 +0200

Na bugtrackerze pojawiło się ostatnio zgłoszenie informujące o błędzie "Nesting level too deep - recursive dependency" przy próbie uruchomienia jednego z przykładów w najnowszej wersji rozwojowej OPTv2. Po dokładniejszych oględzinach wyszło na jaw, że winny jest zbyt wyśrubowany limit ustawiony w konfiguracji PHP przez autora zgłoszenia (ponad czterokrotnie mniejszy, niż wartość domyślna). Jednak przy tej okazji myślę, że warto trochę bardziej przyjrzeć się temu, jakie wymagania postawi nowy OPT interpreterowi i wyjaśnić kilka spraw z tym związanych.

Optymalizacje, jakie implementuję w OPT, dotyczą przede wszystkim głównej klasy parsera oraz kompilatora. Pierwsza z nich, jako część kodu ładowana każdorazowo, ma narzucone bardzo wyśrubowane wymagania. Nie ma tutaj wyszukanych algorytmów, dlatego przyspieszanie działania dotyczy:

Zmniejszania objętości kodu.
Minimalizacji odwołań do dysku twardego.
Wykorzystaniem najwydajniejszych elementów języka.

Chodzi o to, aby załadowanie biblioteki było jak najmniej obciążające dla interpretera, a w konsekwencji używającego ją skryptu.

Nieco inaczej sprawa wygląda z kompilatorem, który ładowany jest tylko okazjonalnie, zatem może być obszerny i rozbity na więcej składowych (aczkolwiek bez zbędnej przesady). Tutaj kluczową rolę zaczynają odgrywać limity ustawione w konfiguracji PHP, gdyż przy szczególnie złych wiatrach może się zdarzyć, że kompilator zużyje wszystkie dostępne zasoby. Niestety, powiększona funkcjonalność kosztuje, a skoro użytkownicy pragnęli mieć parsowanie także XML-owych znaczników, muszą liczyć się z tym, że dla każdego z nich trzeba teraz tworzyć obiekt węzła i dla każdego z nich trzeba wykonać trochę prac przygotowawczych. Moją rolą jest tutaj uczynienie tego zużycia tak małego, jak to tylko jest możliwe.

Elementy, które mogą się wyczerpać podczas używania kompilatora to:

Stos
Pamięć operacyjna

Wykorzystywane algorytmy, z racji operowania na strukturze zwanej drzewem, korzystają dość mocno z rekurencji, przez co liczba aktualnie wykonywanych funkcji i metod szybko rośnie. W PHP domyślnym limitem narzuconym na głębokość rekurencji jest 64 i do pracy z OPT najlepiej zostawić go na takim poziomie, a już na pewno nie bawić się w jego zmniejszanie do jakichś śmiesznych wartości pokroju "16", co zresztą zaszkodziłoby nie tylko OPT, ale i wielu innym skryptom :). Każdą rekurencję można jednak zastąpić iteracyjną wersją, która może i nie zużywa mniej pamięci, ale przynajmniej jest niezależna od wspomnianego limitu. Odpowiednie przeróbki wprowadzone są już teraz do wielu metod, które zamiast wywoływać się rekurencyjnie, korzystają np. z kolejek. Najgorzej sprawa wygląda z dwoma algorytmami:

Przetwarzanie drzewa przez procesory instrukcji
Kompilacja wyrażeń

W pierwszym z nich mamy następującą sytuację: odnajdujemy węzeł jakiejś instrukcji i musimy go przetworzyć. Kierujemy go więc do odpowiedniego procesora (klasa pochodna od optInstruction), on generuje do niej kod PHP i decyduje, co zrobić z dziećmi danego węzła. Zazwyczaj decyduje się na ich obróbkę. Tu wkracza wywołanie rekurencyjne i cały proces powtarza się od początku. Trudności to rozrzucenie całego algorytmu po mnóstwie klas, które mogą być na dokładkę oficjalnie rozbudowywane przez zainteresowanych programistów. Co więcej, niektóre instrukcje wymagają, aby przetwarzanie rozpoczęło się natychmiast wraz z wywołaniem metody przetwarzającej, ponieważ od tego, jaki kod PHP wygenerują sobie potomkowie, zależy dalsza obróbka ich rodzica. Eliminuje to w oczywisty sposób kolejkę. Stworzenie eleganckiego zamiennika byłoby proste, gdybyśmy mieli dostęp do programowania niskopoziomowego, lecz tak nie jest.

Popatrzmy, jak to wpłynie na kompilację. Mamy jakiś rozbudowany szablon, w którym znaczniki zagnieżdżone są aż do głębokości 30. Sam OPT z kompilatorem może w porywach zużyć dodatkowe 10 zagnieżdżeń, zaś w najgłębszym miejscu jest na dokładkę jeszcze skomplikowane wyrażenie z nawiasami. Zatem całość zużyje ok. 45 wywołań, z dostępnych 64, czyli ponad 70% limitu! I choć przypadek jest dość pesymistyczny, bo prawdę mówiąc mi się nigdy nie zdarzyło, żebym musiał robić jakiś plik HTML z 30-ma zagnieżdżonymi znacznikami, to jednak pokazuje on, że kompilacja to proces wymagający.

Skoro bez brzydkich sztuczek, które nie spodobałyby się na pewno twórcom instrukcji, nie da się usunąć rekurencji, to jak sobie z tym poradzić? Wpadłem na pomysł, gdzie rekurencji nie usuwamy, lecz za to drastycznie ją ograniczamy. Korzystam tutaj z faktu, że natychmiastowy dostęp do tego, co wykompilowały dzieci, jest potrzebny tylko kilku instrukcjom, natomiast np. zwyczajnym znacznikom XML/HTML jest to po grzyba, gdyż one i tak nie wiedzą, co z tym zrobić. Mamy więc sporą szansę, że gdy wybierzemy losowy węzeł z drzewa, trafimy na taki, któremu rekurencja jest niepotrzebna. Dlaczego więc nie zaproponować dwóch wersji algorytmu: imperatywnej i rekurencyjnej, w zależności od potrzeb? Tam, gdzie instrukcje robią czary, mogą sobie zażyczyć prawdziwej rekurencji, natomiast normalnie wszystko idzie poprzez kolejki. Wtedy przy dobrych wiatrach, takie drzewo o głębokości 30, może być przetworzone na jeden raz, bez żadnej rekurencji! W normalnych warunkach natomiast zejdzie ona na głębokość 3, 4, co jest już akceptowalne.

Druga sprawa dotyczy zużycia pamięci. Wprawdzie nie jest tu aż tak tragicznie, ale da się zauważyć wyraźne zwiększenie zapotrzebowania w porównaniu z kompilatorem do OPT 1.x, nawet pomimo wykorzystania patentów z tamtego projektu. Większość tego zajmuje oczywiście samo drzewo. Mierzyłem ostatnio zużycie pamięci generowane przez pojedyncze obiekty węzłów i wyniki wahały się w granicach 2 kilobajtów na pusty obiekt bez udziwnień, natomiast przy dodaniu atrybutu, rosło średnio o kilobajt. Gdy instrukcje zaczną dopisywać do buforów kod PHP, sprawa się pogarsza, ale dotyczy to tylko wybranych węzłów w całym szablonie. Okazuje się, że możemy tu trochę zaoszczędzić. Obiekty wykorzystują kilka tablic, które dotąd były automatycznie inicjowane na samym początku, na przykład:

abstract class optScannable extends optNode implements Iterator
{
	protected $subnodes = array();

W większości węzłów część tych tablic stoi pusta, więc nie ma sensu, aby były one cały czas stworzone. Poprawiłem kod tak, aby odpowiednie metody tworzyły pustą tablicę dopiero, gdy będzie ona potrzebna, zaś z deklaracji wywaliłem dopiski = array(). Dało to ciekawy efekt: na jednej tak wywalonej tablicy zacząłem oszczędzać 400 bajtów. Nowe rezultaty pomiarów są następujące:

Węzeł bez atrybutów: 1400 b.
Węzeł z jednym atrybutem: 2350 b.

Dodatkowa oszczędność może zostać osiągnięta dzięki pamiętaniu o kasacji niepotrzebnych już danych o dużej objętości, jak np. treść szablonu.

O czym należy pamiętać, korzystając z nowego OPT, jeśli chodzi o kwestie wydajnościowe:

Z wyśrubowanymi limitami kompilator na pewno będzie się wysypywać. Myślę, że 16 MB pamięci dla skryptu (aktualny domyślny limit) to wartość na tyle rozsądna, by kompilator mógł odwalić dobrą robotę nawet z całkiem rozbudowanym szablonem oraz jednocześnie aby zostało coś dla skryptu.
Parsowanie szablonu najlepiej uruchamiać na końcu, kasując przedtem w skrypcie niepotrzebne już dane o dużej objętości.
Kompilacja szablonów z dziedziczeniem może wymagać więcej pamięci, szczególnie przy nadpisywaniu już istniejących snippetów (parser musi trzymać w pamięci również nadpisane wersje).
Niezaimplementowany jeszcze tryb tekstowy (quirks mode) wymagać będzie znacznie mniej pamięci dzięki uproszczonemu drzewu (brak znaczników XML).
Kompilacja uruchamiana jest raz na długi czas; podczas normalnej pracy można spokojnie zapomnieć o istnieniu tych wszystkich wymagań.

Myślę, że ten wpis dość dobrze pokazuje, o ilu aspektach trzeba pamiętać, pisząc porządną bibliotekę. Klucz to wiedzieć, na ile można sobie w danym miejscu pozwolić i że oprócz biblioteki, gdzieś tam ma jeszcze w tej samej pamięci, w tej samej płaszczyźnie pracować wykorzystujący ją skrypt, który także ma swoje wymagania.

OPT 2.0.0-dev5

Zyx — czw, 20 mar 2008 14:27:00 +0100

Upłynęło trochę więcej czasu, niż planowałem, od ostatniej wersji dev, lecz poniekąd w ramach rekompensaty dodałem do OPT sporą liczbę nowych rzeczy. Rozwiązanie sprawy DTD, prologów XML, obsługi sekcji CDATA i escape'owania kodu, dokończenie parsera wyrażeń czy wreszcie pełna implementacja komponentów są moim zdaniem znaczącym krokiem naprzód. Do końca prac jest już bliżej, niż dalej. Na zakodowanie czeka już tylko kilka instrukcji, prawie wszystkie pozostałe są już ukończone. Kompilator działa bardzo dobrze, na ukończeniu jest cały interfejs programistyczny, przechodząc ostatnie szlify. Niebawem planuję rozpocząć pierwsze testy bojowe na bazie mojej własnej strony domowej, a także rozpocząć tworzenie biblioteki Open Power Forms zgodnej z nową wersją.

Nowy Open Power Template posiada całkowicie zmieniony mechanizm komponentów, który jest teraz znacznie bardziej elastyczny i pozwala na uzyskiwanie wielu ciekawych efektów niewielkim kosztem. Fundamentalne zasady działania pozostały, zmieniła się cała reszta. Oto przykładowa próbka pokazująca, jak teraz będzie wyglądać praca z formularzami budowanymi na bazie komponentów:

<opt:snippet name="componentView">
  <com:div class="field" invalid="field error">
    <p>{$opt.component.title}: <opt:display /></p>
    <p class="desc" opt:if="$opt.component.description">{$opt.component.description}</p>
    <opt:onEvent name="error" message="info">
      <p class="error">{@info}</p>
    </opt:onEvent>
  </com:div>
</opt:snippet>

<div class="form">
<form method="post" action="skrypt.php">

<opt:input name="imie" template="componentView">
   <opt:set name="title" str:value="Podaj swoje imię" />
   <opt:set name="description" str:value="Przynajmniej 3 litery" />
</opt:input>

<opt:input name="nazwisko" template="componentView">
   <opt:set name="title" str:value="Podaj swoje nazwisko" />
   <opt:set name="description" str:value="Przynajmniej 3 litery" />
</opt:input>

<opt:input name="wiek" template="componentView">
   <opt:set name="title" str:value="Podaj swój wiek" />
   <opt:set name="description" str:value="Przedział: 10-99 lat" />
</opt:input>

<div class="foot"><input type="submit" value="Wyślij" /></div>
</form>
</div>

Nowa implementacja w pełni wykorzystuje możliwości, jakie stwarza instrukcja opt:snippet oraz dziedziczenie szablonów. Gdyby ktoś chciał, mógłby zaprogramować obiekty komponentów w ten sposób, że zbędne stanie się nawet ręczne podawanie opisów poszczególnych pól. Komponent może obsługiwać zdarzenia, wyświetlanie samego siebie oraz swojego otoczenia, zarządzać parametrami, a nawet ingerować w atrybuty wybranych znaczników HTML (do tego służy przestrzeń nazw com). OPT sam z siebie zawierać będzie jedynie mechanizm, lecz nie będzie w nim ani jednego gotowego komponentu (poza przykładami, ale te nie są bezpośrednio częścią biblioteki). Po prostu aby w pełni wykorzystać cały potencjał, klasy komponentów powinny być zintegrowane z systemami kontroli formularzy, obsługą błędów, systemem językowym itd., a to wykracza daleko poza dziedzinę biblioteki. Gotową do natychmiastowego użycia implementacją komponentów będzie Open Power Forms.

Niestety, w nowym devie lekko zawalona jest sprawa z dokumentacją. Po prostu TypeFriendly jeszcze specjalnie nie potrafi generować tego, co chcemy, a DocBookowej wersji nie rozwijałem, pisząc już wszystko w nowym formacie. Dlatego mam nadzieję, że nikomu nie stanie się krzywda, gdy zobaczy... zbiór źródłowych plików TXT, które trzeba przeglądać narzędziami notatnikopodobnymi :). Na pocieszenie dodam, że składnia Markdowna Extra jest bardzo czytelna dla człowieka (w sumie zaprojektowano ją właśnie na wzór "formatowań" stosowanych właśnie w e-mailach, plikach README itd.), dlatego poza brakiem nawigacji oraz kolorów nie powinno to być aż takie trudne w lekturze. Trzeba jedynie pamiętać o ustawieniu (na wszelki wypadek) uniksowych zejść do nowej linii i kodowania UTF-8.

Wraz z publikacją nowej wersji, zamieściłem też na stronie bibliotek pierwszą partię oficjalnych, praktycznych porad do OPT. Oto linki do najważniejszych miejsc:

OPT 2.0.0-dev4

Zyx — nie, 02 mar 2008 11:14:00 +0100

Do ściągnięcia jest już czwarta wersja developerska Open Power Template'a. Projekt zaczyna nabierać kształtów, jako że na ukończeniu jest już główna klasa parsera. Oprócz wzmiankowanego wcześniej cache'u, zaimplementowałem nowe instrukcje oraz skończyłem prace nad snippetami tak, że w zasadzie już całe dziedziczenie szablonów działa, jak należy. Mam nadzieję, że pod koniec miesiąca biblioteka będzie już w takim stanie, że będzie nadawać się do ostrożnego użycia. Rzeczywiste projekty będą potrzebne, aby wykryć błędy oraz końcowe niedociągnięcia.

W snippetach pojawiła się możliwość wstawienia zawartości rodzica za pomocą znacznika opt:parent:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<opt:extend file="test_inherited_a.tpl">
	<opt:snippet name="header">
		<h1>Webmaster Of Puppets</h1>
		<p>Here is the parent content:</p>
		<opt:parent/>
		<p>End of the parent content</p>
	</opt:snippet>
</opt:extend>

W tym wypadku, jeżeli w pliku test_inherited_a.tpl zdefiniowaliśmy snippet o identycznej nazwie, jego zawartość trafi na miejsce znacznika opt:parent. Takie zagnieżdżanie działa wielopoziomowo. Gdyby i w tamtym snippecie użyto tego mechanizmu, OPT sięgnąłby jeszcze głębiej i tak dalej. Możliwe jest nawet wyciągnięcie domyślnej zawartości bloku opt:insert, do którego ostatecznie snippet będzie wstawiony. Do całości dodałem na dokładkę prosty kod wykrywający nieskończoną rekurencję. Gdy taka zostanie wykryta, programista otrzyma elegancki, czerwony komunikat błędu :).

Przy korzystaniu z nowego OPT powinna znacząco przydać się nowa konsola debugowa, rozszerzona w stosunku do analogicznej opcji w OPT 1.1.x. Główna zmiana dotyczy rozbicia listy wykonanych szablonów na mniejsze listy, które pokazują różne informacje:

Lista wykonanych szablonów
Lista aktualnie przekompilowanych szablonów
Lista szablonów wczytanych z cache'u.
Lista dziedziczenia szablonów - pokazuje użyte łańcuch zależności wraz z informacją, czy były one właśnie rekompilowane, czy nie.

Dodatkowo, konsola wyświetla wszystkie ostrzeżenia, które w tej wersji nie są już bezczelnie ładowane na ekran. Można się do nich dostać jedynie poprzez konsolę debugową lub komunikat błędu, o ile ustawiliśmy odpowiedni poziom debugowania.

Sprawa wydajności przedstawia się bardzo dobrze. Ostatecznie zamknąłem plik opt.class.php w około 25 KB, w porównaniu do 32 KB z poprzedniej wersji, a na chwilę obecną wpływ jego rozmiaru jest dość dobrze widoczny w wynikach, jako że PHP musi załadować taki parser i go wstępnie skompilować do wewnętrznego bajtkodu. Naturalnie, gdy pozałączamy dużo szablonów, nie będzie to aż takie widoczne, ale mimo wszystko cieszę się z uzyskanego efektu.

Paczkę można ściągnąć stąd. Zawiera ona również częściowo ukończoną polską dokumentację.