feat: parent parameter (#53)

* lib/attrset: add splitStrPath

* lib/attrset: add mkModuleArgs

though getAttrByStrPath is used, it is used only in `delib.module` for
the user's api.

with this function i tried to cover `delib.host` and `delib.rice` as
well.

* lib/configurations/module: rename wrap argument to x

for consistency with other configuration modules. also "object" doesn't
make much sense in a semantic way, but 'x' is short and easy on the eyes

* lib/configurations/hosts: change todo to note

i think that's more appropriate

* docs/src/modules/structure: add parent argument

also change cfg's description to a more readable one. i think using an
approach like "literally describe what the code does" in the
documentation is pointless, because the code is just available and the
users can find it by themselves

* docs/src/modules/structure: 'equal' typo

as i remember, "to" is not used for "equals", but for "equal"

* docs/src/hosts/structure: parent argument

a funny issue was discovered: name in the modules was split by dots, but
not in the hosts.

i updated the documentation to chase the current working state of the
branch, so i added a disclaimer for the usage of dot characters in the
name.

i don't actually know what should be done here. parent is probably not
very useful to the hosts, but host function by itself is almost a wrapper
around the module function, so should it provide less functionality?
maybe the user defined the hosts module by themselves and some useful
values were defined here.

the current logic is likely broken if host contains dots. a single
string is used in lib/configuration/host.nix to define config (see the
note), but the name is split in mkModuleArgs. the situation is identical
for rices.

i see two resolutions here:

- use parent argument only for the modules and rollback the changes of
  using mkModuleArgs - preserve previous behaviour
- add an additional argument to mkModuleArgs to not split the name -
  just fixing the issue as an edgecase

aside from that, in either way, the library results in a bit inconsistent
behaviour, because dots are used as split characters for the modules, but
not for the hosts or rices.

for the hosts, i see no reason to use the dots, because host is just a
host. host is a singular entity and nesting hosts seems unlikely. maybe
allowing dots is actually good, because gives freedom to the user for
the naming.

but for the rices, i don't know. maybe nesting rices could be cool,
because you can have a main "flavour" and nested "subflavours". and
these subflavours would automatically inherit options from the parent.
this seems like a cool application of the parent argument as a whole.

but hosts and rices use assertions for the names, and right now the data
structure for the assertions is a plain list, because the names cannot
be nested. if nesting would be allowed, then a tree-like structure of
attributes should be converted to a list.

and the issue with infinite recursion should be resolved as well, if we
want to allow nesting.

i, personally, would stick with the second resolution to fix this issue
and provide parent to hosts and rices, because i see no harm in it. the
matter with the nesting can be handled later.

* Revert "docs/src/hosts/structure: parent argument"

This reverts commit b8c6afe.

* lib/configurations/host!: don't use mkModuleArgs

essentially, reverts the functionality to the original state

personally, i really don't like the repetition here, but refactoring of
the logic that's not tied to the parent argument is not in the scope for
this branch, if the parent argument is not implemented here

* lib/configurations/rice!: don't use mkModuleArgs

the reasoning is the same as for the hosts

* lib/attrset!: -mkModuleArgs, +splitStrPath

splitStrPath is minimal, and used for other exported functions, so it's
pretty safe to export.

but mkModuleArgs is only used in one place, so it's been moved to the
lib/configurations/module. and without the category functionality,
because it's not needed anymore.

* docs/src/ru/modules/structure: parent argument

chase english docs

Author: shimeoki

docs/src/modules/structure.md

@@ -17,40 +17,41 @@ This section uses the variables `myconfigName`, `moduleSystem`, and `homeManager
 A list of arguments passed to `options` and `[myconfig|nixos|home|darwin].[ifEnabled|ifDisabled|always]`, if their type is a `lambda`:
 - `name`: the same [name](#function-arguments-name) from the `delib.module` arguments.
 - `myconfig`: equals `config.${myConfigName}`.
-- `cfg`{#passed-arguments-cfg}: equals the result of the expression `delib.getAttrByStrPath name config.${myConfigName} {}`, where `name` is the [argument](#function-arguments-name) from `delib.module`, and `{}` is the value returned if the attribute is not found.
+- `cfg`{#passed-arguments-cfg}: essentially, the config values (assigned options) of the current module. In other words, equals `config.${myConfigName}.${name}`, where `name` is the [argument](#function-arguments-name) from `delib.module` and is "expanded" (converted to a valid attribute path).
+- `parent`: equal to the "parent" module (attribute set) of `cfg`. Example: `parent` is `config.${myConfigName}.programs` if `cfg` is `config.${myConfigName}.programs.example`.
 
 ## Pseudocode {#pseudocode}
 ```nix
 delib.module {
   name = "";
 
   # options.${myConfigName} = ...
-  options = {name, cfg, myconfig, ...}: {};
+  options = {name, cfg, parent, myconfig, ...}: {};
 
   # config.${myConfigName} = ...
-  myconfig.ifEnabled = {name, cfg, myconfig, ...}: {};
-  myconfig.ifDisabled = {name, cfg, myconfig, ...}: {};
-  myconfig.always = {name, cfg, myconfig, ...}: {};
+  myconfig.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  myconfig.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  myconfig.always = {name, cfg, parent, myconfig, ...}: {};
 
   # if moduleSystem == "nixos"
   # then {config = ...;}
   # else {}
-  nixos.ifEnabled = {name, cfg, myconfig, ...}: {};
-  nixos.ifDisabled = {name, cfg, myconfig, ...}: {};
-  nixos.always = {name, cfg, myconfig, ...}: {};
+  nixos.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  nixos.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  nixos.always = {name, cfg, parent, myconfig, ...}: {};
 
   # if moduleSystem == "home"
   # then {config = ...;}
   # else {config.home-manager.users.${homeManagerUser} = ...;}
-  home.ifEnabled = {name, cfg, myconfig, ...}: {};
-  home.ifDisabled = {name, cfg, myconfig, ...}: {};
-  home.always = {name, cfg, myconfig, ...}: {};
+  home.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  home.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  home.always = {name, cfg, parent, myconfig, ...}: {};
 
   # if moduleSystem == "darwin"
   # then {config = ...;}
   # else {}
-  darwin.ifEnabled = {name, cfg, myconfig, ...}: {};
-  darwin.ifDisabled = {name, cfg, myconfig, ...}: {};
-  darwin.always = {name, cfg, myconfig, ...}: {};
+  darwin.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  darwin.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  darwin.always = {name, cfg, parent, myconfig, ...}: {};
 }
 ```

docs/src/ru/modules/structure.md

@@ -17,40 +17,41 @@
 Список аргументов, которые передаются в `options` и `[myconfig|nixos|home|darwin].[ifEnabled|ifDisabled|always]`, если их тип - это `lambda`:
 - `name`: тот же [name](#function-arguments-name) из аргументов `delib.module`.
 - `myconfig`: равен `config.${myConfigName}`.
-- `cfg`{#passed-arguments-cfg}: равен результату выражения `delib.getAttrByStrPath name config.${myConfigName} {}`, где `name` - это [аргумент](#function-arguments-name) `delib.module`, а `{}` - значение, которое возвращается, если атрибут не найден.
+- `cfg`{#passed-arguments-cfg}: по сути, значения (присвоенные) из конфигурации текущего модуля. Другими словами, равняется `config.${myConfigName}.${name}`, где `name` это [аргумент](#function-arguments-name) из `delib.module`, "раскрывающийся" (конвертируется в валидный путь как атрибут) при этом.
+- `parent`: равняется модулю-"родителю" (набору атрибутов) `cfg`. Пример: `parent` это `config.${myConfigName}.programs`, если `cfg` это `config.${myConfigName}.programs.example`.
 
 ## Псевдокод {#pseudocode}
 ```nix
 delib.module {
   name = "";
 
   # options.${myConfigName} = ...
-  options = {name, cfg, myconfig, ...}: {};
+  options = {name, cfg, parent, myconfig, ...}: {};
 
   # config.${myConfigName} = ...
-  myconfig.ifEnabled = {name, cfg, myconfig, ...}: {};
-  myconfig.ifDisabled = {name, cfg, myconfig, ...}: {};
-  myconfig.always = {name, cfg, myconfig, ...}: {};
+  myconfig.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  myconfig.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  myconfig.always = {name, cfg, parent, myconfig, ...}: {};
 
   # если moduleSystem == "nixos"
   # то {config = ...;}
   # иначе {}
-  nixos.ifEnabled = {name, cfg, myconfig, ...}: {};
-  nixos.ifDisabled = {name, cfg, myconfig, ...}: {};
-  nixos.always = {name, cfg, myconfig, ...}: {};
+  nixos.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  nixos.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  nixos.always = {name, cfg, parent, myconfig, ...}: {};
 
   # если moduleSystem == "home"
   # то {config = ...;}
   # иначе {config.home-manager.users.${homeManagerUser} = ...;}
-  home.ifEnabled = {name, cfg, myconfig, ...}: {};
-  home.ifDisabled = {name, cfg, myconfig, ...}: {};
-  home.always = {name, cfg, myconfig, ...}: {};
+  home.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  home.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  home.always = {name, cfg, parent, myconfig, ...}: {};
 
   # если moduleSystem == "darwin"
   # то {config = ...;}
   # иначе {}
-  darwin.ifEnabled = {name, cfg, myconfig, ...}: {};
-  darwin.ifDisabled = {name, cfg, myconfig, ...}: {};
-  darwin.always = {name, cfg, myconfig, ...}: {};
+  darwin.ifEnabled = {name, cfg, parent, myconfig, ...}: {};
+  darwin.ifDisabled = {name, cfg, parent, myconfig, ...}: {};
+  darwin.always = {name, cfg, parent, myconfig, ...}: {};
 }
 ```

lib/attrset.nix

@@ -1,10 +1,12 @@
-{ lib, ... }:
+{ lib, delib, ... }:
 {
+  splitStrPath = lib.splitString ".";
+
   getAttrByStrPath =
     strPath: attrset: default:
-    lib.attrByPath (lib.splitString "." strPath) default attrset;
+    lib.attrByPath (delib.splitStrPath strPath) default attrset;
 
-  setAttrByStrPath = strPath: value: lib.setAttrByPath (lib.splitString "." strPath) value;
+  setAttrByStrPath = strPath: value: lib.setAttrByPath (delib.splitStrPath strPath) value;
 
   hasAttrs =
     attrs: attrset:

lib/configurations/module.nix

@@ -20,17 +20,31 @@
         (
           { config, ... }:
           let
-            cfg = delib.attrset.getAttrByStrPath name config.${myconfigName} { };
+            args =
+              let
+                # instance of the user's config attrset, not the
+                # same as myconfig in the outer scope
+                myconfig = config.${myconfigName};
 
-            wrap =
-              object:
-              if builtins.typeOf object == "lambda" then
-                object {
-                  inherit name cfg;
-                  myconfig = config.${myconfigName};
-                }
-              else
-                object;
+                cfgPath = delib.attrset.splitStrPath name;
+
+                fromPath = with lib; path: if (length path) > 0 then attrByPath path { } myconfig else myconfig;
+
+                cfg = fromPath cfgPath;
+                parent = fromPath (lib.dropEnd 1 cfgPath);
+              in
+              {
+                inherit
+                  name
+                  myconfig
+                  cfg
+                  parent
+                  ;
+              };
+
+            inherit (args) cfg;
+
+            wrap = x: if builtins.typeOf x == "lambda" then x args else x;
 
             defaults =
               {