wlib.dag set documentation

wlib.dag.dagWith

Arguments:

• settings:

  • 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.
  • …other arguments for wlib.types.specWith (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.
• To add extra type-checked fields, use the modules attribute, which is passed through to wlib.types.specWith. 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 or spec, a parentName argument will automatically be injected to access the actual attribute name.

wlib.dag.dalWith

Arguments:

• settings:

  • 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.
  • …other arguments for wlib.types.specWith (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.
• To add extra type-checked fields, use the modules attribute, which is passed through to wlib.types.specWith. 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 or spec, a parentName argument will automatically be injected to access the actual attribute name.

wlib.dag.mkDagEntry

Arguments:

{
  dataOptFn, # <- receives the submodule arguments. Returns a set for `lib.mkOption` (`internal = true` will be added unless you set it otherwise)
  defaultNameFn ? { name, isDal, ... }@moduleArgs: if isDal then null else name,
  isDal ? false, # <- added to `config._module.args`
}:

dataOptFn receives config, options, name, and isDal. Returns a set for lib.mkOption

Creates a module with a name, data, before, and after field, which can be passed to wlib.types.specWith or wlib.types.spec, to create a spec type which can be used with all the wlib.dag functions.

wlib.dag.dagNameModule

If, when constructing your own DAG type with mkDagEntry, your data field accepts submodules, you should also supply this module to specWith in order to set config.data._module.args.dagName.

You would do this because the name argument of that submodule will receive the field it was in, not the one from the parent attrsOf type.

If you use dagWith or dalWith, this is done for you for submodule and spec.

wlib.dag.topoSort

Takes an attribute set or list containing attrsets with (optional) name, before and after fields.

It then sorts them into a topologically sorted list of entries.

It does not perform any normalization of the entries themselves.

Internally this function uses the toposort function in <nixpkgs/lib/lists.nix> and it returns the same thing.

It returns an object which is like a “result”

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"; after = [ ]; before = [ ]; }
                { data = "3"; name = "c"; after = [ ]; before = [ "d" ]; }
                { data = "2"; name = "b"; after = [ "a" "c" ]; before = [ ]; }
                { data = "4"; name = "d"; after = [ ]; before = [ "e" ]; }
                { data = "5"; name = "e"; after = [ ]; before = [ ]; }
              ];
             }
   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 = [
                { data = "2"; name = "b"; after = [ "a" "c" ]; before = [ ]; }
                { data = "3"; name = "c"; after = [ "d" ]; before = [ ]; }
                { data = "4"; name = "d"; after = [ "b" ]; before = [ ]; }
              ];
              loops = [
                { data = "2"; name = "b"; after = [ "a" "c" ]; before = [ ]; }
              ];
            }
   true

dag

Function argument

wlib.dag.unwrapSort

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

wlib.dag.unwrapSort "name_for_error" { a = { before = [ "b" ]; }; b = { data = 1; }; }

The result is a sorted DAL, the result field from calling wlib.dag.topoSort

Accepts the same types in its dag argument as wlib.dag.topoSort.

But it returns the resulting list directly, and throws an error message if there is a cycle

wlib.dag.sortAndUnwrap

Same as unwrapSort but its argument is a set and it optionally accepts a function to map over the result

Arguments:

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

wlib.dag.dagToDal

converts a DAG to a DAL

Accepts the same types as wlib.dag.topoSort.

It is the normalization function used by topoSort when the argument is not a list prior to sorting the list.

wlib.dag.isEntry

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

Will return true if the item meets the following criteria:

Has a data field. If it has a name field that field is a string. If it has a before or after field that field is a list of strings.

It allows entries to have extra values not mentioned above.

wlib.dag.isDag

determines whether a value is of the attrset type and all values meet the criteria of wlib.dag.isEntry

Allows entries to have extra values

wlib.dag.isDal

determines whether a value is of the list type and all values meet the criteria of wlib.dag.isEntry

wlib.dag.lmap

Applies a function to each element of the given DAL.

Requires values to meet the criteria of wlib.dag.isEntry

wlib.dag.gmap

Applies a function to each element of the given DAG.

Requires values to meet the criteria of wlib.dag.isEntry

wlib.dag.mapDagToDal

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

Requires values to meet the criteria of wlib.dag.isEntry

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