update contrib

CONTRIBUTING.md

@@ -41,7 +41,25 @@ The configuration file (yaml) is parsed in two layers:
 
 Only the higher layer is accessible to other classes of dotdrop.
 
-The lower layer part is only taking care of basic types and
+**Rules**
+
+* `dynvariables` are executed in their own config file
+* profile cannot include profiles defined above in the import tree
+* config files do not have access to variables
+  defined above in the import tree
+
+**Precedence**
+
+* `dynvariables` > `variables`
+* profile `(dyn)variables` > any other `(dyn)variables`
+* profile `(dyn)variables` > profile's included `(dyn)variables`
+* imported `variables`/`dynvariables` > `(dyn)variables`
+* actions/transformations  using variables are resolved at runtime
+  (when action/transformation is executed) and not when loading the config
+
+## lower layer (cfg_yaml.py)
+
+The lower layer part is only taking care of basic types
 does the following:
   * normalize all config entries
     * resolve paths (dotfiles src, dotpath, etc)
@@ -55,9 +73,11 @@ does the following:
   * fix any deprecated entries (link_by_default, etc)
   * clear empty entries
 
-In the end it makes sure the dictionary (or parts of it) accessed
+In the end it makes sure the dictionary accessed
 by the higher layer is clean and normalized.
 
+## higher layer (cfg_aggregator.py)
+
 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
@@ -74,36 +94,33 @@ example) won't be *seen* by the higher layer until the config is reloaded. Consi
 `dirty` flag as a sign the file needs to be written and its representation in higher
 levels in not accurate anymore.
 
-## Variables resolution
+## Variables resolution in the config file
 
-How variables are resolved (pass through jinja2's
+How variables are resolved (through jinja2's
-templating function) in the config file.
+templating) in the config file.
 
-* resolve `include` (the below merge is temporary just to resolve the `includes`)
+* resolve main config file variables
-  * `variables` and `dynvariables` are first merged and recursively resolved
+  * `variables` and `dynvariables` are recursively templated
   * `dynvariables` are executed
-  * they are all merged and `include` paths are resolved
+  * both `variables` and `dynvariables` are merged
+  * profile's `variables` and `dynvariables` are merged
+* resolve *included* entries (see below)
+  * paths and entries are templated
     (allows to use something like `include {{@@ os @@}}.variables.yaml`)
-* `variables` and profile's `variables` are merged
+* *included* entries are processed
-* `dynvariables` and profile's `dynvariables` are merged
+  * dyn-/variables are all resolved in their own file
-* `dynvariables` are executed
-* they are all merged into the final *local* `variables`
 
-These are then used to resolve different elements in the config file:
+*included*
+
+* entry *import_actions*
+* entry *import_configs*
+* entry *import_variables*
+* profile's *import*
+* profile's *include
+
+Variables are then used to resolve different elements in the config file:
 see [this](https://github.com/deadc0de6/dotdrop/wiki/config-variables#config-available-variables)
 
-Then additional variables (`import_variables` and `import_configs`) are
-then merged and take precedence over local variables.
-
-Note:
-
-* `dynvariables` > `variables`
-* profile `(dyn)variables` > any other `(dyn)variables`
-* profile `(dyn)variables` > profile's included `(dyn)variables`
-* imported `variables`/`dynvariables` > `(dyn)variables`
-* actions/transformations  using variables are resolved at runtime
-  (when action/transformation is executed) and not when loading the config
-
 # Testing
 
 Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.

dotdrop/cfg_yaml.py

@@ -89,47 +89,6 @@ class CfgYaml:
     lnk_link = LinkTypes.LINK.name.lower()
     lnk_children = LinkTypes.LINK_CHILDREN.name.lower()
 
-    # TODO
-    #
-    # "include" entries:
-    #   - import_actions
-    #   - import_configs
-    #   - import_variables
-    #   - profile's import
-    #   - profile's include
-    #
-    # variable precedence:
-    # 1) profile variable
-    # 2) "import_variables" variables
-    # 3) "import_configs" variables
-    # 4) other variables
-    #
-    # rules:
-    # - dynvariables are executed in their own config file
-    # - profile cannot include profiles defined above in the import tree
-    # - config files do not have access to variables
-    #   defined above in the import tree
-    #
-    # parse a config file
-    # - parse settings
-    # - parse variables
-    #   - interprete dynvariables
-    #   - template the include entries
-    # - parse profiles
-    # - parse dotfiles
-    # - parse other elements (actions, trans_r, trans_w)
-    # - parse and integrate included elements (see below)
-    #
-    # parse "include" entry
-    # - same as parse config file
-    # - add new entry to the top dict
-    #
-    # TODO
-    # - properly handle the included profile
-    # - document precedence in wiki
-    # - document parsing in CONTRIBUTING.md
-    #
-
     def __init__(self, path, profile=None, addprofiles=[], debug=False):
         """
         config parser