wlib.dag set documentation

wlib.dag.dagOf

A directed acyclic graph of some inner type.

Arguments:

• elemType: type

Accepts an attrset of elements

The elements should be of type elemType or sets of the type { data, name ? null, before ? [], after ? [] } where the data field is of type elemType

name defaults to the key in the set.

Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap

Note, if the element type is a submodule then the name argument will always be set to the string "data" since it picks up the internal structure of the DAG values. To give access to the "actual" attribute name a new submodule argument is provided with the name dagName.

The config.optionname value from the associated option will be normalized such that all items are DAG entries

If you wish to alter the type, you may provide different options to wlib.dag.dagWith by updating this type wlib.dag.dagOf // { strict = false; }

wlib.dag.dagWith

Arguments:

• settings:

  • strict ? true: false adds freeformType = wlib.types.attrsRecursive and adjusts the conversion logic to accomodate. See Notes section below.
  • defaultNameFn ? ({ config, name, isDal, ... }@moduleArgs: if isDal then null else name): Function to compute the default name for entries. Recieves the submodule arguments.
  • dataTypeFn ? (elemType: { config, name, isDal, ... }@moduleArgs: elemType): Can be used if the type of the data field needs to depend upon the submodule arguments.
  • dontConvertFunctions ? false: true allows passing function-type submodules as dag entries. If your data field's type may contain a function, or is a submodule type itself, this should be left as false.
  • ...other arguments for lib.types.submoduleWith (modules, specialArgs, etc...) Passed through to configure submodules in the DAG entries.

• elemType: type The type of the DAG entries’ data field. You can provide the type, OR an entry for each item. In the resulting config.optionname value, all items are normalized into entries.

Notes:

• dagWith accepts an attrset as its first parameter (the settings) before elemType.
• Setting strict = false allows entries to have unchecked extra attributes beyond data, name, before, and after. If your item is a set, and might have a data field, you will want to keep strict = true to avoid false positives.
• To add extra type-checked fields, use the modules attribute, which is passed through to submoduleWith. The allowed dag fields will be automatically generated from the base set of modules passed.
• The config.optionname value from the associated option will be normalized so that all items become valid DAG entries.
• If elemType is a submodule, and dataTypeFn is not provided, a dagName argument will automatically be injected to access the actual attribute name.

wlib.dag.dalOf

A DAG LIST or (DAL) or dependency list of some inner type

Arguments:

• elemType: type

Accepts a LIST of elements

The elements should be of type elemType or sets of the type { data, name ? null, before ? [], after ? [] } where the data field is of type elemType

If a name is not given, it cannot be targeted by other values.

Can be used in conjunction with wlib.dag.topoSort and wlib.dag.sortAndUnwrap

Note, if the element type is a submodule then the name argument will always be set to the string "data" since it picks up the internal structure of the DAG values. To give access to the "actual" attribute name a new submodule argument is provided with the name dagName.

The config.optionname value from the associated option will be normalized such that all items are DAG entries

If you wish to alter the type, you may provide different options to wlib.dag.dalWith by updating this type wlib.dag.dalOf // { strict = false; }

wlib.dag.dalWith

Arguments:

• settings:

  • strict ? true: false adds freeformType = wlib.types.attrsRecursive and adjusts the conversion logic to accomodate. See Notes section below.
  • defaultNameFn ? ({ config, name, isDal, ... }@moduleArgs: if isDal then null else name): Function to compute the default name for entries. Recieves the submodule arguments.
  • dataTypeFn ? (elemType: { config, name, isDal, ... }@moduleArgs: elemType): Can be used if the type of the data field needs to depend upon the submodule arguments.
  • dontConvertFunctions ? false: true allows passing function-type submodules as dag entries. If your data field's type may contain a function, or is a submodule type itself, this should be left as false.
  • ...other arguments for lib.types.submoduleWith (modules, specialArgs, etc...) Passed through to configure submodules in the DAG entries.

• elemType: type The type of the DAL entries’ data field. You can provide the type, OR an entry for each item. In the resulting config.optionname value, all items are normalized into entries.

Notes:

