# Design of Subplot libraries

## Principles

For the libraries shipped with Subplot we should aim to follow these
principles:

* bindings in `share/common/lib`
* implemented in both Python and Rust
  - `share/{python,rust}/lib`
* both implementations verified using the same subplot
  - `tests/subplots/common/*.subplot`
* documented in the bindings file
* steps are named so that they naturally belong to a specific library
  - in `lib/files`, steps refer to files and directories
  - in `lib/runcmd`, steps refer to running commands of their stdio
    or exit code
* steps should be reasonably atomic and composable
* the library is reasonably comprehensive, given available time to work on it,
  and easy to extend with new steps
* steps should have variations to catch common ways of expressing the same thing
  - e.g., `given directory foo` vs `given a directory foo` vs `given directory foo exists`
* the library as a whole is reasonably generic and not specific to one
  application
* steps make sense to the target subset of stakeholders
  - we may need different steps for different subsets

This list not exhaustive and we will expand on it as we gain more experience
in using Subplot.

## The `lib/files` library

This has been fairly nice to use. It could be improved by adding variations
for some common ways of expressing things.

The library could add support for dealing with both on-disk and embedded
files. E.g., comparing an on-disk file with an embedded file without
first creating an on-disk file from the embedded one. This is partly for
convenience, but mostly so that stakeholders who are not programmers will find
it easier to understand scenarios. A step saying "given file foo and embedded
file bar are identical" is more easily understood than "given file bar"
followed, possibly much later, by "then files foo and bar match".

Some of the existing steps are there because they were convenient for the
Obnam project, and it may be worth reviewing whether they make sense in a
library shipped with Subplot itself

## The `lib/runcmd` library

This has been fairly nice to use, but is lacking things commonly needed.

* Stdio redirection and combining commands with shell pipers.
  - <https://gitlab.com/subplot/subplot/-/work_items/331>
  - <https://gitlab.com/subplot/subplot/-/work_items/388>
* Daemon or background process support.

Overall, the library could be more convenient and allow things to be more
concise for common usage patterns.

## Missing libraries

We should aim for Subplot to ship libraries for common use cases that many
projects need, especially ones that are tricky to implement. Some of the
things that are known to be missing:

* daemon or background process support, for testing HTTP services and such
* HTTP client support
  - <https://gitlab.com/subplot/subplot/-/work_items/276>
* support for common data formats, such as JSON and YAML
  - <https://gitlab.com/subplot/subplot/-/work_items/375>
