doc: Remove library documentation files
This commit is contained in:
parent
b0de23bfbf
commit
d0a5beae9a
5 changed files with 0 additions and 374 deletions
|
|
@ -1,71 +0,0 @@
|
|||
# libutil {#sec:libutil}
|
||||
|
||||
<!--
|
||||
Might not get this big, but its here for DRYness
|
||||
-->
|
||||
|
||||
The utility library of the project contains utility functionality which is
|
||||
used by all other libraries and/or binaries.
|
||||
|
||||
It is explicitely not intended for module-use only, but for all other libraries.
|
||||
|
||||
## Key-Value split {#sec:libutil:kvsplit}
|
||||
|
||||
This helper implements functionality to split key-value string into two parts.
|
||||
It was introduced to simplify commandline specification for header fields (see
|
||||
@lst:kvsplit:headerspec).
|
||||
|
||||
```{#lst:kvsplit:headerspec .bash .numberLines caption="Headerfield spec"}
|
||||
imag store create --path /some.entry entry --header field=foo
|
||||
# ^^^^^^^^^
|
||||
```
|
||||
|
||||
It is implemented by introducing a `KeyValue` type which is generic over Key
|
||||
and Value. This type gets implemented `KeyValue<String, String> for String` to
|
||||
be able to split a `String` into two `String` objects, key and value
|
||||
respectively. The implementation is realized via Regex.
|
||||
|
||||
The `KeyValue` type implementes `Into<(K, V)>` for convenience.
|
||||
|
||||
## Error tracing {#sec:libutil:errortrace}
|
||||
|
||||
The error tracing functions are functions which help printing an error chain
|
||||
to the user.
|
||||
|
||||
It allows to trace nested errors like @lst:errtrace:exampleerror to the user
|
||||
in a backtrace-ish way (@lst:errtrace:exampletrace).
|
||||
|
||||
```{#lst:errtrace:exampleerror.rust .numberLines caption="Error chain"}
|
||||
ErrA::new(a_errorkind,
|
||||
Some(Box::new(ErrB::new(b_errorkind,
|
||||
Some(Box::new(ErrC::new(c_errorkind,
|
||||
None)))
|
||||
)))
|
||||
)
|
||||
```
|
||||
|
||||
The variants of the function allow limiting the trace to a certain depth or
|
||||
printing the error trace to the debug output stream.
|
||||
|
||||
```{#lst:errtrace:exampletrace .numberLines caption="Error trace"}
|
||||
[Error][c_errorkind]: Some C-error text -- caused:
|
||||
[Error][b_errorkind]: Some B-error text -- caused:
|
||||
[Error][a_errorkind]: Some A-error text
|
||||
```
|
||||
|
||||
## Variant generator {#sec:libutil:vargen}
|
||||
|
||||
The `generate_variants()` function can be used to generate variants of a base
|
||||
vector value.
|
||||
|
||||
```{#lst:vargen:exampleuse .rust .numberLines caption="Variant generation"}
|
||||
let base = 1;
|
||||
let vars = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
|
||||
let res = generate_variants(base, vars, &|base, var| base + var);
|
||||
|
||||
assert!(res == vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
|
||||
```
|
||||
|
||||
As shown in @lst:vargen:exampleuse (from the tests), can this function
|
||||
be used to generate values from a base value.
|
||||
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
# librt {#sec:librt}
|
||||
|
||||
The runtime library provides types and functions which MUST be used by the
|
||||
modules to implement the commandline interface, configuration file parsing and
|
||||
logging.
|
||||
|
||||
The runtime library provides basic functionality for configuration file parsing
|
||||
and logging setup.
|
||||
The runtime library also provides helper functions for building a commandline
|
||||
interface.
|
||||
|
||||
## Configuration file {#sec:librt:cfg}
|
||||
|
||||
The runtime library SHOULD read the configuration file, if it can be found.
|
||||
If the configuration file cannot be found, the following variables are set to
|
||||
their default values as shown in @tbl:librt:cfg:defaultvalues.
|
||||
|
||||
| Variable | Value |
|
||||
| :------------- | :------------------- |
|
||||
| verbosity | false |
|
||||
| debugging | false |
|
||||
| store location | `$HOME/.imag/store/` |
|
||||
|
||||
Table: Default values for configuration if configuration file unavailable
|
||||
{#tbl:librt:cfg:defaultvalues}
|
||||
|
||||
### Location of the configuration file {#sec:librt:cfg:location}
|
||||
|
||||
For the configuration file is searched at the following locations:
|
||||
|
||||
1. Path: `$runtimepath/config`
|
||||
1. Path: `$runtimepath/config.toml`
|
||||
1. Path: `$runtimepath/imagrc`
|
||||
1. Path: `$runtimepath/imagrc.toml`
|
||||
1. Path: `$HOME/.imag/config`
|
||||
1. Path: `$HOME/.imag/config.toml`
|
||||
1. Path: `$HOME/.imag/imagrc`
|
||||
1. Path: `$HOME/.imag/imagrc.toml`
|
||||
1. Path: `$XDG_CONFIG_DIR/imag/config`
|
||||
1. Path: `$XDG_CONFIG_DIR/imag/config.toml`
|
||||
1. Path: `$XDG_CONFIG_DIR/imag/imagrc`
|
||||
1. Path: `$XDG_CONFIG_DIR/imag/imagrc.toml`
|
||||
1. Path in the environment variable `$IMAG_CONFIG`
|
||||
|
||||
If neither of these configuration files are found, the program MUST USE the
|
||||
default values for the minimum required variables
|
||||
(@tbl:librt:cfg:defaultvalues).
|
||||
|
||||
### Contents of the configuration file {#sec:librt:cfg:contents}
|
||||
|
||||
The contents of the configuration file MUST BE encoded in Unicode UTF-8.
|
||||
The contents of the configuration file are structured as TOML, regardless of the
|
||||
file extension.
|
||||
|
||||
The configuration file contains several sections:
|
||||
|
||||
1. The `base` section, which contains basic variables
|
||||
(@tbl:librt:cfg:contents:base)
|
||||
1. The `modules` section, which contains a section for each module.
|
||||
1. The `store` section, which contains configuration on the behaviour of the
|
||||
store (@tbl:librt:cfg:contents:store)
|
||||
|
||||
| Variable | Type |
|
||||
| :------------- | :------ |
|
||||
| verbosity | boolean |
|
||||
| debugging | boolean |
|
||||
| store location | Path |
|
||||
|
||||
Table: "Base" variables in the configuration file {#tbl:librt:cfg:contents:base}
|
||||
|
||||
|
||||
| Variable | Type | Meaning |
|
||||
| :-------- | :------ | :----------------------------------------------- |
|
||||
| git-vcs | boolean | Whether the store is version controlled with git |
|
||||
|
||||
Table: "store" variables in the configuration file {#tbl:librt:cfg:contents:store}
|
||||
|
||||
|
|
@ -1,166 +0,0 @@
|
|||
# libstore {#sec:libstore}
|
||||
|
||||
<!--
|
||||
Store functionality
|
||||
-->
|
||||
|
||||
The "libstore" MUST define the programming-language level interface to the
|
||||
store on the file system.
|
||||
The library therefor MUST define and export types which can be used to get data
|
||||
from the filesystem.
|
||||
|
||||
## Types {#sec:libstore:types}
|
||||
|
||||
The types in @tbl:libstore:types are exported by the library.
|
||||
|
||||
| Type | Meaning |
|
||||
| :------------ | :----------------------------------------------- |
|
||||
| Entry | Entity on the Filesystem, File |
|
||||
| EntryContent | User-Content of the Entry |
|
||||
| EntryHeader | Header of the Entry |
|
||||
| Store | Store interface |
|
||||
| FileLockEntry | Handle to an Entry |
|
||||
|
||||
Table: Types the store library exports {#tbl:libstore:types}
|
||||
|
||||
Each of these types MUST export functions to work with the data the objects of
|
||||
the types contain.
|
||||
|
||||
### Entry {#sec:libstore:types:entry}
|
||||
|
||||
The `Entry` type MUST hold the following content:
|
||||
|
||||
- A path where on the filesystem the acutal file lives
|
||||
- An instance of `EntryContent` as interface to the content of the file
|
||||
(@sec:libstore:types:entrycontent).
|
||||
- An instance of `EntryHeader` as interface to the header of the file
|
||||
(@sec:libstore:types:entryheader).
|
||||
|
||||
The entry type MUST export functions to get
|
||||
|
||||
- The content object
|
||||
- The header object
|
||||
- The path of the actual file
|
||||
|
||||
The entry type MUST export functions to set
|
||||
|
||||
- The header object
|
||||
- The content object
|
||||
|
||||
### EntryContent {#sec:libstore:types:entrycontent}
|
||||
|
||||
The `EntryContent` type is an type-alias for `String`.
|
||||
|
||||
### EntryHeader {#sec:libstore:types:entryheader}
|
||||
|
||||
The `EntryHeader` type is an wrapper around the type, the TOML-Parser library
|
||||
exports.
|
||||
|
||||
It SHOULD contain utility functions to work with the header in a convenient way.
|
||||
|
||||
### Store {#sec:libstore:types:store}
|
||||
|
||||
The `Store` type MUST represent the interface to the store on the filesystem.
|
||||
It MUST contain CRUD-functionality to work with the entries in the store.
|
||||
It MUST contain a variable which contains the path of the store on the
|
||||
filesystem which is represented by an object of this type.
|
||||
It also MUST contain a getter for this variable.
|
||||
It MUST NOT contain a setter for this variable, as changing the store while the
|
||||
programm is running is not allowed.
|
||||
|
||||
## Hook system {#sec:libstore:hooks}
|
||||
|
||||
The store library includes a hook system, which can be used to execute arbitrary
|
||||
code before or after the store was accessed. The following hooks are available:
|
||||
|
||||
* `PreReadHook`
|
||||
* `PostReadHook`
|
||||
* `PreCreateHook`
|
||||
* `PostCreateHook`
|
||||
* `PreUpdateHook`
|
||||
* `PostUpdateHook`
|
||||
* `PreDeleteHook`
|
||||
* `PostDeleteHook`
|
||||
|
||||
These are called "Hook positions" in the following.
|
||||
|
||||
Which are executed before or after the store action is executed. The `Pre`-Hooks
|
||||
can deny the execution by returning an error. The `Post`-Hooks can (for the
|
||||
appropriate store actions) alter the hook result.
|
||||
|
||||
Registering hooks with the store is implemented via functions on the `Store`
|
||||
type itself. Hooks MUST NEVER be removed from the `Store` object during runtime,
|
||||
only adding hooks to the store is allowed.
|
||||
|
||||
As the hooks are simply trait objects, one is able to implement arbitrary hooks,
|
||||
for example
|
||||
|
||||
* Simple consistency-checks for the store
|
||||
* Version control system adaption for the store (via git for example)
|
||||
* Encryption of store entries (via gnupg for example)
|
||||
* Automatic backup on every change to the store (via rsnapshot for example)
|
||||
|
||||
Some hooks MAY be shipped with the imag source distribution and be enabled by
|
||||
default.
|
||||
|
||||
Execution order of the hooks is a not-yet-solved problem.
|
||||
|
||||
### Hook-Aspects {#sec:libstore:hooks:aspects}
|
||||
|
||||
Each hook can be assigned to an "Aspect". There MAY BE zero or more aspects for
|
||||
each Hook position. Aspects can be sorted and configured via the configuration
|
||||
file, whereas each aspect has its own configuration section:
|
||||
|
||||
```{#lst:hooks:aspects:cfg .toml .numberLines caption="Hook config section"}
|
||||
[store]
|
||||
|
||||
// Defines order of aspects for the pre-read hook position
|
||||
pre-read-aspects = [ "misc" ]
|
||||
|
||||
// Defines order of aspects for the post-read hook position
|
||||
post-read-aspects = [ "decryption" ]
|
||||
|
||||
// ...
|
||||
|
||||
// configuration for the "misc" hook aspect
|
||||
[[aspects.misc]]
|
||||
parallel-execution = true
|
||||
|
||||
// configuration for the "decryption" hook aspect
|
||||
[[aspects.decryption]]
|
||||
parallel-execution = false
|
||||
```
|
||||
|
||||
Aspects are executed in the same order they appear in the configuration (in the
|
||||
`pre-read-aspects = []` array, for example).
|
||||
Aspects _could_ be sorted in different order for each hook position.
|
||||
|
||||
Aspect names are unique, so one aspect "misc" in "pre-read-aspects" is the
|
||||
same as in "post-read-aspects" and both be configured via `aspects.misc`, though
|
||||
they do not share hooks.
|
||||
|
||||
Aspects where parallel execution is enabled MAY BE executed in sequence if one
|
||||
of the hooks wants mutable access to the data they hook into.
|
||||
|
||||
Hooks can then be assigned to one hook aspect. Hooks MUST never be assigned to
|
||||
more than one hook aspect. Hooks which are not assigned to any aspect MUST never
|
||||
be executed.
|
||||
|
||||
```{#lst:hooks:cfg .toml .numberLines caption="Hook configuration"}
|
||||
[hooks]
|
||||
|
||||
// decrypt hook with gnupg. An appropriate "gnupg-encrypt" hook must be defined
|
||||
// to be fully operational, of course
|
||||
[[gnupg-decrypt]]
|
||||
aspect = "decryption"
|
||||
key = "0x123456789"
|
||||
|
||||
// version control hook. Sorted into aspect "misc" here.
|
||||
[[git]]
|
||||
aspect = "misc"
|
||||
|
||||
// ...
|
||||
```
|
||||
|
||||
Hooks MAY HAVE arbitrary configuration keys.
|
||||
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
# liblink {#sec:liblink}
|
||||
|
||||
The "liblink" library contains functionality for linking from entries to
|
||||
internal and external content.
|
||||
|
||||
The utilities provided by "liblink" contain functions to
|
||||
|
||||
* Get internal links from arbitraty entries
|
||||
* Access an "EntryHeader" object to
|
||||
* get internal links
|
||||
* set internal links
|
||||
* get "Entry" objects for links from a header
|
||||
|
||||
## Linking internal content with liblink {#sec:liblink:internal}
|
||||
|
||||
As one entry MAY contain zero or more interal links in the header section
|
||||
"imag.links", the "liblink" library provides functionality to
|
||||
|
||||
* get the link from an EntryHeader object
|
||||
* set the links in a EntryHeader object
|
||||
* query for a specific link in a EntryHeader object
|
||||
* by regex
|
||||
* by module name
|
||||
* by filename
|
||||
|
||||
as well as functionality to get "Entry" objects for each entry in the Header.
|
||||
|
||||
## Linking external content with liblink {#sec:liblink:external}
|
||||
|
||||
As one "EntryHeader" MUST NOT contain more than one link to external content (as
|
||||
defined in @sec:thestore:linking:external, the following scheme for linking to
|
||||
external content MUST BE provided by "liblink":
|
||||
|
||||
* Generate a "link" entry in the store
|
||||
* with store path starting with "/link/"
|
||||
* where the header field "imag.content.uri" MUST BE set
|
||||
* with optional content which can be stored in the section of the "liblink"
|
||||
module section (section name "link", as defined by
|
||||
@sec:thestore:fileformat:header:module).
|
||||
* Get an external link by store path (looking up the store path entry and
|
||||
getting the link to the external content from it)
|
||||
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
# libtag {#sec:libtag}
|
||||
|
||||
The "libtag" library contains functionality for tagging entries.
|
||||
|
||||
The following functionality for entries is provided:
|
||||
|
||||
* Adding a tag to an entry
|
||||
* Removing a tag from an entry
|
||||
* Fetching the list of tags from an entry
|
||||
* Checking whether a tag is set in an entry
|
||||
|
||||
The following additional functionality is provided:
|
||||
|
||||
* Fetching all entries which contain a tag
|
||||
* Fetching all entries which contain a list of tags
|
||||
* Fetching all entries which fulfill a set of tag-requirements (either
|
||||
present, or not present, chained by logical operators)
|
||||
|
||||
Loading…
Reference in a new issue