91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
## 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`
|
|
|