# HG changeset patch
# User František Kučera <franta-hg@frantovo.cz>
# Date 1544467428 -3600
# Node ID 4e45b9a177c295b89841c4ed9a259f55d687cca4
# Parent  0c05bdaeda343e437139e9f9901eeb3adea0aceb
examples: relpipe-tr-sed

diff -r 0c05bdaeda34 -r 4e45b9a177c2 relpipe-data/examples.xml
--- a/relpipe-data/examples.xml	Mon Dec 10 18:24:52 2018 +0100
+++ b/relpipe-data/examples.xml	Mon Dec 10 19:43:48 2018 +0100
@@ -372,6 +372,74 @@
 			</p>
 		</blockquote>
 		
+		<h2>Rename VG in /etc/fstab using relpipe-tr-sed</h2>
+		
+		<p>
+			Let's expect that we have a <code>/etc/fstab</code> with many lines defining the mount-points (directories) of particular devices (disks) and we are using LVM.
+			If we rename a volume group (VG), we have to change all of them. The lines look like this one:
+		</p>
+		
+		<pre>/dev/alpha/photos    /mnt/photos/    btrfs    noauto,noatime,nodiratime    0  0</pre>
+		
+		<p>
+			We want to change all lines from <code>alpha</code> to <code>beta</code> (the new VG name).
+			This can be done by:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-fstab \
+	| relpipe-tr-sed 'fstab' 'device' '^/dev/alpha/' '/dev/beta/' \
+	| relpipe-out-fstab]]></m:pre>
+	
+		<p>
+			Unlike the text-oriented <code>sed</code> command, the relational <code>relpipe-tr-sed</code> works only with given relation (<code>fstab</code>) and given attribute (<code>device</code>)
+			and it would leave untouched other relations and attributes in the stream.
+			So it would not replace the strings on unwanted places (if there are any random matches).
+		</p>
+		
+		<p>
+			Even the relation names and attribute names are specified as a regular expression, so we can (purposefully) modify multiple relations or attributes.
+			For example we can put zeroes in both <code>dump</code> and <code>pass</code> attributes:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-fstab | relpipe-tr-sed 'fstab' 'dump|pass' '.*' '0' | relpipe-out-fstab]]></m:pre>
+		
+		<p>
+			n.b. the data types must be respected, we can not e.g. put <code>abc</code> in the <code>pass</code> attribute because it is declared as <code>integer</code>.
+		</p>
+		
+		<h2>Using relpipe-tr-sed with groups and backreferences</h2>
+		
+		<p>
+			This tool also support regex groups and backreferences. Thus we can use parts of the matched string in our replacement string:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[relpipe-in-cli generate r 1 a string "some string xxx_123 some zzz_456 other" \
+	| relpipe-tr-sed 'r' 'a' '([a-z]{3})_([0-9]+)' '$2:$1' \
+	| relpipe-out-tabular]]></m:pre>
+		
+		<p>Which would convert this:</p>
+		<pre><![CDATA[r:
+ ╭────────────────────────────────────────╮
+ │ a                             (string) │
+ ├────────────────────────────────────────┤
+ │ some string xxx_123 some zzz_456 other │
+ ╰────────────────────────────────────────╯
+Record count: 1]]></pre>
+		
+		<p>into this:</p>
+		<pre><![CDATA[r:
+ ╭────────────────────────────────────────╮
+ │ a                             (string) │
+ ├────────────────────────────────────────┤
+ │ some string 123:xxx some 456:zzz other │
+ ╰────────────────────────────────────────╯
+Record count: 1]]></pre>
+
+		<p>
+			If there were any other relations or attributes in the stream, they would be unaffected by this transformation,
+			becase we specified <code>'r' 'a'</code> instead of some wider regular expression that would match more relations or attributes.
+		</p>
+		
 	</text>
 
 </stránka>