From 8c597d2c4dbf6f66c522a708014a1865d3376741 Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Thu, 2 Aug 2018 01:41:33 +0200 Subject: [PATCH] doc: Document new IO story with libimagrt --- doc/src/05100-lib-rt.md | 76 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) 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`