`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 almost the same types as wlib.dag.topoSort.

Except it requires the DAG form.

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

`wlib.dag.pushDownDagNames`

Takes a DAG (set of sets) and adds the name field to the internal set if not already present and a string

`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.specBetween`

Adds before and after dependencies to a spec.

This is similar to entryBetween, but instead of constructing a new entry it augments an existing spec. Any existing before or after fields on the spec are preserved and extended.

Arguments:

before: [ string ] Additional nodes that the spec should appear before.
after: [ string ] Additional nodes that the spec should appear after.
spec: attrset The spec to modify.

Returns the spec with merged dependency fields.

`wlib.dag.specAfter`

Adds after dependencies to a spec.

Equivalent to:

specBetween [ ] after spec

Existing dependency fields on the spec are preserved and extended.

`wlib.dag.specBefore`

Adds before dependencies to a spec.

Equivalent to:

specBetween before [ ] spec

Existing dependency fields on the spec are preserved and extended.

`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.specsBetween`

Given a list of specs (attribute sets with stuff in them, and optional name, before, and after fields), places them sequentially within the DAG.

This is approximately the opposite of wlib.dag.dagToDal.

Each generated node receives a name of the form:

"${tag}-${index}"

If a spec already has a name field it will be used instead.

The specs are chained via their before and after fields so that their order in the list is preserved. The entire sequence can also be constrained relative to other DAG nodes using the before and after arguments.

Arguments:

tag: string Prefix used when generating names.
before: [ string ] Nodes that the first generated entry must appear before.
after: [ string ] Nodes that the first generated entry must appear after.
entries: [ attrset ] Specs to insert into the DAG.

Returns a DAG (attribute set) containing the generated entries.

`wlib.dag.entriesBetween`

defined as:

tag: before: after: entries:
wlib.dag.specsBetween tag before after (map (data: { inherit data; }) entries)

`wlib.dag.specsAnywhere`

Convenience wrapper around specsBetween that inserts a sequence of specs without adding any external ordering constraints.

The generated entries will still be chained relative to each other so that their order in the input list is preserved.

Equivalent to:

tag: specsBetween tag [ ] [ ]

Arguments:

tag: string Prefix used when generating names.

`wlib.dag.specsAfter`

Convenience wrapper around specsBetween that inserts a sequence of specs which must appear after the given nodes.

Equivalent to:

tag: after: specsBetween tag [ ] after

Arguments:

tag: string Prefix used when generating names.
after: [ string ] Nodes that the first generated entry must appear after.

`wlib.dag.specsBefore`

Convenience wrapper around specsBetween that inserts a sequence of specs which must appear before the given nodes.

Equivalent to:

tag: before: specsBetween tag before [ ]

Arguments:

tag: string Prefix used when generating names.
before: [ string ] Nodes that the first generated entry must appear before.

`wlib.dag.entriesAnywhere`

Convenience wrapper around entriesBetween that inserts a sequence of entries without adding any external ordering constraints.

Equivalent to:

tag: entries: entriesBetween tag [ ] [ ] entries

Arguments:

tag: string Prefix used when generating names.
entries: [ any ] Payload values that will be converted into DAG entries.

`wlib.dag.entriesAfter`

Convenience wrapper around entriesBetween that inserts a sequence of entries which must appear after the given nodes.

Equivalent to:

tag: after: entries: entriesBetween tag [ ] after entries

Arguments:

tag: string Prefix used when generating names.
after: [ string ] Nodes that the first generated entry must appear after.
entries: [ any ] Payload values that will be converted into DAG entries.

`wlib.dag.entriesBefore`

Convenience wrapper around entriesBetween that inserts a sequence of entries which must appear before the given nodes.

Equivalent to:

tag: before: entries: entriesBetween tag before [ ] entries

Arguments:

tag: string Prefix used when generating names.
before: [ string ] Nodes that the first generated entry must appear before.
entries: [ any ] Payload values that will be converted into DAG entries.

Keyboard shortcuts

nix-wrapper-modules