diff -r a39066264509 -r 2868d772c27e relpipe-data/examples-awk-changing-structure.xml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/relpipe-data/examples-awk-changing-structure.xml	Tue May 28 21:18:20 2019 +0200
@@ -0,0 +1,112 @@
+<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>Changing structures with AWK</nadpis>
+	<perex>adding or removing attributes or dropping a relation</perex>
+	<m:pořadí-příkladu>02400</m:pořadí-příkladu>
+
+	<text xmlns="http://www.w3.org/1999/xhtml">
+		
+		<p>
+			The AWK transformations can also change the structure of transformed relation.
+			It means adding or removing attributes or dropping the whole relation.
+		</p>
+		
+		<h2>Adding attributes with AWK</h2>
+		
+		<p>
+			Using <code>--output-attribute</code> we can specify the output attributes.
+			If we do not want to explicitly specify all of them and just want to add some new ones, we will use <code>--input-attributes-append</code> (or <code>--input-attributes-prepend</code>),
+			which will preserve also the input attributes:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-fstab \
+	| relpipe-tr-awk \
+		--relation '.*' \
+			--for-each '{ id = NR; record(); }' \
+			--output-attribute id integer \
+			--input-attributes-append \
+	| relpipe-out-tabular]]></m:pre>
+	
+		<p>This adds one new attribute with ordinal numbers:</p>
+		
+		<pre><![CDATA[fstab:
+ ╭──────────────┬─────────────────┬──────────────────────────────────────┬──────────────────────┬───────────────┬───────────────────────────────────────┬────────────────┬────────────────╮
+ │ id (integer) │ scheme (string) │ device                      (string) │ mount_point (string) │ type (string) │ options                      (string) │ dump (integer) │ pass (integer) │
+ ├──────────────┼─────────────────┼──────────────────────────────────────┼──────────────────────┼───────────────┼───────────────────────────────────────┼────────────────┼────────────────┤
+ │            1 │ UUID            │ 29758270-fd25-4a6c-a7bb-9a18302816af │ /                    │ ext4          │ relatime,user_xattr,errors=remount-ro │              0 │              1 │
+ │            2 │                 │ /dev/sr0                             │ /media/cdrom0        │ udf,iso9660   │ user,noauto                           │              0 │              0 │
+ │            3 │                 │ /dev/sde                             │ /mnt/data            │ ext4          │ relatime,user_xattr,errors=remount-ro │              0 │              2 │
+ │            4 │ UUID            │ a2b5f230-a795-4f6f-a39b-9b57686c86d5 │ /home                │ btrfs         │ relatime                              │              0 │              2 │
+ │            5 │                 │ /dev/mapper/sdf_crypt                │ /mnt/private         │ xfs           │ relatime                              │              0 │              2 │
+ ╰──────────────┴─────────────────┴──────────────────────────────────────┴──────────────────────┴───────────────┴───────────────────────────────────────┴────────────────┴────────────────╯
+Record count: 5]]></pre>
+
+
+		<h2>Remnoving attributes with AWK</h2>
+
+		<p>Or we can omit omit attributes unless explicitly specified ones:</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-fstab \
+	| relpipe-tr-awk \
+		--relation '.*' \
+			--for-each '{ type_big = toupper(type); record(); }' \
+			--output-attribute mount_point string \
+			--output-attribute type        string \
+			--output-attribute type_big    string \
+		| relpipe-out-tabular]]></m:pre>
+		
+		<p>which effectively removes unlisted attributes:</p>
+		
+		<pre><![CDATA[fstab:
+ ╭──────────────────────┬───────────────┬───────────────────╮
+ │ mount_point (string) │ type (string) │ type_big (string) │
+ ├──────────────────────┼───────────────┼───────────────────┤
+ │ /                    │ ext4          │ EXT4              │
+ │ /media/cdrom0        │ udf,iso9660   │ UDF,ISO9660       │
+ │ /mnt/data            │ ext4          │ EXT4              │
+ │ /home                │ btrfs         │ BTRFS             │
+ │ /mnt/private         │ xfs           │ XFS               │
+ ╰──────────────────────┴───────────────┴───────────────────╯
+Record count: 5]]></pre>
+
+
+		<p>AWK is a powerful language so we can use conditions, for cycles etc. and write much more complex transformations.</p>
+		
+		<h2>Dropping a relation</h2>
+		
+		<p>
+			A relation can be „dropped“ which means that transformation will run but no relational output will be generated for it 
+			(even the header will be omitted, so it differs from just eliminating all records by a condition).
+			Using AWK for such a simple operation like <code>DROP</code> seems weird but sometimes it might make sense due to intentional side effects.
+		</p>
+		
+		<p>
+			Because the AWK code is executed for each record, we can e.g. write some output to a file or to STDERR:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-fstab \
+	| relpipe-tr-awk \
+		--relation '.*' \
+			--for-each '{ printf("%s → %s\n", device, mount_point) > "/dev/stderr" }' \
+			--drop]]></m:pre>
+			
+		<p>Which prints text:</p>
+		
+		<pre><![CDATA[29758270-fd25-4a6c-a7bb-9a18302816af → /
+/dev/sr0 → /media/cdrom0
+/dev/sde → /mnt/data
+a2b5f230-a795-4f6f-a39b-9b57686c86d5 → /home
+/dev/mapper/sdf_crypt → /mnt/private]]></pre>
+
+		<p>
+			Then <code>relpipe-tr-awk</code> works much like an output filter (converts relational data to another format).
+			However, if there are more relations and some of theme are not matched by <code>--relation</code>, they will be passed through and delivered to the STDOUT in the relational format.
+			STDERR might be occasionally polluted by some warning messages, so using a dedicated file for such output is a safer way.
+		</p>
+
+
+	</text>
+	
+</stránka>