arrayUtilities: init

ci/OWNERS

@@ -56,6 +56,7 @@
 /pkgs/build-support/cc-wrapper                   @Ericson2314
 /pkgs/build-support/bintools-wrapper             @Ericson2314
 /pkgs/build-support/setup-hooks                  @Ericson2314
+/pkgs/build-support/setup-hooks/arrayUtilities   @ConnorBaker
 /pkgs/build-support/setup-hooks/auto-patchelf.sh @layus
 /pkgs/by-name/au/auto-patchelf                   @layus
 

pkgs/build-support/setup-hooks/arrayUtilities/getSortedMapKeys/getSortedMapKeys.bash

@@ -0,0 +1,45 @@
+# shellcheck shell=bash
+
+# getSortedMapKeys
+# Stores the sorted keys of the input associative array referenced by inputMapRef in the indexed arrray referenced by
+# outputArrRef.
+#
+# Note from the Bash manual on arrays:
+#   There is no maximum limit on the size of an array, nor any requirement that members be indexed or assigned contiguously.
+#   - https://www.gnu.org/software/bash/manual/html_node/Arrays.html
+#
+# Since no guarantees are made about the order in which associative maps are traversed, this function is primarly
+# useful for getting rid of yet another source of non-determinism. As an added benefit, it checks that the arguments
+# provided are of correct type, unlike native parameter expansion which will accept expansions of strings.
+#
+# Arguments:
+# - inputMapRef: a reference to an associative array (not mutated)
+# - outputArrRef: a reference to an indexed array (contents are replaced entirely)
+#
+# Returns 0.
+getSortedMapKeys() {
+  if (($# != 2)); then
+    nixErrorLog "expected two arguments!"
+    nixErrorLog "usage: getSortedMapKeys inputMapRef outputArrRef"
+    exit 1
+  fi
+
+  local -rn inputMapRef="$1"
+  # shellcheck disable=SC2178
+  # Don't warn about outputArrRef being used as an array because it is an array.
+  local -rn outputArrRef="$2"
+
+  if ! isDeclaredMap "${!inputMapRef}"; then
+    nixErrorLog "first argument inputMapRef must be a reference to an associative array"
+    exit 1
+  elif ! isDeclaredArray "${!outputArrRef}"; then
+    nixErrorLog "second argument outputArrRef must be a reference to an indexed array"
+    exit 1
+  fi
+
+  # shellcheck disable=SC2034
+  local -a keys=("${!inputMapRef[@]}")
+  sortArray keys "${!outputArrRef}"
+
+  return 0
+}

pkgs/build-support/setup-hooks/arrayUtilities/getSortedMapKeys/package.nix

@@ -0,0 +1,17 @@
+{
+  callPackages,
+  isDeclaredArray,
+  isDeclaredMap,
+  makeSetupHook,
+  sortArray,
+}:
+makeSetupHook {
+  name = "getSortedMapKeys";
+  propagatedBuildInputs = [
+    isDeclaredArray
+    isDeclaredMap
+    sortArray
+  ];
+  passthru.tests = callPackages ./tests.nix { };
+  meta.description = "Gets the sorted indices of an associative array";
+} ./getSortedMapKeys.bash

pkgs/build-support/setup-hooks/arrayUtilities/getSortedMapKeys/tests.nix

@@ -0,0 +1,80 @@
+# NOTE: Tests related to getSortedMapKeys go here.
+{
+  getSortedMapKeys,
+  lib,
+  testers,
+}:
+let
+  inherit (lib.attrsets) recurseIntoAttrs;
+  inherit (testers) shellcheck shfmt testEqualArrayOrMap;
+
+  check =
+    {
+      name,
+      valuesMap,
+      expectedArray,
+    }:
+    (testEqualArrayOrMap {
+      inherit name valuesMap expectedArray;
+      script = ''
+        set -eu
+        nixLog "running getSortedMapKeys with valuesMap to populate actualArray"
+        getSortedMapKeys valuesMap actualArray
+      '';
+    }).overrideAttrs
+      (prevAttrs: {
+        nativeBuildInputs = prevAttrs.nativeBuildInputs or [ ] ++ [ getSortedMapKeys ];
+      });
+in
+recurseIntoAttrs {
+  shellcheck = shellcheck {
+    name = "getSortedMapKeys";
+    src = ./getSortedMapKeys.bash;
+  };
+
+  shfmt = shfmt {
+    name = "getSortedMapKeys";
+    src = ./getSortedMapKeys.bash;
+  };
+
+  empty = check {
+    name = "empty";
+    valuesMap = { };
+    expectedArray = [ ];
+  };
+
+  singleton = check {
+    name = "singleton";
+    valuesMap = {
+      "apple" = "fruit";
+    };
+    expectedArray = [ "apple" ];
+  };
+
+  keysAreSorted = check {
+    name = "keysAreSorted";
+    valuesMap = {
+      "apple" = "fruit";
+      "bee" = "insect";
+      "carrot" = "vegetable";
+    };
+    expectedArray = [
+      "apple"
+      "bee"
+      "carrot"
+    ];
+  };
+
+  # NOTE: While keys can be whitespace, they cannot be null (empty).
+  keysCanBeWhitespace = check {
+    name = "keysCanBeWhitespace";
+    valuesMap = {
+      " " = 1;
+      "  " = 2;
+    };
+    expectedArray = [
+      " "
+      "  "
+    ];
+  };
+}

pkgs/build-support/setup-hooks/arrayUtilities/isDeclaredArray/isDeclaredArray.bash

@@ -0,0 +1,14 @@
+# shellcheck shell=bash
+
+# isDeclaredArray
+# Tests if inputArrayRef refers to a declared, indexed array.
+#
+# Arguments:
+# - inputArrayRef: a reference to an indexed array (not mutated)
+#
+# Returns 0 if the indexed array is declared, 1 otherwise.
+isDeclaredArray() {
+  # NOTE: We must dereference the name ref to get the type of the underlying variable.
+  # shellcheck disable=SC2034
+  local -nr inputArrayRef="$1" && [[ ${!inputArrayRef@a} =~ a ]]
+}

pkgs/build-support/setup-hooks/arrayUtilities/isDeclaredArray/package.nix

@@ -0,0 +1,9 @@
+{
+  callPackages,
+  makeSetupHook,
+}:
+makeSetupHook {
+  name = "isDeclaredArray";
+  passthru.tests = callPackages ./tests.nix { };
+  meta.description = "Tests if an array is declared";
+} ./isDeclaredArray.bash