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