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

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.

wlib.dag.dagWith

dagOf allows extra values beyond just after before data and name to be present.

dagWith accepts an attrset as its first parameter BEFORE elemType. You may include { strict = true; } to make it refuse to recognize sets with extra values.

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

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.

wlib.dag.dalWith

dalOf allows extra values beyond just after before data and name to be present.

dalWith accepts an attrset as its first parameter BEFORE elemType. You may include { strict = true; } to make it refuse to recognize sets with extra values.

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

wlib.dag.isDal

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

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.

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.

wlib.dag.lmap

Applies a function to each element of the given DAL.

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,
}