matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Auto merge of #123 - matthiasbeyer:doc/redefine-store-orga, r=matthiasbeyer

Browse source 
Doc/redefine store orga

As proposed in personal discussion with @TheNeikos
This commit is contained in:
Homu 2016-01-19 07:50:34 -08:00
commit 4c426bc8ed
1 changed files with 51 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
doc/src/02000-store.md
View file

@ -71,11 +71,58 @@ 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 one predefined part: The module name of the Module the
Entry belongs to, in lowercase letters.
So if a Module named "ExampleModule" stores a file in the Store, the Storepath
for a file with the name "example.file" is "/examplemodule/example.file".
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".
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" would be stored in
sub-folders like this:
```
/module/some/sub/folder/example~0.1
```
## 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.