doc: Document new IO story with libimagrt

1 files changed, 76 insertions, 0 deletions

diff --git a/doc/src/05100-lib-rt.md b/doc/src/05100-lib-rt.md
index ca22256c..eddba923 100644
--- a/doc/src/05100-lib-rt.md
+++ b/doc/src/05100-lib-rt.md
@@ -9,6 +9,82 @@ It also contains the store object and creates it from configuration.
 the `libimagrt::runtime::Runtime` object is the first complex object that comes
 to live in a imag binary.
 
+
+### IO with libimagrt
+
+libimagrt also provides IO primitives which should be used by all imag tools and
+libraries:
+
+The IO story in imag is pretty easy. As imag is mainly a CLI tool, IO is either
+`stdout` or `stderr` and `stdin`.
+
+
+#### Output
+
+libimagrt provides getters for an output stream for "normal" output, like
+logging, status information, etc. It also provides an output for "touched
+entries".
+
+Whenever an imag tool touches an entry in any way (either reading or writing),
+it should report this to libimagrt. libimagrt then does "the right thing" which
+is printing it to stdout or swallowing the output.
+Normal output (logging, status information, explicitely queried information)
+goes to the right sink automatically, that is:
+
+* If the user provides the appropriate flags, normal output goes to `stderr` and
+  "touched entries" go to `stdout`. This allows a user to 'chain' imag calls.
+* If the user does not provide these flags, normal output goes to `stdout` (for
+  piping to other tools, e.g. `grep`) and "touched entries" are not printed.
+
+* `stdin` can be used for reading store-ids which shall be processed by an imag
+  tool. For example `imag-tag` can receive a list of entries to add tags to via
+  `stdin` like this: `echo some/entry some/other | imag tag -I add sometag`.
+
+With these two settings in place, calls to imag can be chained and mixed with
+external tools pretty easily:
+
+```
+imag -O ids where 'some.header == 1' | \
+imag -I -O tag add foo               | \
+imag -I -O category set bar          | \
+fzf                                  | \
+imag -I tag add baz
+```
+
+The first line gets all imag entries where `some.header` equals `1`. The touched
+entries are printed to `stdout` (`-O`).
+The second line tags all entries which are passed via `stdin` (`-I`) with `foo`
+and prints them to `stdout` (`-O`)
+The third line sets the category for all entries which are passed via `stdin`
+with `bar` and prints them to `stdout`.
+The fourth line calls the `fzf` program and lets the user select one entry
+and the last line reads that entry via `stdin` and tags it with `baz`.
+
+Automatically detecting the appropriate input/output settings is possible, but
+hidden behind a environment-flag, as it is considered experimental.
+To test this, set `IMAG_IO_EXPERIMENTAL=1` in your environment.
+Note that `stdin` may be detected as "store id stream" when it is actually not.
+`libimagrt` can take care of this when passing `--interactive`.
+
+
+#### Input
+
+`libimagrt` also provides primitives for input. As documented in the paragraph
+on "Output", imag tools may get store ids passed via `stdin`.
+Hence, imag tools may/can not interactive when passing store ids via `stdin`.
+`libimagrt` provides functionality to query data from the user. These functions
+automatically fail if the user passes store-ids via `stdin`.
+
+The next paragraph documents the details of this and may be skipped.
+
+The user tells imag that `stdin` contains store-ids by setting the `-I`
+(`--ids-in`) flag on the commandline. If that flag is given, the interactive
+functionality of libimagrt automatically returns an `Err(_)` which can be used
+to tell the user what happened and exit the program accordingly.
+The user may also provide `--interactive` to tell imag via libimagrt that
+`stdin` is indeed not a stream of store-ids even if a pipe is detected.
+
+
 ### Long-term TODO
 
 - [ ] Merge with `libimagstore`