2016-01-08 17:28:31 +00:00
|
|
|
# The Store {#sec:thestore}
|
|
|
|
|
|
|
|
## File Format {#sec:thestore:fileformat}
|
|
|
|
|
2016-01-10 16:34:53 +00:00
|
|
|
The content in the store MUST BE encoded in either Unicode UTF-8 or ASCII.
|
|
|
|
Each "Entry" (File) MUST HAVE a "Header" component as well as a "Content"
|
|
|
|
component.
|
|
|
|
Each "Entry" in the store MUST start with three single dashes ("-") followed
|
|
|
|
by a newline character, named "initial marker" in the following chapter.
|
|
|
|
The Header follows the initial marker (@sec:thestore:fileformat:header).
|
|
|
|
The Header MUST BE followed by a line which contains three single dashes ("-")
|
|
|
|
and a newline character, called "header-close marker" in the following
|
|
|
|
chapter.
|
|
|
|
The content follows the header-close marker (@sec:thestore:fileformat:content).
|
|
|
|
|
|
|
|
### Header Format {#sec:thestore:fileformat:header}
|
|
|
|
|
|
|
|
The header format MUST BE "TOML".
|
|
|
|
The contents of the header contain
|
|
|
|
|
|
|
|
1. A section called "imag", where the automatically by the program generated
|
|
|
|
data goes to.
|
|
|
|
The contents of these sections are edited via commandline calls or by the
|
|
|
|
program implicitely and SHOULD NOT be edited by the user.
|
2016-01-11 08:29:13 +00:00
|
|
|
Modules of the program are free to store arbitrary data here.
|
|
|
|
If a module stores data in the header of a file it MUST do that in a
|
2016-01-12 16:09:04 +00:00
|
|
|
dedicated section, as TOML supports it.
|
2016-01-19 13:41:44 +00:00
|
|
|
Exceptions are:
|
|
|
|
|
|
|
|
* A module MAY collect URIs and put it into a flat list in the subsection
|
|
|
|
"imag.links".
|
|
|
|
* A section "imag.content" MAY BE used for refering to external content.
|
|
|
|
Valid keys in this section are "uri", "file" and "mime", whereas
|
|
|
|
- "uri" refers to the external content
|
|
|
|
- "file" refers to a local variant, this is optional
|
|
|
|
- "mime" stores the MIME-Type of the local variant, if present.
|
|
|
|
|
2016-01-10 16:34:53 +00:00
|
|
|
1. Other OPTIONAL sections which are named and edited by the user. The program
|
|
|
|
MUST NOT touch the contents of these sections, except explicitely asked by
|
|
|
|
the user to do so.
|
|
|
|
|
|
|
|
### 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 program SHOULD NOT expect any particular markup format, except explicitely
|
|
|
|
configured in the header of the file.
|
|
|
|
|
2016-01-12 12:07:04 +00:00
|
|
|
### Example {#sec:thestore:fileformat:example}
|
|
|
|
|
|
|
|
An example for a file in the store follows.
|
|
|
|
|
|
|
|
```
|
|
|
|
---
|
|
|
|
[imag]
|
|
|
|
nothing = here
|
|
|
|
[imag.examplemodule]
|
|
|
|
and_nothing = here_as_well
|
|
|
|
---
|
|
|
|
|
|
|
|
This is an example text, written by the user.
|
|
|
|
|
|
|
|
```
|
|
|
|
|
2016-01-08 17:28:31 +00:00
|
|
|
## File organization {#sec:thestore:fileorganization}
|
|
|
|
|
2016-01-10 17:07:05 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
The Path of each File is shown as absolute path in this paper, while the root
|
|
|
|
is always the store directory.
|
|
|
|
This Path is named "Storepath".
|
|
|
|
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`.
|
|
|
|
|
2016-01-19 13:34:58 +00:00
|
|
|
A Storepath contains predefined parts:
|
|
|
|
|
|
|
|
* The module name of the Module the Entry belongs to.
|
|
|
|
This part is 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 "ExampleModule" with version "0.1" stores a file in the
|
|
|
|
Store, the Storepath for a file with the name "example" is
|
|
|
|
"/ExampleModule/example~0.1".
|
2016-01-10 17:07:05 +00:00
|
|
|
|
|
|
|
Any number of subdirectories MAY BE used, so creating folder hierarchies is
|
|
|
|
possible and valid.
|
2016-01-19 13:34:58 +00:00
|
|
|
A file "example" for a module "module" in version "0.1" would be stored in
|
|
|
|
sub-folders like this:
|
|
|
|
|
|
|
|
```
|
|
|
|
/module/some/sub/folder/example~0.1
|
|
|
|
```
|
|
|
|
|
2016-01-19 13:35:13 +00:00
|
|
|
## Store path links {#sec:thestore:links}
|
|
|
|
|
|
|
|
Linking entries MUST BE 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" at the moment.
|
|
|
|
If the module "B" gets updated, it might update its entries in the store as
|
|
|
|
well.
|
|
|
|
The link from the "a" MUST NOT get invalid in this case.
|
|
|
|
|
|
|
|
This is accomplished by linking without the version number: So a link for the
|
|
|
|
entry
|
|
|
|
|
|
|
|
```
|
|
|
|
/module/some/sub/folder/example~0.1
|
|
|
|
```
|
|
|
|
|
|
|
|
is
|
|
|
|
|
|
|
|
```
|
|
|
|
imag://module/some/sub/folder/example
|
|
|
|
```
|
|
|
|
|
|
|
|
As shown in the example, a link to imag-internal entries, the link is prefixed
|
|
|
|
with a "imag://" identifier.
|
|
|
|
A link to external content MUST NEVER be prefixed this way.
|
|
|
|
The path of the internal link MUST NEVER be relative, but always absolute from
|
|
|
|
the root directory of the store.
|
2016-01-10 17:07:05 +00:00
|
|
|
|