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.

Long-term TODO

• Merge with libimagstore