--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ukázka/skriptování.xml Sat Nov 17 23:05:59 2012 +0100
@@ -0,0 +1,358 @@
+<stránka
+ xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
+ xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
+ <nadpis>Skriptování</nadpis>
+ <perex>Na stránku můžeme vložit výstup skriptů.</perex>
+ <pořadí>50</pořadí>
+
+ <text xmlns="http://www.w3.org/1999/xhtml">
+
+ <p>
+ Na stránkách můžeme používat skripty.
+ Spouští se při generování a jejich standardní výstup se vloží do stránky.
+ Třeba doprostřed textu ostavce nebo do jiného elementu.
+ </p>
+ <p>
+ Příklad:
+ <em>
+ Tyto stránky byly vygenerované v systému
+ <span title="tento text pochází ze skriptu"><m:skript jazyk="bash">uname -o</m:skript></span>.
+ </em>
+ </p>
+
+ <p>
+ Díky skriptování můžeme stránky obohatit o prakticky libovolný obsah –
+ jak prostý text, tak i XHTML fragmenty.<m:podČarou>
+ Zapíná se pomocí atributu <code>výstup="xhtml"</code> a generátor pak kontroluje správné formátování –
+ nestane se vám, že byste omylem vygenerovali stránky s překříženými nebo neuzavřenými značkami.
+ Výchozím jmenným prostorem je XHTML a je dostupný i jmenný prostor pro makra (<code>m</code>).
+ </m:podČarou>
+ </p>
+ <p>
+ Skriptování ale může být nebezpečné, pokud byste spustili generátor na stránkách,
+ které psal někdo nedůvěryhodný a vložil do nich škodlivý kód.
+ Kromě toho, ukázková sada stránek by měla být přeložitelná kdekoli a mít minimum závislostí
+ (ne každý musí mít nainstalovaný Perl nebo Python či další podporované interprety).
+ Proto je skriptování ve výchozím stavu vypnuté – je potřeba ho povolit v souboru <code>web.conf</code>.
+ </p>
+
+ <h2>Podporované jazyky</h2>
+ <p>
+ V současnosti jsou podporované tyto jazyky:
+ </p>
+
+ <table>
+ <thead>
+ <tr>
+ <td>Jazyk</td>
+ <td>Interpret</td>
+ </tr>
+ </thead>
+ <tbody>
+ <m:skript jazyk="perl" výstup="xhtml"><![CDATA[
+use strict;
+use warnings;
+
+open(JAVA, "<", $ENV{"XWG_SKRIPTOVANI_JAVA"}) or die $!;
+
+while (<JAVA>) {
+ if (/podporovanýJazyk\.put\("(\w+)",\s*"(.*)"\);/) {
+ print "<tr><td><code>$1</code></td><td><code>$2</code></td></tr>\n";
+ }
+}
+ ]]></m:skript>
+ </tbody>
+ </table>
+
+ <h3>Perl – ukázka</h3>
+ <p>Jazyky použité nebo citované na této stránce:</p>
+ <!--
+ Lepšího výsledku bychom samozřejmě dosáhli pomocí XPath dotazu,
+ ale toto je příklad na Perl :-)
+ -->
+ <pre><m:skript jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+open(XML, "<", $ENV{"XWG_STRANKA_SOUBOR"}) or die $!;
+my %skripty;
+
+while (<XML>) {
+ if (/m:skript\s+jazyk="(\w+)"/) {
+ $skripty{$1}++;
+ }
+}
+
+for(keys(%skripty)) {
+ print "$skripty{$_}×\t $_\n";
+}
+ ]]></m:skript></pre>
+
+ <h3>BASH – ukázka</h3>
+ <pre><m:skript jazyk="bash"><![CDATA[
+echo -n "Právě je: ";
+date;
+echo -n "Operační systém: ";
+uname -o;
+echo -n "SHA-1 otisk zdrojáku této stránky: ";
+sha1sum "$XWG_STRANKA_SOUBOR" | cut -f 1 -d " ";
+ ]]></m:skript></pre>
+
+ <!--
+ <h2>PHP</h2>
+ <pre style="max-height: 200px;"><m:skript jazyk="php"><![CDATA[
+<?php
+phpinfo();
+?>
+ ]]></m:skript></pre>
+ -->
+
+ <h2>Proměnné prostředí</h2>
+ <p>
+ Ve skriptech máme dostupné následující proměnné prostředí:
+ </p>
+
+ <table>
+ <thead>
+ <tr>
+ <td>Proměnná</td>
+ <td>Význam</td>
+ </tr>
+ </thead>
+ <tbody>
+ <!-- Pokud načítáme skript ze souboru, je atribut jazyk nepovinný. -->
+ <m:skript jazyk="perl" výstup="xhtml" src="skriptování-proměnné.pl"/>
+ </tbody>
+ </table>
+
+ <p>
+ Kód:
+ </p>
+
+ <m:pre jazyk="xml"><![CDATA[<m:skript jazyk="bash">
+echo "URI: $XWG_STRANKA_URI";
+echo "Soubor: $XWG_STRANKA_SOUBOR";
+echo "Nadpis: $XWG_STRANKA_NADPIS";
+echo "Perex: $XWG_STRANKA_PEREX";
+</m:skript>]]></m:pre>
+
+ <p>nám vypíše:</p>
+
+ <pre><m:skript jazyk="bash"><![CDATA[
+echo "URI: $XWG_STRANKA_URI" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
+echo "Soubor: $XWG_STRANKA_SOUBOR" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
+echo "Nadpis: $XWG_STRANKA_NADPIS";
+echo "Perex: $XWG_STRANKA_PEREX";
+ ]]></m:skript></pre>
+
+ <h2 id="makraZeSkriptů">Makra ze skriptů</h2>
+ <p>
+ XML generované skriptem může také obsahovat makra, která se následně interptetují.
+ <m:skript jazyk="bash" výstup="xhtml"><![CDATA[
+echo '<m:skript jazyk="bash">'; # Ty zrůdo! :-)
+echo 'echo "Takže můžeš skriptovat, když skriptuješ,";';
+echo '</m:skript>';
+ ]]></m:skript>
+ nebo dělat něco užitečnějšího.
+ </p>
+
+ <m:skript jazyk="perl" výstup="xhtml"><![CDATA[
+use strict;
+use warnings;
+
+my $adresar = "vstup/makra";
+
+print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
+print " node [shape=\"box\"];\n";
+print " koren [label=\"Uživatelská makra\"];\n";
+
+opendir(DIR, $adresar) or die $!;
+my $i = 0;
+while (readdir(DIR)) {
+ next if (/^\./);
+ # Měli bychom ošetřit zvláštní znaky v názvech souborů,
+ # abychom nezpůsobili chybu GraphVizu.
+ print " n$i [label=\"$_\"];\n";
+ print " koren -> n$i;\n";
+ $i++;
+}
+
+print "</m:diagram>";
+closedir(DIR);
+ ]]></m:skript>
+
+ <p>…třeba vygenerovat tento diagram následujícím perlovským skriptem:</p>
+
+ <m:pre jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+my $adresar = "vstup/makra";
+
+print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
+print " node [shape=\"box\"];\n";
+print " koren [label=\"Uživatelská makra\"];\n";
+
+opendir(DIR, $adresar) or die $!;
+my $i = 0;
+while (readdir(DIR)) {
+ next if (/^\./);
+ # Měli bychom ošetřit zvláštní znaky v názvech souborů,
+ # abychom nezpůsobili chybu GraphVizu.
+ print " n$i [label=\"$_\"];\n";
+ print " koren -> n$i;\n";
+ $i++;
+}
+
+print "</m:diagram>";
+closedir(DIR);]]></m:pre>
+
+ <p>
+ Který vložíme zabalený v <code><![CDATA[<m:skript jazyk="perl" výstup="xhtml"> … </m:skript>]]></code> do stránky.
+ </p>
+ <p>
+ Známá chyba: ve skriptech zatím nefungují poznámky pod čarou (a není jisté, jestli kdy fungovat budou – pravděpodobně by to vyžadovalo vícefázové zpracování).
+ </p>
+
+ <h2>Makra ve skriptech</h2>
+
+ <p>
+ Uvnitř zdrojového kódu skriptu můžeme používat jiná makra.
+ Např. tento kód:
+ </p>
+
+ <m:pre jazyk="xml"><![CDATA[<pre>
+ <m:skript jazyk="perl">
+ print "Náš podnik se jmenuje <m:firma/>";
+ </m:skript>
+</pre>]]></m:pre>
+
+ <p>
+ nám vygeneruje:
+ </p>
+
+ <pre><m:skript jazyk="perl">
+ print "Náš podnik se jmenuje <m:firma/>";
+ </m:skript></pre>
+
+ <p>
+ Můžete si tak vytvořit makra pro opakující se části
+ a používat je jak v textu stránek, tak ve skriptech nebo diagramech.<m:podČarou>
+ Jen pozor na ošetření zvláštních znaků – pokud text takové znaky obsahuje,
+ je dobré ho zabalit ještě do jedné značky, která se postará o <em>escapování</em>
+ pro daný kontext (skriptovací jazyk a prostředí v něm – např. apostrofy vs. uvozovky).
+ </m:podČarou>
+ </p>
+
+ <p>
+ Jen pro připomenutí: nejedná se o nějaké primitivní zástupky a nahrazování textu
+ – makra můžou být parametrizovaná, obsahovat atributy (např. pád a číslo) nebo vnořené elementy
+ a na základě této parametrizace vytvářet odlišný výstup, který je následně předán skriptu.
+ </p>
+
+ <pre><m:skript jazyk="bash">
+ echo "S naší <m:firma pád="7"/> budete jistě spokojeni!";
+ echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
+ </m:skript></pre>
+
+ <p>
+ Zdrojový kód:
+ </p>
+
+ <!-- Pozor: ve zvýrazňovači syntaxe Pygmentize je chyba – neumí diakritiku – správně je: pád="7" -->
+ <m:pre jazyk="xml"><![CDATA[<pre>
+ <m:skript jazyk="bash">
+ echo "S naší <m:firma pad="7"/> budete jistě spokojeni!";
+ echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
+ </m:skript>
+</pre>]]></m:pre>
+
+ <p>
+ Skripty v těchto příkladech nejsou příliš užitečné, protože pouze vypisují text,
+ který by šlo vložit přímo do XML stránky
+ – předpokládá se, že ve svých skriptech budete dělat něco zajímavějšího :-)
+ </p>
+
+ <h2>Skripty v makrech</h2>
+ <p>
+ Uvnitř definic maker můžeme volat<m:podČarou>
+ Ovšem trochu jiným způsobem, než ve stránkách –
+ nacházíme se totiž v <em>programu</em> (XSL šablona definující makro)
+ nikoli v <em>datovém souboru</em> (XML stránka).
+ </m:podČarou>
+ jiná makra – mj. skripty.
+ Toho jsme využili v makru, které generuje tabulku verzí z mercurialu
+ – ten umí vypsat historii úložiště v XML, které následně snadno zpracujeme v XSLT.
+ </p>
+
+ <m:hg-verze/>
+
+ <p>
+ Toto makro naleznete v souboru <code>vstup/makra/hg-verze.xsl</code>.
+ </p>
+
+ <h2>Vnořování maker</h2>
+ <p>
+ Trochu jiný případ je vnořování maker na stránce.
+ Např. si chceme vypsat vybrané internetové služby:
+ </p>
+ <m:tabulka>
+ <m:skript jazyk="perl"><![CDATA[
+use strict;
+use warnings;
+
+print "Port\tSlužba\tProtokol\n";
+open(S, "<", "/etc/services") or die $!;
+while (<S>) {
+ if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
+ print "$2\t$1\t$3\n";
+ }
+}
+ ]]></m:skript>
+ </m:tabulka>
+
+ <p>
+ Pro vygenerování použijeme dvě makra – tabulku a skript – která vložíme do textu stránky:
+ </p>
+
+ <m:pre jazyk="xml"><![CDATA[
+<m:tabulka>
+ <m:skript jazyk="perl"><![CDATA[
+ print "Port\tSlužba\tProtokol\n";
+ open(S, "<", "/etc/services") or die $!;
+ while (<S>) {
+ if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
+ print "$2\t$1\t$3\n";
+ }
+ }
+ ]]]]>><![CDATA[</m:skript>
+</m:tabulka>]]></m:pre>
+
+ <p>
+ Ve skriptu v tomto případě negenerujeme XHTML značky, ale CSV (s tabulátory)
+ a o převod na XHTML tabulku se postará XSL šablona.
+ </p>
+
+ <!--
+ Nebo to taky můžeme napsat na jeden řádek:
+ cat /etc/services | perl -ne 'if (/(\w+)\s+(21|22|25|80)\/(tcp)/) { print "$2\t$1\t$3\n";}'
+ a vložit do tabulky jako BASH skript :-)
+ -->
+
+ <p>
+ Podobně bychom mohli postupovat i u <a href="#makraZeSkriptů">diagramu</a> –
+ negenerovat skriptem značky makra, ale pouze jeho obsah – zadání diagramu, nebo jen jeho část.
+ Někdy se ale může hodit ve skriptu nastavovat atributy elementů nebo elementy vytvářet dynamicky.
+ </p>
+
+ <p>
+ Skriptování lze použít i pro generování zdrojového kódu, který bude následně zvýrazněn
+ pomocí značky <code><m:pre jazyk="…"/></code>.
+ Toho využíváme na stránce <m:a href="zdrojáky">Zdrojové kódy</m:a> v případě SQL a XML ukázek.
+ Skript můžeme použít mj. i ke zkrácení zdrojáku – když chceme vypsat jen jeho relevantní část.
+ </p>
+
+ </text>
+
+</stránka>
+