# HG changeset patch
# User František Kučera <franta-hg@frantovo.cz>
# Date 1547766058 -3600
# Node ID 2adb6465eaddcffbfb93bb4dceb4de95a235bf89
# Parent  d29970e8b7c9405b186a7c7a2fe27d9d41050d2c
examples: relpipe-in-filesystem

diff -r d29970e8b7c9 -r 2adb6465eadd relpipe-data/examples.xml
--- a/relpipe-data/examples.xml	Fri Jan 18 00:00:20 2019 +0100
+++ b/relpipe-data/examples.xml	Fri Jan 18 00:00:58 2019 +0100
@@ -697,6 +697,113 @@
 			as will be shown in further examples.
 		</p>
 		
+		<h2>Read files metadata using relpipe-in-filesystem</h2>
+		
+		<p>
+			Our filesystems contain valuable information and using proper tools we can extract them.
+			Using <code>relpipe-in-filesystem</code> we can gather metadata of our files and process them in relational way.
+			This tools does not traverse our filesystem (remember the rule: <em>do one thing and do it well</em>),
+			instead, it eats list of file paths separated from standard input.
+			It is typically used together with the <code>find</code> command, but we can also create such list by hand using e.g. <code>printf</code> command.
+		</p>
+		
+		<m:pre jazyk="bash">find /etc/ssh/ -print0 | relpipe-in-filesystem | relpipe-out-tabular</m:pre>
+		
+		<p>
+			In the basic scenario, it behaves like <code>ls -l</code>, just more modular and machine-readable:
+		</p>
+		
+		<pre><![CDATA[filesystem:
+ ╭───────────────────────────────────┬───────────────┬────────────────┬────────────────┬────────────────╮
+ │ path                     (string) │ type (string) │ size (integer) │ owner (string) │ group (string) │
+ ├───────────────────────────────────┼───────────────┼────────────────┼────────────────┼────────────────┤
+ │ /etc/ssh/                         │ d             │              0 │ root           │ root           │
+ │ /etc/ssh/moduli                   │ f             │         553122 │ root           │ root           │
+ │ /etc/ssh/ssh_host_ecdsa_key       │ f             │            227 │ root           │ root           │
+ │ /etc/ssh/sshd_config              │ f             │           3262 │ root           │ root           │
+ │ /etc/ssh/ssh_host_ed25519_key.pub │ f             │             91 │ root           │ root           │
+ │ /etc/ssh/ssh_host_ecdsa_key.pub   │ f             │            171 │ root           │ root           │
+ │ /etc/ssh/ssh_host_rsa_key         │ f             │           1679 │ root           │ root           │
+ │ /etc/ssh/ssh_config               │ f             │           1580 │ root           │ root           │
+ │ /etc/ssh/ssh_host_ed25519_key     │ f             │            399 │ root           │ root           │
+ │ /etc/ssh/ssh_import_id            │ f             │            338 │ root           │ root           │
+ │ /etc/ssh/ssh_host_rsa_key.pub     │ f             │            391 │ root           │ root           │
+ ╰───────────────────────────────────┴───────────────┴────────────────┴────────────────┴────────────────╯
+Record count: 11]]></pre>
+
+		<p>
+			We can specify desired attributes and also their aliases:
+		</p>
+		
+		<m:pre jazyk="bash"><![CDATA[find /etc/ssh/ -print0 \
+	| relpipe-in-filesystem \
+		--file path --as artefact \
+		--file size \
+		--file owner --as dear_owner \
+	| relpipe-out-tabular]]></m:pre>
+	
+		<p>And we will get a subset with renamed attributes:</p>
+	
+		<pre><![CDATA[filesystem:
+ ╭───────────────────────────────────┬────────────────┬─────────────────────╮
+ │ artefact                 (string) │ size (integer) │ dear_owner (string) │
+ ├───────────────────────────────────┼────────────────┼─────────────────────┤
+ │ /etc/ssh/                         │              0 │ root                │
+ │ /etc/ssh/moduli                   │         553122 │ root                │
+ │ /etc/ssh/ssh_host_ecdsa_key       │            227 │ root                │
+ │ /etc/ssh/sshd_config              │           3262 │ root                │
+ │ /etc/ssh/ssh_host_ed25519_key.pub │             91 │ root                │
+ │ /etc/ssh/ssh_host_ecdsa_key.pub   │            171 │ root                │
+ │ /etc/ssh/ssh_host_rsa_key         │           1679 │ root                │
+ │ /etc/ssh/ssh_config               │           1580 │ root                │
+ │ /etc/ssh/ssh_host_ed25519_key     │            399 │ root                │
+ │ /etc/ssh/ssh_import_id            │            338 │ root                │
+ │ /etc/ssh/ssh_host_rsa_key.pub     │            391 │ root                │
+ ╰───────────────────────────────────┴────────────────┴─────────────────────╯
+Record count: 11]]></pre>
+
+		<p>
+			We can also choose, which path format fits our needs best:
+		</p>
+
+
+		<m:pre jazyk="bash"><![CDATA[find ../../etc/ssh/ -print0 \
+	| relpipe-in-filesystem \
+		--file path \
+		--file path_absolute \
+		--file path_canonical \
+		--file name \
+	| relpipe-out-tabular]]></m:pre>
+	
+		<p>The <code>path</code> attribute contains the exact same value as was on input. Other formats are derived:</p>
+	
+		<pre><![CDATA[filesystem:
+ ╭────────────────────────────────────────┬───────────────────────────────────────────────────┬───────────────────────────────────┬──────────────────────────╮
+ │ path                          (string) │ path_absolute                            (string) │ path_canonical           (string) │ name            (string) │
+ ├────────────────────────────────────────┼───────────────────────────────────────────────────┼───────────────────────────────────┼──────────────────────────┤
+ │ ../../etc/ssh/                         │ /home/hack/../../etc/ssh/                         │ /etc/ssh                          │                          │
+ │ ../../etc/ssh/moduli                   │ /home/hack/../../etc/ssh/moduli                   │ /etc/ssh/moduli                   │ moduli                   │
+ │ ../../etc/ssh/ssh_host_ecdsa_key       │ /home/hack/../../etc/ssh/ssh_host_ecdsa_key       │ /etc/ssh/ssh_host_ecdsa_key       │ ssh_host_ecdsa_key       │
+ │ ../../etc/ssh/sshd_config              │ /home/hack/../../etc/ssh/sshd_config              │ /etc/ssh/sshd_config              │ sshd_config              │
+ │ ../../etc/ssh/ssh_host_ed25519_key.pub │ /home/hack/../../etc/ssh/ssh_host_ed25519_key.pub │ /etc/ssh/ssh_host_ed25519_key.pub │ ssh_host_ed25519_key.pub │
+ │ ../../etc/ssh/ssh_host_ecdsa_key.pub   │ /home/hack/../../etc/ssh/ssh_host_ecdsa_key.pub   │ /etc/ssh/ssh_host_ecdsa_key.pub   │ ssh_host_ecdsa_key.pub   │
+ │ ../../etc/ssh/ssh_host_rsa_key         │ /home/hack/../../etc/ssh/ssh_host_rsa_key         │ /etc/ssh/ssh_host_rsa_key         │ ssh_host_rsa_key         │
+ │ ../../etc/ssh/ssh_config               │ /home/hack/../../etc/ssh/ssh_config               │ /etc/ssh/ssh_config               │ ssh_config               │
+ │ ../../etc/ssh/ssh_host_ed25519_key     │ /home/hack/../../etc/ssh/ssh_host_ed25519_key     │ /etc/ssh/ssh_host_ed25519_key     │ ssh_host_ed25519_key     │
+ │ ../../etc/ssh/ssh_import_id            │ /home/hack/../../etc/ssh/ssh_import_id            │ /etc/ssh/ssh_import_id            │ ssh_import_id            │
+ │ ../../etc/ssh/ssh_host_rsa_key.pub     │ /home/hack/../../etc/ssh/ssh_host_rsa_key.pub     │ /etc/ssh/ssh_host_rsa_key.pub     │ ssh_host_rsa_key.pub     │
+ ╰────────────────────────────────────────┴───────────────────────────────────────────────────┴───────────────────────────────────┴──────────────────────────╯
+Record count: 11]]></pre>
+
+		<p>
+			We can also <em>select</em> symlink targets or their types.
+			If some file is missing or is inaccessible due to permissions, only <code>path</code> is printed for it.
+		</p>
+		
+		<p>
+			Tip: if we are looking for files in the current directory and want omit the „.“ we just call: <code>find -printf '%P\0'</code> instead of <code>find -print0</code>.
+		</p>
+
 		
 	</text>