Introduce types.orderOf

lib/tests/modules.sh

@@ -233,6 +233,22 @@ checkConfigError 'infinite recursion encountered' config.foo ./freeform-attrsOf.
 checkConfigError 'The option .* is used but not defined' config.foo ./freeform-lazyAttrsOf.nix ./freeform-unstr-dep-str.nix
 checkConfigOutput 24 config.foo ./freeform-lazyAttrsOf.nix ./freeform-unstr-dep-str.nix ./define-value-string.nix
 
+## orderOf
+# Check whether two elements with after/before are ordered correctly
+checkConfigOutput e config.value.0.data ./order/single-option.nix ./order/orderable.nix
+checkConfigOutput d config.value.1.data ./order/single-option.nix ./order/orderable.nix
+checkConfigOutput c config.value.2.data ./order/single-option.nix ./order/orderable.nix
+checkConfigOutput b config.value.3.data ./order/single-option.nix ./order/orderable.nix
+checkConfigOutput a config.value.4.data ./order/single-option.nix ./order/orderable.nix
+# Check that a cycle throws an error
+checkConfigError 'Cycle detected when trying to order option .*: a -> e -> d -> b -> a' config.value ./order/single-option.nix ./order/cycle.nix
+# Check that multiple orderOf declarations can be merged
+checkConfigOutput e config.value.0.data ./order/multiple-options.nix ./order/orderable.nix
+checkConfigOutput d config.value.1.data ./order/multiple-options.nix ./order/orderable.nix
+checkConfigOutput c config.value.2.data ./order/multiple-options.nix ./order/orderable.nix
+checkConfigOutput b config.value.3.data ./order/multiple-options.nix ./order/orderable.nix
+checkConfigOutput a config.value.4.data ./order/multiple-options.nix ./order/orderable.nix
+
 cat <<EOF
 ====== module tests ======
 $pass Pass

lib/tests/modules/order/cycle.nix

@@ -0,0 +1,5 @@
+{
+  imports = [ ./orderable.nix ];
+
+  value.a.before.e = true;
+}

lib/tests/modules/order/multiple-options.nix

@@ -0,0 +1,42 @@
+{ lib, ... }: {
+  imports = [
+    {
+      options.value = lib.mkOption {
+        type = lib.types.orderOf {
+          elemType = lib.types.submodule ({ name, ... }: {
+            options.data = lib.mkOption {
+              type = lib.types.str;
+              default = name;
+            };
+          });
+        };
+      };
+    }
+    {
+      options.value = lib.mkOption {
+        type = lib.types.orderOf {
+          before = a: b: a.value.before.${b.name} or false;
+          elemType = lib.types.submodule {
+            options.before = lib.mkOption {
+              type = lib.types.attrsOf lib.types.bool;
+              default = {};
+            };
+          };
+        };
+      };
+    }
+    {
+      options.value = lib.mkOption {
+        type = lib.types.orderOf {
+          before = a: b: b.value.after.${a.name} or false;
+          elemType = lib.types.submodule {
+            options.after = lib.mkOption {
+              type = lib.types.attrsOf lib.types.bool;
+              default = {};
+            };
+          };
+        };
+      };
+    }
+  ];
+}

lib/tests/modules/order/orderable.nix

@@ -0,0 +1,23 @@
+{
+
+  config.value = {
+    e = {
+      before.c = true;
+      before.a = true;
+    };
+    d = {
+      after.e = true;
+    };
+    c = {
+      after.e = true;
+      before.b = true;
+    };
+    b = {
+      after.d = true;
+      before.a = true;
+    };
+    a = {
+      after.d = true;
+    };
+  };
+}

lib/tests/modules/order/single-option.nix

@@ -0,0 +1,22 @@
+{ lib, ... }:
+{
+  options.value = lib.mkOption {
+    type = lib.types.orderOf {
+      before = a: b: a.value.before.${b.name} or false || b.value.after.${a.name} or false;
+      elemType = lib.types.submodule ({ name, ... }: {
+        options.data = lib.mkOption {
+          type = lib.types.str;
+          default = name;
+        };
+        options.after = lib.mkOption {
+          type = lib.types.attrsOf lib.types.bool;
+          default = {};
+        };
+        options.before = lib.mkOption {
+          type = lib.types.attrsOf lib.types.bool;
+          default = {};
+        };
+      });
+    };
+  };
+}

lib/types.nix

@@ -302,6 +302,35 @@ rec {
       functor = (defaultFunctor name) // { wrapped = elemType; };
     };
 
