imag/doc/src/05100-lib-entryref.md

55 lines
2 KiB
Markdown
Raw Normal View History

## libimagentryref
2016-08-24 12:12:05 +00:00
This library crate contains functionality to generate _references_ within the
imag store.
A reference is a "pointer" to a file or directory on the filesystem and outside
the store.
It differs from `libimagentrylink`/external linking as
2016-08-24 12:12:05 +00:00
it is designed exclusively for filesystem references, not for URLs.
A reference is created with a unique identifier, like a hash. The implementation
how this hash is calculated can be defined by the user of `libimagentryref`.
2016-08-24 12:12:05 +00:00
So this library helps to resemble something like a _symlink_.
2016-08-24 12:12:05 +00:00
### Usage
2016-08-24 12:12:05 +00:00
Users have to implement the `UniqueRefPathGenerator` trait which should
implement a hashing functionality for pathes.
2016-08-24 12:12:05 +00:00
### Limits
2016-08-24 12:12:05 +00:00
This is _not_ intended to be a version control system or something like that.
2016-08-24 12:12:05 +00:00
We also can not use _real symlinks_ as we need imag-store-objects to be able to
link stuff.
### Usecase
2016-08-24 12:12:05 +00:00
This library offers functionality to refer to content outside of the store.
It can be used to refer to _nearly static stuff_ pretty easily - think of a
Maildir - you add new mails by fetching them, but you mostly do not remove
mails.
If mails get moved, they can be re-found via their hash, because Maildir objects
hardly change. Or because the hash implementation which is used to refer to them
hashes only the `Message-Id` and that does not change.
2016-08-24 12:12:05 +00:00
2017-02-20 13:45:43 +00:00
### Long-term TODO
Not implemented yet:
2017-02-20 13:45:43 +00:00
- [ ] Re-finding of files via their hash.
This must be implemented with several things in mind
* The user of the library should be able to provide a way how the
filesystem is searched. Basically a Functor which yields pathes to
check based on the original path of the missing file.
This enables implementations which do only search a certain subset
of pathes, or does depth-first-search rather than
breadth-first-search.
2017-02-20 13:45:43 +00:00
2018-06-13 23:36:22 +00:00
### Known problems
The functionality this library provides fails to work when syncing the imag
store between two devices where the data layout is different on each device.