From 6f31432f22a761832b1b3262eb44b95b9db57394 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Fri, 31 May 2019 20:15:33 +0200 Subject: [PATCH] update design doc --- CONTRIBUTING.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a8f1c9..6aeaac4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,8 +15,10 @@ Dotdrop's code base is located in the [dotdrop directory](/dotdrop). Here's an overview of the different files and their role: * **action.py**: represent the actions and transformations +* **cfg_yaml.py**: the lower level config parser +* **cfg_aggregator.py**: the higher level config parser * **comparator.py**: the class handling the comparison for `compare` -* **config.py**: the config file (*config.yaml*) parser +* **dictparser.py**: abstract class for parsing dictionaries * **dotdrop.py**: the entry point and where the different cli commands are executed * **dotfile.py**: represent a dotfile * **installer.py**: the class handling the installation of dotfile for `install` @@ -24,10 +26,54 @@ Here's an overview of the different files and their role: * **linktypes.py**: enum for the three types of linking (none, symlink, children) * **logger.py**: the custom logger * **options.py**: the class embedding all the different options across dotdrop +* **profile.py**: represent a profile +* **settings.py**: represent the config settings * **templategen.py**: the jinja2 templating class * **updater.py**: the class handling the update of dotfiles for `update` * **utils.py**: some useful methods +## Config parsing + +The configuration file (yaml) is parsed in two layers: + + * the lower layer in `cfg_yaml.py` + * the higher layer in `cfg_aggregator.py` + +Only the higher layer is accessible to other classes of dotdrop. + +The lower layer part is only taking care of basic types and +does the following: + * normalize all config entries + * resolve paths (dotfiles src, dotpath, etc) + * refactor actions to a common format + * etc + * import any data from external files (configs, variables, etc) + * apply variable substitutions + * complete any data if needed (add the "profile" variable, etc) + * execute intrepreted variables through the shell + * write new entries (dotfile, profile) into the dictionary and save it to a file + * fix any deprecated entries (link_by_default, etc) + * clear empty entries + +In the end it makes sure the dictionary (or parts of it) accessed +by the higher layer is clean and normalize. + +The higher layer will transform the dictionary parsed by the lower layer +into objects (profiles, dotfiles, actions, etc). +The higher layer has no notion of inclusion (profile included for example) or +file importing (import actions, etc) or even interpreted variables +(it only sees variables that have already been interpreted). + +It does the following: + * transform dictionaries into objects + * patch list of keys with its corresponding object (for example dotfile's actions) + * provide getters for every other classes of dotdrop needing to access elements + +Note that any change to the yaml dictionary (adding a new profile or a new dotfile for +example) won't be *seen* by the higher layer until the config is reloaded. Consider the +`dirty` flag as a sign the file needs to be written and its representation in higher +levels in not accurate anymore. + # Testing Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.