• dalWith accepts an attrset as its first parameter (the settings) before elemType.
• Setting strict = false allows entries to have UNCHECKED extra attributes beyond data, name, before, and after. If your item is a set, and might have a data field, you will want to keep strict = true to avoid false positives.
• To add extra type-checked fields, use the modules attribute, which is passed through to submoduleWith. The allowed dag fields will be automatically generated from the base set of modules passed.
• The config.optionname value from the associated option will be normalized so that all items become valid DAG entries.
• If elemType is a submodule, and dataTypeFn is not provided, a dagName argument will automatically be injected to access the actual attribute name.

wlib.dag.isEntry

Determines whether a value is a valid DAG entry (allows extra values)

wlib.dag.isDag

determines whether a value is of the attrset type and all values are dag entries

Allows entries to have extra values

wlib.dag.isDal

determines whether a value is of the list type and all values are dag entries

Allows entries to have extra values

wlib.dag.topoSort

Takes an attribute set containing entries built by entryAnywhere, entryAfter, and entryBefore to a topologically sorted list of entries.

Alternatively, it can take a dal (dependency list) instead. Which is a list of such entries.

Requires values to all be DAG entries (in other words, have a value.data field)

Internally this function uses the topoSort function in <nixpkgs/lib/lists.nix> and its value is accordingly.

Specifically, the result on success is

   { result = [ { name = ?; data = ?; } … ] }

For example

   nix-repl> topoSort {
               a = entryAnywhere "1";
               b = entryAfter [ "a" "c" ] "2";
               c = entryBefore [ "d" ] "3";
               d = entryBefore [ "e" ] "4";
               e = entryAnywhere "5";
             } == {
               result = [
                 { data = "1"; name = "a"; }
                 { data = "3"; name = "c"; }
                 { data = "2"; name = "b"; }
                 { data = "4"; name = "d"; }
                 { data = "5"; name = "e"; }
               ];
             }
   true

And the result on error is

   {
     cycle = [ { after = ?; name = ?; data = ? } … ];
     loops = [ { after = ?; name = ?; data = ? } … ];
   }

For example

   nix-repl> topoSort {
               a = entryAnywhere "1";
               b = entryAfter [ "a" "c" ] "2";
               c = entryAfter [ "d" ] "3";
               d = entryAfter [ "b" ] "4";
               e = entryAnywhere "5";
             } == {
               cycle = [
                 { after = [ "a" "c" ]; data = "2"; name = "b"; }
                 { after = [ "d" ]; data = "3"; name = "c"; }
                 { after = [ "b" ]; data = "4"; name = "d"; }
               ];
               loops = [
                 { after = [ "a" "c" ]; data = "2"; name = "b"; }
               ];
             }
   true

dag

: Function argument

wlib.dag.gmap

Applies a function to each element of the given DAG.

Requires values to all be DAG entries (in other words, have a value.data field)

wlib.dag.mapDagToDal

wlib.dag.gmap but returns the result as a DAL

Requires values to all be DAG entries (in other words, have a value.data field)

wlib.dag.dagToDal

converts a DAG to a DAL

Requires values to all be DAG entries (in other words, have a value.data field)

wlib.dag.lmap

Applies a function to each element of the given DAL.

Requires values to all be DAG entries (in other words, have a value.data field)

wlib.dag.entryBetween

Creates a DAG entry with specified before and after dependencies.

wlib.dag.entryAnywhere

Create a DAG entry with no particular dependency information.

wlib.dag.entryAfter

Convenience function to create a DAG entry that should come after certain nodes.

wlib.dag.entryBefore

Convenience function to create a DAG entry that should come before certain nodes.

wlib.dag.entriesBetween

Given a list of entries, this function places them in order within the DAG. Each entry is labeled "${tag}-${entry index}" and other DAG entries can be added with 'before' or 'after' referring these indexed entries.

The entries as a whole can be given a relation to other DAG nodes. All generated nodes are then placed before or after those dependencies.

wlib.dag.entriesAnywhere

Convenience function for creating multiple entries without specific dependencies.

wlib.dag.entriesAfter

Convenience function for creating multiple entries that must be after another entry

wlib.dag.entriesBefore

Convenience function for creating multiple entries that must be before another entry

wlib.dag.sortAndUnwrap

Convenience function for resolving a DAG or DAL and getting the result in a sorted list of DAG entries

Unless you make use of mapIfOk, the result is still a DAL, but sorted.

Arguments:

{
  name ? "DAG", # for error message
  dag,
  mapIfOk ? null,
}

Requires values to all be DAG entries (in other words, have a value.data field)