lib/types: add record (simplified submodule)

lib/tests/modules.sh

@@ -107,6 +107,43 @@ checkConfigError() {
     fi
 }
 
+# record field
+checkConfigOutput '^"Alice"$' config.people.alice.name ./declare-record.nix ./define-record-alice.nix ./define-record-bob.nix
+checkConfigOutput '^2019$' config.people.bob.nixerSince ./declare-record.nix ./define-record-alice.nix ./define-record-bob.nix
+
+# record field type error
+checkConfigError 'A definition for option .people.mallory.nixerSince. is not of type .signed integer.. Definition values' config.people.mallory.nixerSince ./declare-record.nix ./define-record-mallory.nix
+checkConfigError 'define-record-mallory.nix.: "beginning of time"' config.people.mallory.nixerSince ./declare-record.nix ./define-record-mallory.nix
+
+# record field default
+checkConfigOutput '^true$' config.people.bob.isCool ./declare-record.nix ./define-record-alice.nix ./define-record-bob.nix
+
+# record field bad default definition
+checkConfigError 'In .the default value of option people.mallory.: "yeah"' config.people.mallory.isCool ./declare-record-bad-default.nix ./define-record-mallory.nix
+checkConfigError 'A definition for option .people.mallory.isCool. is not of type .boolean.. Definition values:' config.people.mallory.isCool ./declare-record-bad-default.nix ./define-record-mallory.nix
+
+# record field works in presence of wildcard
+checkConfigOutput '^2016$' config.people.alice.nixerSince ./declare-record-wildcard.nix ./define-record-alice-prefs.nix
+
+# record wildcard field
+checkConfigOutput '^true$' config.people.alice.mechKeyboard ./declare-record-wildcard.nix ./define-record-alice-prefs.nix
+
+# record definition without corresponding field
+checkConfigError 'A definition for option .people.mike. has an unknown field' config.people.mike.age ./declare-record.nix ./define-record-mike.nix
+# record optional field without definition
+checkConfigError "attribute 'age' in selection path 'config.people.alice.age' not found" config.people.alice.age ./declare-record-optional-field.nix ./define-record-alice.nix
+# record optional field with definition
+checkConfigOutput '^27$' config.people.mike.age ./declare-record-optional-field.nix ./define-record-mike.nix
+
+#TODO:
+# - test empty definitions
+# - test neseted records
+# - test nested optional records
+# - etc?
+
+
+if false; then
+
 # Shorthand meta attribute does not duplicate the config
 checkConfigOutput '^"one two"$' config.result ./shorthand-meta.nix
 
@@ -558,6 +595,8 @@ checkConfigOutput '^34|23$' options.submoduleLine34.declarationPositions.1.line
 # nested options work
 checkConfigOutput '^30$' options.nested.nestedLine30.declarationPositions.0.line ./declaration-positions.nix
 
+fi
+
 cat <<EOF
 ====== module tests ======
 $pass Pass

lib/tests/modules/declare-record-bad-default.nix

@@ -0,0 +1,20 @@
+{ lib, ... }:
+
+let
+  inherit (lib) mkOption types;
+
+  person = types.record {
+    fields = {
+      nixerSince = mkOption { type = types.int; };
+      name = mkOption { type = types.str; };
+      isCool = mkOption {
+        type = types.bool;
+        default = "yeah";
+      };
+    };
+  };
+
+in
+{
+  options.people = mkOption { type = types.attrsOf person; };
+}

lib/tests/modules/declare-record-optional-field.nix

@@ -0,0 +1,20 @@
+{ lib, ... }:
+
+let
+  inherit (lib) mkOption types;
+
+  person = types.record {
+    fields = {
+      nixerSince = mkOption { type = types.int; };
+      name = mkOption { type = types.str; };
+    };
+    optionalFields = {
+      age = mkOption { type = types.ints.unsigned; };
+    };
+    wildcard = mkOption { type = types.bool; };
+  };
+
+in
+{
+  options.people = mkOption { type = types.attrsOf person; };
+}

lib/tests/modules/declare-record-wildcard.nix

