--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/relpipe-data/examples-yaml.xml	Mon Feb 21 00:43:11 2022 +0100
@@ -0,0 +1,79 @@
+<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>Reading and writing YAML</nadpis>
+	<perex>convert relations to YAML or YAML/JSON to relations</perex>
+	<m:pořadí-příkladu>05200</m:pořadí-příkladu>
+
+	<text xmlns="http://www.w3.org/1999/xhtml">
+
+		<p>
+			YAML is a text format for serializing tree structures into text (like XML).
+			It can be sometimes tricky, but basic scenarios are intuitive and straightforward.
+			We can use YAML to describe relational data and load them using the <code>relpipe-in-yaml</code> input filter:
+		</p>
+		
+		<m:pre src="examples/film-1-no-types.yaml" jazyk="yaml"/>
+		<p>This YAML notation is almost as simple as <m:a href="examples-recfile">Recfiles</m:a> and like Recfiles it can be easily written by hand.</p>
+		
+		<p>
+			We can also use the JSON notation (it can be read by the same tool – <code>relpipe-in-json</code> is currently just a symlink to <code>relpipe-in-yaml</code>).
+			JSON is inferior to YAML and XML, but the JSON input filter might be useful when interacting with software that can produce only JSON.
+			The <code>film</code> relation would look like this in JSON format (shortened):
+		</p>
+		<m:pre jazyk="json"><![CDATA[{
+	"film": [
+		{
+			"title": "Beetlejuice",
+			"year": "1988",
+			"director": "Tim Burton"
+		},
+		{
+			"title": "…",
+			"year": "…",
+			"director": "…"
+		},
+		
+	]
+}]]></m:pre>
+		
+		<p>
+			When we want to declare data types
+			– which is usually a good idea – 
+			we add the <code>attribute-metadata</code> header and move the data under the <code>record</code> node:
+		</p>
+		<m:pre src="examples/film-1.yaml" jazyk="yaml"/>
+		<p>
+			This form (with data types and quotes) is also produced by the <code>relpipe-out-yaml</code> tool.
+		</p>
+		
+		
+		<p>When we load such YAML, we get this relational data:</p>
+		<m:pre src="examples/film-1.tabular" jazyk="text"/>
+		<p>Of course, there might be multiple relations, not only one.</p>
+		
+		
+		<p>
+			Once we convert the YAML to relational format, we can run any transformations and conversions as usual.
+			For example we can use SQL to sort the recordsy by year:
+		</p>
+
+		<m:pre jazyk="shell"><![CDATA[cat film-1.yaml \
+	| relpipe-in-yaml \
+	| relpipe-tr-sql --relation 'film' "SELECT * FROM film ORDER BY year" \
+	| relpipe-out-recfile > relpipe-data/examples/film-1.rec]]></m:pre>
+	
+		<p>and Recfile output filter to get:</p>
+		<m:pre src="examples/film-1.rec" jazyk="text"/>
+		
+		<p>Or we may use XPath filter:</p>
+		<m:pre jazyk="shell"><![CDATA[relpipe-tr-xpath --relation '.*' --where 'year >= 1980 and year < 1990']]></m:pre>
+		<p>to get the 80s films:</p>
+		<m:pre src="examples/film-1.filtered-2.tabular" jazyk="text"/>
+		
+		<p>YAML comes into play when we are looking for a friendly format for user-supplied data.</p>
+
+	</text>
+
+</stránka>