1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/ukázka/skriptování.xml Sat Nov 17 23:05:59 2012 +0100
1.3 @@ -0,0 +1,358 @@
1.4 +<stránka
1.5 + xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
1.6 + xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
1.7 + <nadpis>Skriptování</nadpis>
1.8 + <perex>Na stránku můžeme vložit výstup skriptů.</perex>
1.9 + <pořadí>50</pořadí>
1.10 +
1.11 + <text xmlns="http://www.w3.org/1999/xhtml">
1.12 +
1.13 + <p>
1.14 + Na stránkách můžeme používat skripty.
1.15 + Spouští se při generování a jejich standardní výstup se vloží do stránky.
1.16 + Třeba doprostřed textu ostavce nebo do jiného elementu.
1.17 + </p>
1.18 + <p>
1.19 + Příklad:
1.20 + <em>
1.21 + Tyto stránky byly vygenerované v systému
1.22 + <span title="tento text pochází ze skriptu"><m:skript jazyk="bash">uname -o</m:skript></span>.
1.23 + </em>
1.24 + </p>
1.25 +
1.26 + <p>
1.27 + Díky skriptování můžeme stránky obohatit o prakticky libovolný obsah –
1.28 + jak prostý text, tak i XHTML fragmenty.<m:podČarou>
1.29 + Zapíná se pomocí atributu <code>výstup="xhtml"</code> a generátor pak kontroluje správné formátování –
1.30 + nestane se vám, že byste omylem vygenerovali stránky s překříženými nebo neuzavřenými značkami.
1.31 + Výchozím jmenným prostorem je XHTML a je dostupný i jmenný prostor pro makra (<code>m</code>).
1.32 + </m:podČarou>
1.33 + </p>
1.34 + <p>
1.35 + Skriptování ale může být nebezpečné, pokud byste spustili generátor na stránkách,
1.36 + které psal někdo nedůvěryhodný a vložil do nich škodlivý kód.
1.37 + Kromě toho, ukázková sada stránek by měla být přeložitelná kdekoli a mít minimum závislostí
1.38 + (ne každý musí mít nainstalovaný Perl nebo Python či další podporované interprety).
1.39 + Proto je skriptování ve výchozím stavu vypnuté – je potřeba ho povolit v souboru <code>web.conf</code>.
1.40 + </p>
1.41 +
1.42 + <h2>Podporované jazyky</h2>
1.43 + <p>
1.44 + V současnosti jsou podporované tyto jazyky:
1.45 + </p>
1.46 +
1.47 + <table>
1.48 + <thead>
1.49 + <tr>
1.50 + <td>Jazyk</td>
1.51 + <td>Interpret</td>
1.52 + </tr>
1.53 + </thead>
1.54 + <tbody>
1.55 + <m:skript jazyk="perl" výstup="xhtml"><![CDATA[
1.56 +use strict;
1.57 +use warnings;
1.58 +
1.59 +open(JAVA, "<", $ENV{"XWG_SKRIPTOVANI_JAVA"}) or die $!;
1.60 +
1.61 +while (<JAVA>) {
1.62 + if (/podporovanýJazyk\.put\("(\w+)",\s*"(.*)"\);/) {
1.63 + print "<tr><td><code>$1</code></td><td><code>$2</code></td></tr>\n";
1.64 + }
1.65 +}
1.66 + ]]></m:skript>
1.67 + </tbody>
1.68 + </table>
1.69 +
1.70 + <h3>Perl – ukázka</h3>
1.71 + <p>Jazyky použité nebo citované na této stránce:</p>
1.72 + <!--
1.73 + Lepšího výsledku bychom samozřejmě dosáhli pomocí XPath dotazu,
1.74 + ale toto je příklad na Perl :-)
1.75 + -->
1.76 + <pre><m:skript jazyk="perl"><![CDATA[
1.77 +use strict;
1.78 +use warnings;
1.79 +
1.80 +open(XML, "<", $ENV{"XWG_STRANKA_SOUBOR"}) or die $!;
1.81 +my %skripty;
1.82 +
1.83 +while (<XML>) {
1.84 + if (/m:skript\s+jazyk="(\w+)"/) {
1.85 + $skripty{$1}++;
1.86 + }
1.87 +}
1.88 +
1.89 +for(keys(%skripty)) {
1.90 + print "$skripty{$_}×\t $_\n";
1.91 +}
1.92 + ]]></m:skript></pre>
1.93 +
1.94 + <h3>BASH – ukázka</h3>
1.95 + <pre><m:skript jazyk="bash"><![CDATA[
1.96 +echo -n "Právě je: ";
1.97 +date;
1.98 +echo -n "Operační systém: ";
1.99 +uname -o;
1.100 +echo -n "SHA-1 otisk zdrojáku této stránky: ";
1.101 +sha1sum "$XWG_STRANKA_SOUBOR" | cut -f 1 -d " ";
1.102 + ]]></m:skript></pre>
1.103 +
1.104 + <!--
1.105 + <h2>PHP</h2>
1.106 + <pre style="max-height: 200px;"><m:skript jazyk="php"><![CDATA[
1.107 +<?php
1.108 +phpinfo();
1.109 +?>
1.110 + ]]></m:skript></pre>
1.111 + -->
1.112 +
1.113 + <h2>Proměnné prostředí</h2>
1.114 + <p>
1.115 + Ve skriptech máme dostupné následující proměnné prostředí:
1.116 + </p>
1.117 +
1.118 + <table>
1.119 + <thead>
1.120 + <tr>
1.121 + <td>Proměnná</td>
1.122 + <td>Význam</td>
1.123 + </tr>
1.124 + </thead>
1.125 + <tbody>
1.126 + <!-- Pokud načítáme skript ze souboru, je atribut jazyk nepovinný. -->
1.127 + <m:skript jazyk="perl" výstup="xhtml" src="skriptování-proměnné.pl"/>
1.128 + </tbody>
1.129 + </table>
1.130 +
1.131 + <p>
1.132 + Kód:
1.133 + </p>
1.134 +
1.135 + <m:pre jazyk="xml"><![CDATA[<m:skript jazyk="bash">
1.136 +echo "URI: $XWG_STRANKA_URI";
1.137 +echo "Soubor: $XWG_STRANKA_SOUBOR";
1.138 +echo "Nadpis: $XWG_STRANKA_NADPIS";
1.139 +echo "Perex: $XWG_STRANKA_PEREX";
1.140 +</m:skript>]]></m:pre>
1.141 +
1.142 + <p>nám vypíše:</p>
1.143 +
1.144 + <pre><m:skript jazyk="bash"><![CDATA[
1.145 +echo "URI: $XWG_STRANKA_URI" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
1.146 +echo "Soubor: $XWG_STRANKA_SOUBOR" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
1.147 +echo "Nadpis: $XWG_STRANKA_NADPIS";
1.148 +echo "Perex: $XWG_STRANKA_PEREX";
1.149 + ]]></m:skript></pre>
1.150 +
1.151 + <h2 id="makraZeSkriptů">Makra ze skriptů</h2>
1.152 + <p>
1.153 + XML generované skriptem může také obsahovat makra, která se následně interptetují.
1.154 + <m:skript jazyk="bash" výstup="xhtml"><![CDATA[
1.155 +echo '<m:skript jazyk="bash">'; # Ty zrůdo! :-)
1.156 +echo 'echo "Takže můžeš skriptovat, když skriptuješ,";';
1.157 +echo '</m:skript>';
1.158 + ]]></m:skript>
1.159 + nebo dělat něco užitečnějšího.
1.160 + </p>
1.161 +
1.162 + <m:skript jazyk="perl" výstup="xhtml"><![CDATA[
1.163 +use strict;
1.164 +use warnings;
1.165 +
1.166 +my $adresar = "vstup/makra";
1.167 +
1.168 +print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
1.169 +print " node [shape=\"box\"];\n";
1.170 +print " koren [label=\"Uživatelská makra\"];\n";
1.171 +
1.172 +opendir(DIR, $adresar) or die $!;
1.173 +my $i = 0;
1.174 +while (readdir(DIR)) {
1.175 + next if (/^\./);
1.176 + # Měli bychom ošetřit zvláštní znaky v názvech souborů,
1.177 + # abychom nezpůsobili chybu GraphVizu.
1.178 + print " n$i [label=\"$_\"];\n";
1.179 + print " koren -> n$i;\n";
1.180 + $i++;
1.181 +}
1.182 +
1.183 +print "</m:diagram>";
1.184 +closedir(DIR);
1.185 + ]]></m:skript>
1.186 +
1.187 + <p>…třeba vygenerovat tento diagram následujícím perlovským skriptem:</p>
1.188 +
1.189 + <m:pre jazyk="perl"><![CDATA[
1.190 +use strict;
1.191 +use warnings;
1.192 +
1.193 +my $adresar = "vstup/makra";
1.194 +
1.195 +print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
1.196 +print " node [shape=\"box\"];\n";
1.197 +print " koren [label=\"Uživatelská makra\"];\n";
1.198 +
1.199 +opendir(DIR, $adresar) or die $!;
1.200 +my $i = 0;
1.201 +while (readdir(DIR)) {
1.202 + next if (/^\./);
1.203 + # Měli bychom ošetřit zvláštní znaky v názvech souborů,
1.204 + # abychom nezpůsobili chybu GraphVizu.
1.205 + print " n$i [label=\"$_\"];\n";
1.206 + print " koren -> n$i;\n";
1.207 + $i++;
1.208 +}
1.209 +
1.210 +print "</m:diagram>";
1.211 +closedir(DIR);]]></m:pre>
1.212 +
1.213 + <p>
1.214 + Který vložíme zabalený v <code><![CDATA[<m:skript jazyk="perl" výstup="xhtml"> … </m:skript>]]></code> do stránky.
1.215 + </p>
1.216 + <p>
1.217 + 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í).
1.218 + </p>
1.219 +
1.220 + <h2>Makra ve skriptech</h2>
1.221 +
1.222 + <p>
1.223 + Uvnitř zdrojového kódu skriptu můžeme používat jiná makra.
1.224 + Např. tento kód:
1.225 + </p>
1.226 +
1.227 + <m:pre jazyk="xml"><![CDATA[<pre>
1.228 + <m:skript jazyk="perl">
1.229 + print "Náš podnik se jmenuje <m:firma/>";
1.230 + </m:skript>
1.231 +</pre>]]></m:pre>
1.232 +
1.233 + <p>
1.234 + nám vygeneruje:
1.235 + </p>
1.236 +
1.237 + <pre><m:skript jazyk="perl">
1.238 + print "Náš podnik se jmenuje <m:firma/>";
1.239 + </m:skript></pre>
1.240 +
1.241 + <p>
1.242 + Můžete si tak vytvořit makra pro opakující se části
1.243 + a používat je jak v textu stránek, tak ve skriptech nebo diagramech.<m:podČarou>
1.244 + Jen pozor na ošetření zvláštních znaků – pokud text takové znaky obsahuje,
1.245 + je dobré ho zabalit ještě do jedné značky, která se postará o <em>escapování</em>
1.246 + pro daný kontext (skriptovací jazyk a prostředí v něm – např. apostrofy vs. uvozovky).
1.247 + </m:podČarou>
1.248 + </p>
1.249 +
1.250 + <p>
1.251 + Jen pro připomenutí: nejedná se o nějaké primitivní zástupky a nahrazování textu
1.252 + – makra můžou být parametrizovaná, obsahovat atributy (např. pád a číslo) nebo vnořené elementy
1.253 + a na základě této parametrizace vytvářet odlišný výstup, který je následně předán skriptu.
1.254 + </p>
1.255 +
1.256 + <pre><m:skript jazyk="bash">
1.257 + echo "S naší <m:firma pád="7"/> budete jistě spokojeni!";
1.258 + echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
1.259 + </m:skript></pre>
1.260 +
1.261 + <p>
1.262 + Zdrojový kód:
1.263 + </p>
1.264 +
1.265 + <!-- Pozor: ve zvýrazňovači syntaxe Pygmentize je chyba – neumí diakritiku – správně je: pád="7" -->
1.266 + <m:pre jazyk="xml"><![CDATA[<pre>
1.267 + <m:skript jazyk="bash">
1.268 + echo "S naší <m:firma pad="7"/> budete jistě spokojeni!";
1.269 + echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
1.270 + </m:skript>
1.271 +</pre>]]></m:pre>
1.272 +
1.273 + <p>
1.274 + Skripty v těchto příkladech nejsou příliš užitečné, protože pouze vypisují text,
1.275 + který by šlo vložit přímo do XML stránky
1.276 + – předpokládá se, že ve svých skriptech budete dělat něco zajímavějšího :-)
1.277 + </p>
1.278 +
1.279 + <h2>Skripty v makrech</h2>
1.280 + <p>
1.281 + Uvnitř definic maker můžeme volat<m:podČarou>
1.282 + Ovšem trochu jiným způsobem, než ve stránkách –
1.283 + nacházíme se totiž v <em>programu</em> (XSL šablona definující makro)
1.284 + nikoli v <em>datovém souboru</em> (XML stránka).
1.285 + </m:podČarou>
1.286 + jiná makra – mj. skripty.
1.287 + Toho jsme využili v makru, které generuje tabulku verzí z mercurialu
1.288 + – ten umí vypsat historii úložiště v XML, které následně snadno zpracujeme v XSLT.
1.289 + </p>
1.290 +
1.291 + <m:hg-verze/>
1.292 +
1.293 + <p>
1.294 + Toto makro naleznete v souboru <code>vstup/makra/hg-verze.xsl</code>.
1.295 + </p>
1.296 +
1.297 + <h2>Vnořování maker</h2>
1.298 + <p>
1.299 + Trochu jiný případ je vnořování maker na stránce.
1.300 + Např. si chceme vypsat vybrané internetové služby:
1.301 + </p>
1.302 + <m:tabulka>
1.303 + <m:skript jazyk="perl"><![CDATA[
1.304 +use strict;
1.305 +use warnings;
1.306 +
1.307 +print "Port\tSlužba\tProtokol\n";
1.308 +open(S, "<", "/etc/services") or die $!;
1.309 +while (<S>) {
1.310 + if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
1.311 + print "$2\t$1\t$3\n";
1.312 + }
1.313 +}
1.314 + ]]></m:skript>
1.315 + </m:tabulka>
1.316 +
1.317 + <p>
1.318 + Pro vygenerování použijeme dvě makra – tabulku a skript – která vložíme do textu stránky:
1.319 + </p>
1.320 +
1.321 + <m:pre jazyk="xml"><![CDATA[
1.322 +<m:tabulka>
1.323 + <m:skript jazyk="perl"><![CDATA[
1.324 + print "Port\tSlužba\tProtokol\n";
1.325 + open(S, "<", "/etc/services") or die $!;
1.326 + while (<S>) {
1.327 + if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
1.328 + print "$2\t$1\t$3\n";
1.329 + }
1.330 + }
1.331 + ]]]]>><![CDATA[</m:skript>
1.332 +</m:tabulka>]]></m:pre>
1.333 +
1.334 + <p>
1.335 + Ve skriptu v tomto případě negenerujeme XHTML značky, ale CSV (s tabulátory)
1.336 + a o převod na XHTML tabulku se postará XSL šablona.
1.337 + </p>
1.338 +
1.339 + <!--
1.340 + Nebo to taky můžeme napsat na jeden řádek:
1.341 + cat /etc/services | perl -ne 'if (/(\w+)\s+(21|22|25|80)\/(tcp)/) { print "$2\t$1\t$3\n";}'
1.342 + a vložit do tabulky jako BASH skript :-)
1.343 + -->
1.344 +
1.345 + <p>
1.346 + Podobně bychom mohli postupovat i u <a href="#makraZeSkriptů">diagramu</a> –
1.347 + negenerovat skriptem značky makra, ale pouze jeho obsah – zadání diagramu, nebo jen jeho část.
1.348 + Někdy se ale může hodit ve skriptu nastavovat atributy elementů nebo elementy vytvářet dynamicky.
1.349 + </p>
1.350 +
1.351 + <p>
1.352 + Skriptování lze použít i pro generování zdrojového kódu, který bude následně zvýrazněn
1.353 + pomocí značky <code><m:pre jazyk="…"/></code>.
1.354 + 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.
1.355 + Skript můžeme použít mj. i ke zkrácení zdrojáku – když chceme vypsat jen jeho relevantní část.
1.356 + </p>
1.357 +
1.358 + </text>
1.359 +
1.360 +</stránka>
1.361 +