nixos-config/subprojects/bahaghari/lib/trivial.nix

{ pkgs, lib, self }:

rec {
  inherit (pkgs.lib.generators) toYAML;

  /**
    Read YAML files into a Nix expression similar to lib.importJSON and
    lib.importTOML from nixpkgs standard library. Unlike both of them, this
    unfortunately relies on an import-from-derivation (IFD) so it isn't exactly
    perfect but it is very close.

    This relies on yaml2json which uses the following YAML library which you
    can view the following link for more details on YAML compatibility.

    https://pkg.go.dev/gopkg.in/yaml.v3#readme-compatibility

    # Arguments

    file
    : The filepath of the YAML file.

    # Type

    ```
    importYAML :: Path -> any
    ```

    # Example

    ```
    importYAML ./simple.yml
    =>
    {
      hello = "there";
      how-are-you-doing = "I'm fine. Thank you for asking.";
    }
    ```
  */
  importYAML = path:
    let
      dataDrv = pkgs.runCommand "convert-yaml-to-json" { } ''
        ${lib.getExe' pkgs.yaml2json "yaml2json"} < "${path}" > "$out"
      '';
    in
    lib.importJSON dataDrv;

  /**
    Convert a given decimal number to a specified base digit with the set of
    glyphs for each digit as returned from lib.toBaseDigits.

    # Arguments

    base
    : The base index.

    glyphs
    : An attribute set of decimal values and their glyphs.

    i
    : The actual integer to be converted.

    # Type

    ```
    toBaseDigitWithGlyphs :: Int -> Int -> Attrs -> String
    ```

    # Example

    ```
    toBaseDigitWithGlyphs 24 267 {
       "0" = "0";
       "1" = "1";
       "2" = "2";
       # ...
       "22" = "M";
       "23" = "N";
     }
    =>
    "12H"

    toBaseDigitWithGlyphs 
    ```
  */
  toBaseDigitsWithGlyphs = base: glyphs: i:
    let
      baseDigits = lib.toBaseDigits base i;
      toBaseDigits = d: glyphs.${builtins.toString d};
    in
    lib.concatMapStrings toBaseDigits baseDigits;

  /**
    Generates a glyph set usable for `toBaseDigitsWithGlyphs`. Take note the
    given list is assumed to be sorted and the generated glyph set starts at
    `0` up to (`listLength - 1`).

    # Arguments

    glyphsList
    : A sorted list of glyphs.

    # Type

    ```
    generateGlyphSet :: [ String ] -> Attrs
    ```

    # Example

    ```
    generateGlyphSet [ "0" "1" "2" "3" "4" "5" "6" "7" "8 "9" "A" "B" "C" "D" "E" "F" ]
    =>
    {
      "0" = "0";
      "1" = "1";
      # ...
      "14" = "E";
      "15" = "F";
    }
    ```
  */
  generateGlyphSet = glyphsList:
    let
      glyphsList' =
        lib.lists.imap0
          (i: glyph: lib.nameValuePair (builtins.toString i) glyph)
          glyphsList;
    in
    lib.listToAttrs glyphsList';

  /**
    Generates a conversion table for a sorted list of glyphs to its decimal
    number. Suitable for creating your own conversion function. Accepts the
    same argument as `generateGlyphSet`.

    # Arguments

    glyphsList
    : A sorted list of glyphs.

    # Type

    ```
    generateConversionTable :: [ String ] -> Attrs
    ```

    # Example

    ```
    generateConversionTable [ "0" "1" "2" "3" "4" "5" "6" "7" "8 "9" "A" "B" "C" "D" "E" "F" ]
    =>
    {
      "0" = 0;
      "1" = 1;
      # ...
      "E" = 14;
      "F" = 15;
    }
    ```
  */
  generateConversionTable = glyphsList:
    let
      glyphsList' =
        lib.lists.imap0
          (i: glyph: lib.nameValuePair glyph i)
          glyphsList;
    in
    lib.listToAttrs glyphsList';

  /**
    A factory function for generating an attribute set containing a glyph
    set, a conversion table, and a conversion function to and from decimal.
    Accepts the same list as `generateGlyphSet` and
    `generateConversionTable` where it assumes it is sorted and
    zero-indexed.

    # Arguments

    glyphsList
    : A sorted list of glyphs.

    # Type

    ```
    generateBaseDigitType :: [ String ] -> Attrs
    ```

    # Example

    ```
    generateBaseDigitType [ "0" "1" ]
    =>
    {
      base = 2;
      glyphSet = { "0" = "0"; "1" = "1"; };
      conversionTable = { "0" = 0; "1" = 1; };
      fromDec = <function>;
      toDec = <function>;
    }
    ```
  */
  generateBaseDigitType = glyphsList: rec {
    base = lib.length glyphsList;
    glyphSet = generateGlyphSet glyphsList;
    conversionTable = generateConversionTable glyphsList;

    # Unfortunately, these functions cannot handle negative numbers unless we
    # implement something like Two's complement. For now, we're not worrying
    # about that since most of the use cases here will be mostly for color
    # generation that typically uses hexadecimal (RGB). Plus I don't want to
    # open a can of worms about implementing this with stringy types.
    fromDec = decimal:
      let
        digits = lib.toBaseDigits base decimal;
      in
      lib.concatMapStrings (d: glyphSet.${builtins.toString d}) digits;

    toDec = digit:
      let
        chars = lib.stringToCharacters digit;
        maxDigits = (lib.length chars) - 1;
        convertDigitToDec =
          lib.lists.imap0 (i: v: conversionTable.${v} * (self.math.pow base (maxDigits - i))) chars;
      in
      lib.foldl (sum: v: sum + v) 0 convertDigitToDec;
  };

  /**
    Given a range of two numbers, ensure the value is only returned within the
    range.

    # Arguments

    min
    : Minimum number of the range.

    max
    : Maximum number of the range.

    value
    : Number to be used for the function.

    # Type

    ```
    clamp :: Number -> Number -> Number -> Number
    ```

    # Example

    ```
    clamp 0 255 654
    =>
    255

    clamp (-100) 100 (-234)
    =>
    -100

    clamp (-100) 100 54
    =>
    54
    ```
  */
  clamp = min: max: value:
    lib.min max (lib.max min value);

  /**
    Given a value, check if it's a number type.

    # Arguments

    value
    : Numerical value.

    # Type

    ```
    isNumber :: Number -> bool
    ```

    # Example:

    ```
    isNumber 3.0
    =>
    true

    isNumber 653
    =>
    true

    isNumber true
    =>
    false
    ```
  */
  isNumber = v:
    lib.isInt v || lib.isFloat v;

  /**
    Given a Nix number, force it to be a floating value.

    # Arguments

    value
    : The numerical value.

    # Type

    ```
    toFloat :: Number -> Float
    ```

    # Example

    ```
    toFloat 5
    =>
    5.0

    toFloat 59.0
    =>
    59.0
    ```
  */
  toFloat = x:
    1.0 * x;

  /**
    Given an initial range of integers, scale the given number with its own
    set of range.

    # Arguments

    rangeSet
    : An attribute set containing the following attributes: `inMin` and `inMax`
    for specifying the input's expected range and `outMin` and `outMax` for the
    output's.

    value
    : The numerical value.

    # Type

    ```
    scale :: Attrs -> Number -> Number
    ```

    # Example

    ```
    scale { inMin = 0; inMax = 15; outMin = 0; outMax = 255; } 4
    =>
    68

    scale { inMin = 0; inMax = 15; outMin = 0; outMax = 255; } (-4)
    =>
    -68

    scale { inMin = 0; inMax = 15; outMin = 0; outMax = 255; } 15
    =>
    255
    ```
  */
  scale = { inMin, inMax, outMin, outMax }: v:
    ((v - inMin) * (outMax - outMin)) / ((inMax - inMin) + outMin);

  /**
    Returns a null value if the condition fails. Otherwise, returns the given
    value `as`.

    # Arguments

    cond
    : Condition that should evaluate as a boolean.

    as
    : Value to be returned if condition returns true.

    # Type

    ```
    optionalNull :: Bool -> Any -> Any
    ```

    # Example

    ```
    optionalNull true "HELLO"
    => "HELLO"

    optionalNull (null != null) "HELLO"
    => null
    ```
  */
  optionalNull = cond: as:
    if cond then
      as
    else
      null;
}