@@ -0,0 +1,17 @@
+{ lib, ... }:
+
+let
+  inherit (lib) mkOption types;
+
+  person = types.record {
+    fields = {
+      nixerSince = mkOption { type = types.int; };
+      name = mkOption { type = types.str; };
+    };
+    wildcard = mkOption { type = types.bool; };
+  };
+
+in
+{
+  options.people = mkOption { type = types.attrsOf person; };
+}

lib/tests/modules/declare-record.nix

@@ -0,0 +1,20 @@
+{ lib, ... }:
+
+let
+  inherit (lib) mkOption types;
+
+  person = types.record {
+    fields = {
+      nixerSince = mkOption { type = types.int; };
+      name = mkOption { type = types.str; };
+      isCool = mkOption {
+        type = types.bool;
+        default = true;
+      };
+    };
+  };
+
+in
+{
+  options.people = mkOption { type = types.attrsOf person; };
+}

lib/tests/modules/define-record-alice-prefs.nix

@@ -0,0 +1,10 @@
+{ lib, ... }:
+{
+  people.alice = {
+    nixerSince = 2016;
+    name = "Alice";
+    hiRes = true;
+    mechKeyboard = true;
+    spiders = false;
+  };
+}

lib/tests/modules/define-record-alice.nix

@@ -0,0 +1,6 @@
+{
+  people.alice = {
+    nixerSince = 2016;
+    name = "Alice";
+  };
+}

lib/tests/modules/define-record-bob.nix

@@ -0,0 +1,6 @@
+{
+  people.bob = {
+    nixerSince = 2019;
+    name = "Bob";
+  };
+}

lib/tests/modules/define-record-mallory.nix

@@ -0,0 +1,6 @@
+{
+  people.mallory = {
+    nixerSince = "beginning of time";
+    name = "Bobby";
+  };
+}

lib/tests/modules/define-record-mike.nix

@@ -0,0 +1,7 @@
+{
+  people.mike = {
+    nixerSince = 2020;
+    name = "Mike";
+    age = 27;
+  };
+}

lib/types.nix

@@ -1044,7 +1044,8 @@ rec {
     # Augment the given type with an additional type check function.
     addCheck = elemType: check: elemType // { check = x: elemType.check x && check x; };
 
-  };
+  }
+  // import ./types/record.nix { inherit lib; };
 };
 
 in outer_types // outer_types.types

lib/types/record.nix