+
+    orderOf = {
+      before ? a: b: false,
+      elemType
+    }: mkOptionType rec {
+      name = "orderOf";
+      description = "ordered entries of ${elemType.description}s";
+      check = elemType.check;
+      merge = loc: defs:
+        let
+          nodeAttributes = (attrsOf elemType).merge loc defs;
+          entries = mapAttrsToList nameValuePair nodeAttributes;
+          sortedEntries = toposort before entries;
+          cycleError =
+            let showCycle = cycle: concatMapStringsSep " -> " (x: x.name) (reverseList (cycle ++ [ (head cycle) ]));
+            in throw "Cycle detected when trying to order option `${showOption loc}': ${showCycle sortedEntries.cycle}";
+        in if sortedEntries ? result then map (v: v.value) sortedEntries.result else cycleError;
+      getSubOptions = elemType.getSubOptions;
+      getSubModules = elemType.getSubModules;
+      substSubModules = m: orderOf { inherit before; elemType = elemType.substSubModules m; };
+      functor = defaultFunctor name // {
+        payload = { inherit before elemType; };
+        binOp = lhs: rhs: {
+          before = a: b: lhs.before a b || rhs.before a b;
+          elemType = lhs.elemType.typeMerge rhs.elemType.functor;
+        };
+      };
+    };
+
     # A version of attrsOf that's lazy in its values at the expense of
     # conditional definitions not working properly. E.g. defining a value with
     # `foo.attr = mkIf false 10`, then `foo ? attr == true`, whereas with

nixos/doc/manual/development/option-types.xml

@@ -360,6 +360,106 @@
      </para>
     </listitem>
    </varlistentry>
+   <varlistentry>
+    <term>
+     <varname>types.orderOf</varname> {
+      <replaceable>before</replaceable> ? a: b: false,
+      <replaceable>elemType</replaceable> }
+    </term>
+    <listitem>
+     <para>
+      A set of elements of type <replaceable>elemType</replaceable>, ordered
+      according to the given partial ordering function <replaceable>before
+      </replaceable>, equivalent to a
+      <link xlink:href="https://en.wikipedia.org/wiki/Directed_acyclic_graph">
+      DAG (directed acyclic graph)</link>. This type takes an attribute set
+      with the following attributes as a parameter:
+      <itemizedlist>
+       <listitem><para>
+        <replaceable>elemType</replaceable>
+        The type of elements. The <literal>orderOf</literal> type accepts
+        the same values as <literal>attrsOf elemType</literal> accepts.
+       </para></listitem>
+       <listitem><para> <replaceable>before</replaceable>
+        The partial ordering function. It takes two parameters, each an
+        attribute set of the form
+        <variablelist>
+         <varlistentry>
+          <term><varname>name</varname></term>
+          <listitem>
+           <para>
+            The attribute name of the entry.
+           </para>
+          </listitem>
+         </varlistentry>
+         <varlistentry>
+          <term><varname>value</varname></term>
+          <listitem>
+           <para>
+            The attribute value of the entry. This is of type <replaceable>elemType</replaceable>.
+           </para>
+          </listitem>
+         </varlistentry>
+        </variablelist>
+        This function should return <literal>true</literal> if the first parameter should be ordered <emphasis>before</emphasis> the second one.
+       </para></listitem>
+      </itemizedlist>
+      The result of this type is a list of <replaceable>elemType</replaceable>
+      items, ordered according to the <replaceable>before</replaceable> function.
+      If there are multiple possible orderings an arbitrary one of them is chosen.
+     </para>
+     <example xml:id="ex-orderOf"><title><literal>orderOf</literal> Example</title><para>
+      Here is a simple example of using this type to order a list of text
+      entries by allowing them to specify which entries they should come
+      before of.
+<programlisting>
+{ lib, ... }:
+{
+  options.value = lib.mkOption {
+    type = lib.types.orderOf {
+      # a should come before b if the value of a specifies { before.&lt;b&gt; = true; }
+      before = a: b: a.value.before.${b.name} or false;
+      elemType = lib.types.submodule {
+        options.text = lib.mkOption {
+          type = lib.types.str;
+        };
+        options.before = lib.mkOption {
+          type = lib.types.attrsOf lib.types.bool;
+          default = {};
+        };
+      };
+    };
+  };
+
+  config.value = {
+    foo = {
+      text = "This is foo";
+      before.bar = true;
+    };
+    bar = {
+      text = "This is bar";
+    };
+  };
+}
+</programlisting>
+      This option will evaluate to
+<programlisting>
+[
+  {
+    text = "This is foo";
+    before = {
+      bar = true;
+    };
+  }
+  {
+    text = "This is bar";
+    before = { };
+  }
+]
+</programlisting>
+     </para></example>
+    </listitem>
+   </varlistentry>
    <varlistentry>
     <term>
      <varname>types.lazyAttrsOf</varname> <replaceable>t</replaceable>