<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>Hello Wordl!</nadpis>
	<perex>generating relational data from CLI arguments</perex>
	<m:pořadí-příkladu>00100</m:pořadí-příkladu>

	<text xmlns="http://www.w3.org/1999/xhtml">
		
		<p>
			Let's start with an obligatory Hello World example.
		</p>
		
		<m:pre jazyk="bash"><![CDATA[relpipe-in-cli \
		--relation "relation_from_cli" \
			--attribute "a" "integer" \
			--attribute "b" "string" \
			--attribute "c" "boolean" \
			--record "1" "Hello" "true" \
			--record "2" "World!" "false"]]></m:pre>
	
		<p>
			This command generates relational data.
			In order to see them, we need to convert them to some other format.
			For now, we will use the „tabular“ format and pipe relational data to the <code>relpipe-out-tabular</code>.
		</p>
		
		<m:pre jazyk="bash"><![CDATA[relpipe-in-cli \
		--relation "relation_from_cli" \
			--attribute "a" "integer" \
			--attribute "b" "string" \
			--attribute "c" "boolean" \
			--record "1" "Hello" "true" \
			--record "2" "World!" "false" \
	| relpipe-out-tabular]]></m:pre>
	
		<p>Output:</p>

		<pre><![CDATA[relation_from_cli:
 ╭─────────────┬────────────┬─────────────╮
 │ a (integer) │ b (string) │ c (boolean) │
 ├─────────────┼────────────┼─────────────┤
 │           1 │ Hello      │        true │
 │           2 │ World!     │       false │
 ╰─────────────┴────────────┴─────────────╯
Record count: 2
]]></pre>

		<p>
			The syntax is simple as we see above. We specify the name of the relation
			and the names and types of attributes
			followed by the data.
		</p>

		<p>
			A single stream may contain multiple relations:
		</p>		
		
		<m:pre jazyk="bash"><![CDATA[(relpipe-in-cli --relation "a" --attribute "x" string --record "hello"; \
 relpipe-in-cli --relation "b" --attribute "y" string --record "world") \
	| relpipe-out-tabular]]></m:pre>
			
		<p>
			Thus we can combine various commands or files and pass the result to a single relational output filter (<code>relpipe-out-tabular</code> in this case) and get:
		</p>
		
		<pre><![CDATA[a:
 ╭────────────╮
 │ x (string) │
 ├────────────┤
 │ hello      │
 ╰────────────╯
Record count: 1
b:
 ╭────────────╮
 │ y (string) │
 ├────────────┤
 │ world      │
 ╰────────────╯
Record count: 1]]></pre>

		<p>
			In the example above, we call <code>relpipe-in-cli</code> twice and let the shell combine their outputs.
			This approach is useful when we want to combine relational data from various sources: different <code>relpipe-in-*</code> tools, files etc.
			But when we work with <code>relpipe-in-cli</code> only, we can ask it to create several relations during one run:
		</p>
		
		<m:pre jazyk="bash"><![CDATA[relpipe-in-cli \
		--relation "a" --attribute "x" string --record "hello" \
		--relation "b" --attribute "y" string --record "world" \
	| relpipe-out-tabular]]></m:pre>
	
		<p>
			The result will be the same.
			We can also use the <code>--records</code> option instead of the <code>--record</code> option – then the rest of the CLI arguments is treated as data of given relation.
			Obviously this option can be used only once for the last relation.
		</p>
		
		<m:pre jazyk="bash"><![CDATA[relpipe-in-cli \
		--relation "relation_from_cli" \
			--attribute "a" "integer" \
			--attribute "b" "string" \
			--attribute "c" "boolean" \
			--records \
				"1" "Hello" "true" \
				"2" "World!" "false" \
	| relpipe-out-tabular]]></m:pre>
	
		<p>
			It will generate the same <code>relation_from_cli</code> table as above.
			If we have more data (especially from external sources), we can use the <code>--records-on-stdin</code> option and pass them through the <m:a href="examples-cli-stdin">STDIN</m:a>.
		</p>
		
	</text>

</stránka>