imag/doc/src/05100-lib-rt.md

## libimagrt

This library provides utility functionality for the modules and the binary
frontends, such as reading and parsing the configuration file, a builder
helper for the commandline interface and such.

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.