<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>