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