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.
|
|
|
|
The name of the section MUST BE the name of the module in lowercase
|
2016-01-11 08:29:13 +00:00
|
|
|
letters.
|
2016-01-10 16:34:53 +00:00
|
|
|
The section MAY BE empty.
|
|
|
|
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-10 17:07:05 +00:00
|
|
|
|