Updater
Documentation for the most robust feature of the library; made easy.
Content for advanced users only. Read only if you'd like to know how the updater works.
WIP docs for release 1.3.
Updater is used to adapt documents, update their content, to suit the content defined by the defaults - while simutaneously doing everything automatically and keeping all comments. This is a perfect solution for "reset your config" headache, with just one line of code.
Defaults must contain at least all the required content (options) for the updater to work properly.
You can configure the updater's behaviour using UpdaterSettings. The full (=complete) updater process consists of 5 stages:
loading version IDs of the document and defaults,
comparing the IDs (to check if updating, downgrading...),
applying relocations to the document (if the files are not the same version ID),
marking ignored blocks in the document,
merging both files.
Would like to know more?
This is a brief documentation. Feel free to contact us, or browse the source code.
1. Loading version IDs
Updater uses the versioning provided using the settings (if any), to obtain version IDs of both the document that's being updated and defaults.
If the version ID of the defaults could not be parsed, the updater exits with an NPE. If the ID of the document could not be obtained, or parsed, the first ID specified by the pattern is assigned to it.
If no versioning is specified, proceeds directly to merging (5th stage).
2. Comparing the IDs
Updater compares the version IDs. Let A be the ID of the document and B of the defaults. If
A = B: it means that no update is needed and the updater exits.
A > B: a downgrade is needed. If enabled by the settings, proceeds directly to merging (5th stage). Throws an error otherwise.
A < B: an upgrade is needed.
3. Applying relocations
Let A be the ID of the document and B of the defaults, the updater applies all relocations specified within the range of (A, B>.
This is a mathematical notation, which represents all IDs from A (exclusive) to B (inclusive).
4. Marking ignored blocks
Set of routes to ignore, for the version ID of the defaults, is obtained and all corresponding blocks are marked.
5. Merging
The updater merges the document with the defaults. To be more exact:
Content present in both the document and defaults is merged as defined by the merge rules.
Content present in the defaults, but not in the document, is deep cloned into the document. This way, the updater keeps no reference to the defaults.
Content which is present in the document, but not in defaults and is deleted from the user file, unless keeping is enabled by the settings.
The steps mentioned above do not apply to ignored blocks, which are skipped immediately and will not be changed (including their contents, if section).
This is the last step -> the updater exits.
Last updated