@@ -0,0 +1,124 @@
+{ lib }:
+
+let
+  inherit (lib)
+    mapAttrs
+    zipAttrsWith
+    removeAttrs
+    attrNames
+    showOption
+    optional
+    mergeDefinitions
+    mkOptionType
+    isAttrs
+    ;
+
+  record =
+    {
+      fields ? { },
+      optionalFields ? { },
+      wildcard ? null,
+    }@args:
+    # TODO: assert that at least one arg is provided, i.e. args != { }
+    let
+      checkFields = mapAttrs (
+        name: value:
+        if value._type or null != "option" then
+          throw "Record field `${lib.escapeNixIdentifier name}` must be declared with `mkOption`."
+        else if value ? apply then
+          throw "In field ${lib.escapeNixIdentifier name} records do not support options with `apply`"
+        else if value ? readOnly then
+          throw "In field ${lib.escapeNixIdentifier name} records do not support options with `readOnly`"
+        else
+          value
+      );
+      fields' = checkFields fields;
+      # TODO: should we also check optionalFields have no default?
+      optionalFields' = checkFields optionalFields;
+      wildcard =
+        if args.wildcard or null == null then
+          null
+        else if args.wildcard._type or null != "option" then
+          throw "Record wildcard must be declared with `mkOption`."
+        else if args.wildcard ? apply then
+          throw "Records do not support options with `apply`, but wildcard has `apply`."
+        else
+          args.wildcard;
+    in
+    mkOptionType {
+      name = "record";
+      description = if wildcard == null then "record" else "open record of ${wildcard.description}";
+      descriptionClass = if wildcard == null then "noun" else "composite";
+      check = isAttrs;
+      merge =
+        loc: defs:
+        let
+          data = zipAttrsWith (name: values: values) (
+            map (
+              def:
+              mapAttrs (_fieldName: fieldValue: {
+                inherit (def) file;
+                value = fieldValue;
+              }) def.value
+            ) defs
+          );
+          requiredFieldValues = mapAttrs (
+            fieldName: fieldOption:
+            builtins.addErrorContext "while evaluating the field `${fieldName}' of option `${showOption loc}'" (
+              (mergeDefinitions (loc ++ [ fieldName ]) fieldOption.type (
+                data.${fieldName} or [ ]
+                # FIXME: isn't this handled by `mergeDefinitions` already?
+                ++ optional (fieldOption ? default) {
+                  value = fieldOption.default;
+                  file = "the default value of option ${showOption loc}";
+                }
+              )).mergedValue
+            )
+          ) fields';
+          optionalFieldValues = lib.concatMapAttrs (
+            fieldName: fieldOption:
+            builtins.addErrorContext
+              "while evaluating the optional field `${fieldName}' of option `${showOption loc}'"
+              (
+                let
+                  opt = mergeDefinitions (loc ++ [ fieldName ]) fieldOption.type (
+                    data.${fieldName} or [ ]
+                    # TODO: surely defaults make no sense for optional fields?
+                    # And doesn't mergeDefinitions do this internally, anyway?
+                    ++ optional (fieldOption ? default) {
+                      value = fieldOption.default;
+                      file = "the default value of option ${showOption loc}";
+                    }
+                  );
+                in
+                lib.optionalAttrs opt.isDefined { ${fieldName} = opt.mergedValue; }
+              )
+          ) optionalFields';
+          extraData = removeAttrs data (attrNames fields' ++ attrNames optionalFields');
+        in
+        if wildcard == null then
+          if extraData == { } then
+            requiredFieldValues
+          else
+            throw "A definition for option `${showOption loc}' has an unknown field."
+        else
+          requiredFieldValues
+          // optionalFieldValues
+          // mapAttrs (
+            fieldName: fieldDefs:
+            builtins.addErrorContext
+              "while evaluating the wildcard field `${fieldName}' of option `${showOption loc}'"
+              ((mergeDefinitions (loc ++ [ fieldName ]) wildcard.type fieldDefs).mergedValue)
+          ) extraData;
+      nestedTypes = fields' // {
+        # potential collision with `_wildcard` field
+        # TODO: should we prevent fields from having a wildcard?
+        _wildcard = wildcard;
+      };
+    };
+
+in
+# public
+{
+  inherit record;
+}

nixos/doc/manual/development/freeform-modules.section.md

@@ -1,5 +1,7 @@
 # Freeform modules {#sec-freeform-modules}
 
+<!-- TODO: Consider re-writing this doc to favor `types.record` over `types.submodule` -->
+
 Freeform modules allow you to define values for option paths that have
 not been declared explicitly. This can be used to add attribute-specific
 types to what would otherwise have to be `attrsOf` options in order to
@@ -12,6 +14,47 @@ into the resulting `config` set. Since this feature nullifies name
 checking for entire option trees, it is only recommended for use in
 submodules.
 
+<!-- TODO: Link to more details on the record and submodule types -->
+
+Wildcard records can also be used to achieve the same thing, and may be
+preferred in many scenarios due to their improved performance when
+compared to submodules and also the ability to declare "optional" fields.
+
+Wildcards records are used by simply passing `wildcard = types.anything`
+to a record type definition.
+
+::: {#ex-wildcard-record .example}
+### Wildcard record
+
+Most freeform submodules can also be represented as wildcard records.
+
+The following example is equivalent to the first submodule example:
+
+```nix
+{ lib, config, ... }: {
+
+  options.settings = lib.mkOption {
+    type = lib.types.record {
+
+      wildcard = lib.types.str;
+
+      # We want this attribute to be checked for the correct type
+      fields.port = lib.mkOption {
+        type = lib.types.port;
+        # Declaring the option also allows defining a default value
+        default = 8080;
+      };
+
+      # We could use an "optional" field, instead of supplying a default
+      optionalFields.port = lib.mkOption {
+        type = lib.types.port;
+      };
+
+    };
+  };
+}
+```
+
 ::: {#ex-freeform-module .example}
 ### Freeform submodule