root/vstup/skriptování.xml @ 114:9302cf6856ea

<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/\\/home\\/$USER/\\/home\\/xwg/g;
echo "Soubor: $XWG_STRANKA_SOUBOR" | 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";
                        }
                }
        ]]]]>&gt;<![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>&lt;m:pre jazyk="…"/&gt;</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>