imag/doc/src/02000-store.md

# The Store {#sec:thestore}

The store is where all the good things happen.
The store is basically just a directory on the filesystem imag manages and keeps
its state in.

One could say that the store is simply a databases, and it really is. We opted
to go for plain text, though, as we believe that plain text is the only sane way
to do such a thing.
A user should always be able to read her data without great effort and putting
everything in a _real_ database like sqlite or even postgresql would need a user
to install additional software just to read his own data. We don't want that.
Text is readable until the worlds end and we think it is therefor better to
store the data in plain text.

The following sections describe the store and the file format we use to store
data. One may skip the following sections, they are included for users who want
to dig into the store with their editors.

## File Format {#sec:thestore:fileformat}

The contents of the store are encoded in either UTF-8 or ASCII. Either way, a
normal text editor (like `vim` or the other one) will always be sufficient to
dog into the store and modify files. For simple viewing even a pager (like
`less`) is sufficient.

Each entry in the store consists of two parts:

1. Header
1. Content

The following section describe their purpose.

### Header Format {#sec:thestore:fileformat:header}

The header format is where imag stores its data. The header is an area at the
top of every file which is seperated from the content part by three dashes
(`---`). Between these three dashes there is structured data. imag uses `TOML`
as data format for this structured data, because it fits best and the available
`TOML` parser for the rust programming language is really good.

The header can contain any amount of data, but modules (see @sec:modules) are
restricted in their way of altering the data.

So normally there are several sections in the header. One section (`[imag]`) is
always present. It contains a `version` field, which tells imag which version
this file was created with (the version information is _also_ encoded in the
filename, just in case things change in the future). It also contains a `links`
field which is an Array of values. This `links` field is for linking (see
@sec:thestore:linking) to other entries in the store.

Other sections are named like the modules which created them. Every module is
allowed to store arbitrary data under its own section and a module may never
read other sections than its own. This is not enforced by imag itself, though.

### Content Format {#sec:thestore:fileformat:content}

The content is the part of the file where the user is free to enter any textual
content. The content may be rendered as Markdown or other markup format for the
users convenience. The store does never expect and specific markup and actually
the markup implementation is not inside the very code of imag.

Technically it would be possible that the content part of a file is used to
store binary data. We don't want this, though.

### Example {#sec:thestore:fileformat:example}

An example for a file in the store follows.

```text

---
[imag]
links = ["/home/user/more_kittens.mpeg"]
version = "0.2.0"

[note]
name = "foo"
---

This is an example text, written by the user.

```

## File organization {#sec:thestore:fileorganization}

The "Entries" are stored as files in the "Store", which is a directory the
user has access to.  The store may exist in the users Home-directory or any
other directory the user has read-write-Access to.

Each module stores its data in an own subdirectory in the store. This is because
we like to keep things ordered and clean, not because it is technically
necessary.

We name the path to a file in the store "Store id" or "Storepath" and we often
refer to it by using the store location as root.
So if the store exists in `/home/user/store/`, a file with the storepath
`/example.file` is (on the filesystem) located at
`/home/user/store/example.file`.

A storepath contains predefined parts:

* The module name of the Module the Entry belongs to, as said above.
  This part is always a directory.
* The version (semantic versioning applies) of the module storing the entry.
  This part is a postfix to the filename.

The pattern for the storepath is

```
/<module name>/<optional sub-folders>/<file name>~<sem version>
```

So if a module named "example-module" with version "0.1.0" stores a file in the
Store, the storepath for a file with the name "example" is
"/example-module/example~0.1.0".

Any number of subdirectories may be used, so creating folder hierarchies is
possible and valid. A file "example" for a module "module" in version "0.1.0"
would be stored in sub-folders like this:

```
/module/some/sub/folder/example~0.1.0
```

For example, it is valid if these files exist at the same time:

* /foo/bar~0.2
* /foo/bar~1.3

It might not be sane, though.

To future-proof the system it is necessary to provide a way for modules to
differentiate in their versions on the store level. Thus if a module wants to
retrieve a file from the store it must at least accept files from it's current
advertised version. It may accept older files and it may transform them and
resubmit them in the newer version.

## Store path links {#sec:thestore:links}

Linking entries is version independent.

This means if an entry "a" from a module "A" gets written to the store, it may
link to an entry "b" from a module "B", which is in version "0.1.0" at the
moment. If the module "B" gets updated, it might update its entries in the store
as well. The link from the "a" should never get invalid in this case, though it
is not ensured by the core of imag itself.