ukázka/skriptování.xml
author František Kučera <franta-hg@frantovo.cz>
Thu, 24 Oct 2019 22:06:44 +0200
changeset 136 d5feb9d8ebc3
parent 120 4d33f14e99dd
permissions -rw-r--r--
fix license version: GNU GPLv3
     1 <stránka
     2 	xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
     3 	xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
     4 	<nadpis>Skriptování</nadpis>
     5 	<perex>Na stránku můžeme vložit výstup skriptů.</perex>
     6 	<pořadí>50</pořadí>
     7 
     8 	<text xmlns="http://www.w3.org/1999/xhtml">
     9 
    10 		<p>
    11 			Na stránkách můžeme používat skripty.
    12 			Spouští se při generování a jejich standardní výstup se vloží do stránky.
    13 			Třeba doprostřed textu ostavce nebo do jiného elementu.
    14 		</p>
    15 		<p>
    16 			Příklad:
    17 			<em>
    18 				Tyto stránky byly vygenerované v systému
    19 				<span title="tento text pochází ze skriptu"><m:skript jazyk="bash">uname -o</m:skript></span>.
    20 			</em>
    21 		</p>
    22 
    23 		<p>
    24 			Díky skriptování můžeme stránky obohatit o prakticky libovolný obsah – 
    25 			jak prostý text, tak i XHTML fragmenty.<m:podČarou>
    26 				Zapíná se pomocí atributu <code>výstup="xhtml"</code> a generátor pak kontroluje správné formátování – 
    27 				nestane se vám, že byste omylem vygenerovali stránky s překříženými nebo neuzavřenými značkami.
    28 				Výchozím jmenným prostorem je XHTML a je dostupný i jmenný prostor pro makra (<code>m</code>).
    29 			</m:podČarou>
    30 		</p>
    31 		<p>
    32 			Skriptování ale může být nebezpečné, pokud byste spustili generátor na stránkách,
    33 			které psal někdo nedůvěryhodný a vložil do nich škodlivý kód.
    34 			Kromě toho, ukázková sada stránek by měla být přeložitelná kdekoli a mít minimum závislostí
    35 			(ne každý musí mít nainstalovaný Perl nebo Python či další podporované interprety).
    36 			Proto je skriptování ve výchozím stavu vypnuté – je potřeba ho povolit v souboru <code>web.conf</code>.
    37 		</p>
    38 
    39 		<h2>Podporované jazyky</h2>
    40 		<p>
    41 			V současnosti jsou podporované tyto jazyky:
    42 		</p>
    43 
    44 		<table>
    45 			<thead>
    46 				<tr>
    47 					<td>Jazyk</td>
    48 					<td>Interpret</td>
    49 				</tr>
    50 			</thead>
    51 			<tbody>
    52 				<m:skript jazyk="perl" výstup="xhtml"><![CDATA[
    53 use strict;
    54 use warnings;
    55 
    56 open(JAVA, "<", $ENV{"XWG_SKRIPTOVANI_JAVA"}) or die $!;
    57 
    58 while (<JAVA>) {
    59 	if (/podporovanýJazyk\.put\("(\w+)",\s*"(.*)"\);/) {
    60 		print "<tr><td><code>$1</code></td><td><code>$2</code></td></tr>\n";
    61 	}
    62 }
    63 				]]></m:skript>
    64 			</tbody>
    65 		</table>
    66 
    67 		<h3>Perl – ukázka</h3>
    68 		<p>Jazyky použité nebo citované na této stránce:</p>
    69 		<!--
    70 			Lepšího výsledku bychom samozřejmě dosáhli pomocí XPath dotazu,
    71 			ale toto je příklad na Perl :-)
    72 		-->
    73 		<pre><m:skript jazyk="perl"><![CDATA[
    74 use strict;
    75 use warnings;
    76 
    77 open(XML, "<", $ENV{"XWG_STRANKA_SOUBOR"}) or die $!;
    78 my %skripty;
    79 
    80 while (<XML>) {
    81 	if (/m:skript\s+jazyk="(\w+)"/) {
    82 		$skripty{$1}++;
    83 	}
    84 }
    85 
    86 for(keys(%skripty)) {
    87 	print "$skripty{$_}×\t $_\n";
    88 }
    89 			]]></m:skript></pre>
    90 
    91 		<h3>BASH – ukázka</h3>
    92 		<pre><m:skript jazyk="bash"><![CDATA[
    93 echo -n "Právě je: ";
    94 date;
    95 echo -n "Operační systém: ";
    96 uname -o;
    97 echo -n "SHA-1 otisk zdrojáku této stránky: ";
    98 sha1sum "$XWG_STRANKA_SOUBOR" | cut -f 1 -d " ";
    99 			]]></m:skript></pre>
   100 
   101 			<!--
   102 			<h2>PHP</h2>
   103 			<pre style="max-height: 200px;"><m:skript jazyk="php"><![CDATA[
   104 <?php
   105 phpinfo();
   106 ?>
   107 			]]></m:skript></pre>
   108 			-->
   109 
   110 			<h2>Proměnné prostředí</h2>
   111 			<p>
   112 				Ve skriptech máme dostupné následující proměnné prostředí:
   113 			</p>
   114 
   115 			<table>
   116 				<thead>
   117 					<tr>
   118 						<td>Proměnná</td>
   119 						<td>Význam</td>
   120 					</tr>
   121 				</thead>
   122 				<tbody>
   123 					<!-- Pokud načítáme skript ze souboru, je atribut jazyk nepovinný. -->
   124 					<m:skript jazyk="perl" výstup="xhtml" src="skriptování-proměnné.pl"/>
   125 				</tbody>
   126 			</table>
   127 
   128 			<p>
   129 				Kód:
   130 			</p>
   131 
   132 			<m:pre jazyk="xml"><![CDATA[<m:skript jazyk="bash">
   133 echo "URI:    $XWG_STRANKA_URI";
   134 echo "Soubor: $XWG_STRANKA_SOUBOR";
   135 echo "Nadpis: $XWG_STRANKA_NADPIS";
   136 echo "Perex:  $XWG_STRANKA_PEREX";
   137 </m:skript>]]></m:pre>
   138 
   139 			<p>nám vypíše:</p>
   140 
   141 			<pre><m:skript jazyk="bash"><![CDATA[
   142 echo "URI:    $XWG_STRANKA_URI" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
   143 echo "Soubor: $XWG_STRANKA_SOUBOR" | sed "s#/mnt/sshfs/[^/]*/#/#" | sed s/\\/home\\/$USER/\\/home\\/xwg/g;
   144 echo "Nadpis: $XWG_STRANKA_NADPIS";
   145 echo "Perex:  $XWG_STRANKA_PEREX";
   146 		]]></m:skript></pre>
   147 
   148 		<h2 id="makraZeSkriptů">Makra ze skriptů</h2>
   149 		<p>
   150 			XML generované skriptem může také obsahovat makra, která se následně interptetují.
   151 			<m:skript jazyk="bash" výstup="xhtml"><![CDATA[
   152 echo '<m:skript jazyk="bash">'; # Ty zrůdo! :-)
   153 echo 'echo "Takže můžeš skriptovat, když skriptuješ,";';
   154 echo '</m:skript>';
   155 			]]></m:skript>
   156 			nebo dělat něco užitečnějšího.
   157 		</p>
   158 		
   159 		<m:skript jazyk="perl" výstup="xhtml"><![CDATA[
   160 use strict;
   161 use warnings;
   162 
   163 my $adresar = "vstup/makra";
   164 
   165 print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
   166 print "	node		[shape=\"box\"];\n";
   167 print "	koren	[label=\"Uživatelská makra\"];\n";
   168 
   169 opendir(DIR, $adresar) or die $!;
   170 my $i = 0;
   171 while (readdir(DIR)) {
   172 	next if (/^\./);
   173 	# Měli bychom ošetřit zvláštní znaky v názvech souborů,
   174 	# abychom nezpůsobili chybu GraphVizu.
   175 	print "	n$i		[label=\"$_\"];\n";
   176 	print "	koren	-> n$i;\n";
   177 	$i++;
   178 }
   179 
   180 print "</m:diagram>";
   181 closedir(DIR);
   182 		]]></m:skript>
   183 
   184 		<p>…třeba vygenerovat tento diagram následujícím perlovským skriptem:</p>
   185 
   186 		<m:pre jazyk="perl"><![CDATA[
   187 use strict;
   188 use warnings;
   189 
   190 my $adresar = "vstup/makra";
   191 
   192 print "<m:diagram nadpis='Uživatelská makra v adresáři $adresar'>\n";
   193 print "	node	[shape=\"box\"];\n";
   194 print "	koren	[label=\"Uživatelská makra\"];\n";
   195 
   196 opendir(DIR, $adresar) or die $!;
   197 my $i = 0;
   198 while (readdir(DIR)) {
   199 	next if (/^\./);
   200 	# Měli bychom ošetřit zvláštní znaky v názvech souborů,
   201 	# abychom nezpůsobili chybu GraphVizu.
   202 	print "	n$i		[label=\"$_\"];\n";
   203 	print "	koren	-> n$i;\n";
   204 	$i++;
   205 }
   206 
   207 print "</m:diagram>";
   208 closedir(DIR);]]></m:pre>
   209 
   210 		<p>
   211 			Který vložíme zabalený v <code><![CDATA[<m:skript jazyk="perl" výstup="xhtml"> … </m:skript>]]></code> do stránky.
   212 		</p>
   213 		<p>
   214 			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í).
   215 		</p>
   216 
   217 		<h2>Makra ve skriptech</h2>
   218 		
   219 		<p>
   220 			Uvnitř zdrojového kódu skriptu můžeme používat jiná makra.
   221 			Např. tento kód:
   222 		</p>
   223 
   224 		<m:pre jazyk="xml"><![CDATA[<pre>
   225 	<m:skript jazyk="perl">
   226 		print "Náš podnik se jmenuje <m:firma/>";
   227 	</m:skript>
   228 </pre>]]></m:pre>
   229 
   230 		<p>
   231 			nám vygeneruje:
   232 		</p>
   233 
   234 		<pre><m:skript jazyk="perl">
   235 				print "Náš podnik se jmenuje <m:firma/>";
   236 		</m:skript></pre>
   237 
   238 		<p>
   239 			Můžete si tak vytvořit makra pro opakující se části
   240 			a používat je jak v textu stránek, tak ve skriptech nebo diagramech.<m:podČarou>
   241 				Jen pozor na ošetření zvláštních znaků – pokud text takové znaky obsahuje,
   242 				je dobré ho zabalit ještě do jedné značky, která se postará o <em>escapování</em> 
   243 				pro daný kontext (skriptovací jazyk a prostředí v něm – např. apostrofy vs. uvozovky).
   244 			</m:podČarou>
   245 		</p>
   246 		
   247 		<p>
   248 			Jen pro připomenutí: nejedná se o nějaké primitivní zástupky a nahrazování textu
   249 			– makra můžou být parametrizovaná, obsahovat atributy (např. pád a číslo) nebo vnořené elementy
   250 			a na základě této parametrizace vytvářet odlišný výstup, který je následně předán skriptu.
   251 		</p>
   252 		
   253 		<pre><m:skript jazyk="bash">
   254 			echo "S naší <m:firma pád="7"/> budete jistě spokojeni!";
   255 			echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
   256 		</m:skript></pre>
   257 		
   258 		<p>
   259 			Zdrojový kód:
   260 		</p>
   261 		
   262 		<!-- Pozor: ve zvýrazňovači syntaxe Pygmentize je chyba – neumí diakritiku – správně je: pád="7" -->
   263 		<m:pre jazyk="xml"><![CDATA[<pre>
   264 	<m:skript jazyk="bash">
   265 		echo "S naší <m:firma pad="7"/> budete jistě spokojeni!";
   266 		echo "Stejně jako my jsme spokojeni s operačním systémem `uname -o`.";
   267 	</m:skript>
   268 </pre>]]></m:pre>
   269 
   270 		<p>
   271 			Skripty v těchto příkladech nejsou příliš užitečné, protože pouze vypisují text,
   272 			který by šlo vložit přímo do XML stránky
   273 			– předpokládá se, že ve svých skriptech budete dělat něco zajímavějšího :-)
   274 		</p>
   275 
   276 		<h2>Skripty v makrech</h2>
   277 		<p>
   278 			Uvnitř definic maker můžeme volat<m:podČarou>
   279 				Ovšem trochu jiným způsobem, než ve stránkách –
   280 				nacházíme se totiž v <em>programu</em> (XSL šablona definující makro)
   281 				nikoli v <em>datovém souboru</em> (XML stránka).
   282 			</m:podČarou>
   283 			jiná makra – mj. skripty.
   284 			Toho jsme využili v makru, které generuje tabulku verzí z mercurialu
   285 			– ten umí vypsat historii úložiště v XML, které následně snadno zpracujeme v XSLT.
   286 		</p>
   287 
   288 		<m:hg-verze/>
   289 
   290 		<p>
   291 			Toto makro naleznete v souboru <code>vstup/makra/hg-verze.xsl</code>.
   292 		</p>
   293 
   294 		<h2>Vnořování maker</h2>
   295 		<p>
   296 			Trochu jiný případ je vnořování maker na stránce.
   297 			Např. si chceme vypsat vybrané internetové služby:
   298 		</p>
   299 		<m:tabulka>
   300 			<m:skript jazyk="perl"><![CDATA[
   301 use strict;
   302 use warnings;
   303 
   304 print "Port\tSlužba\tProtokol\n";
   305 open(S, "<", "/etc/services") or die $!;
   306 while (<S>) {
   307 	if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
   308 		print "$2\t$1\t$3\n";
   309 	}
   310 }
   311 			]]></m:skript>
   312 		</m:tabulka>
   313 		
   314 		<p>
   315 			Pro vygenerování použijeme dvě makra – tabulku a skript – která vložíme do textu stránky:
   316 		</p>
   317 		
   318 		<m:pre jazyk="xml"><![CDATA[
   319 <m:tabulka>
   320 	<m:skript jazyk="perl"><![CDATA[
   321 		print "Port\tSlužba\tProtokol\n";
   322 		open(S, "<", "/etc/services") or die $!;
   323 		while (<S>) {
   324 			if (/(\w+)\s+(21|22|25|80)\/(tcp)/) {
   325 				print "$2\t$1\t$3\n";
   326 			}
   327 		}
   328 	]]]]>&gt;<![CDATA[</m:skript>
   329 </m:tabulka>]]></m:pre>
   330 
   331 		<p>
   332 			Ve skriptu v tomto případě negenerujeme XHTML značky, ale CSV (s tabulátory)
   333 			a o převod na XHTML tabulku se postará XSL šablona.
   334 		</p>
   335 
   336 		<!--
   337 			Nebo to taky můžeme napsat na jeden řádek:
   338 			cat /etc/services | perl -ne 'if (/(\w+)\s+(21|22|25|80)\/(tcp)/) { print "$2\t$1\t$3\n";}'
   339 			a vložit do tabulky jako BASH skript :-)
   340 		-->
   341 
   342 		<p>
   343 			Podobně bychom mohli postupovat i u <a href="#makraZeSkriptů">diagramu</a> –
   344 			negenerovat skriptem značky makra, ale pouze jeho obsah – zadání diagramu, nebo jen jeho část.
   345 			Někdy se ale může hodit ve skriptu nastavovat atributy elementů nebo elementy vytvářet dynamicky.
   346 		</p>
   347 
   348 		<p>
   349 			Skriptování lze použít i pro generování zdrojového kódu, který bude následně zvýrazněn
   350 			pomocí značky <code>&lt;m:pre jazyk="…"/&gt;</code>.
   351 			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.
   352 			Skript můžeme použít mj. i ke zkrácení zdrojáku – když chceme vypsat jen jeho relevantní část.
   353 		</p>
   354 
   355 	</text>
   356 
   357 </stránka>
   358