🌲🌴 import-tree 🎄🌳#

{config, ...} {
  imports = [  (import-tree ./modules)  ];
}

Obtaining the API#

When used as a flake, the flake outputs attrset is the primary callable. Otherwise, importing the default.nix that is at the root of this repository will evaluate into the same attrset. This callable attrset is referred to as import-tree in this documentation.

import-tree#

Takes a single argument: path or deeply nested list of path. Returns a module that imports the discovered files. For example, given the following file tree:

default.nix
modules/
  a.nix
  subdir/
    b.nix

The following

{lib, config, ...} {
  imports = [ (import-tree ./modules) ];
}

Is similar to

{lib, config, ...} {
  imports = [
    {
      imports = [
        ./modules/a.nix
        ./modules/subdir/b.nix
      ];
    }
  ];
}

If given a deeply nested list of paths the list will be flattened and results concatenated. The following is valid usage:

{lib, config, ...} {
  imports = [ (import-tree [./a [./b]]) ];
}

Configurable behavior#

import-tree functions with custom behavior can be obtained using a builder pattern. For example:

lib.pipe import-tree [
  (i: i.mapWith lib.traceVal) # trace all paths
  (i: i.filtered (lib.hasInfix ".mod.")) # filter nix files by some predicate
  (i: i ./modules) # finally, call the configured callable with a path
]

Here is a simpler but less readable equivalent:

((import-tree.mapWith lib.traceVal).filtered (lib.hasInfix ".mod.")) ./modules

import-tree.filtered#

filtered takes a predicate function path -> bool. Only paths for which the filter returns true are selected:

[!NOTE] Only files with suffix .nix are candidates.

# import-tree.filtered : (path -> bool) -> import-tree

import-tree.filtered (lib.hasInfix ".mod.") ./some-dir

filtered can be applied multiple times, in which case only the files matching all filters will be selected:

lib.pipe import-tree [
  (i: i.filtered (lib.hasInfix ".mod."))
  (i: i.filtered (lib.hasSuffix "default.nix"))
  (i: i ./some-dir)
]

Or, in a simpler but less readable way:

(import-tree.filtered (lib.hasInfix ".mod.")).filtered (lib.hasSuffix "default.nix") ./some-dir

import-tree.matching#

matching takes a regular expression. The regex should match the full path for the path to be selected. Matching is done with builtins.match.

# import-tree.matching : regex -> import-tree

import-tree.matching ".*/[a-z]+@(foo|bar)\.nix" ./some-dir

matching can be applied multiple times, in which case only the paths matching all regex patterns will be selected, and can be combined with any number of filtered, in any order.

import-tree.mapWith#

mapWith can be used to transform each path by providing a function.

e.g. to convert the path into a module explicitly:

# import-tree.mapWith : (path -> any) -> import-tree

import-tree.mapWith (path: {
  imports = [ path ];
  # assuming such an option is declared
  automaticallyImportedPaths = [ path ];
})

mapWith can be applied multiple times, composing the transformations:

lib.pipe import-tree [
  (i: i.mapWith (lib.removeSuffix ".nix"))
  (i: i.mapWith builtins.stringLength)
] ./some-dir

The above example first removes the .nix suffix from all selected paths, then takes their lengths.

Or, in a simpler but less readable way:

((import-tree.mapWith (lib.removeSuffix ".nix")).mapWith builtins.stringLength) ./some-dir

mapWith can be combined with any number of filtered and matching calls, in any order, but the (composed) transformation is applied after the filters, and only to the paths that match all of them.

import-tree.withLib#

[!NOTE] withLib is required prior to invocation of any of .leafs or .pipeTo. Because with the use of those functions the implementation does not have access to a lib that is provided as a module argument.

# import-tree.withLib : lib -> import-tree

import-tree.withLib pkgs.lib

import-tree.pipeTo#

pipeTo takes a function that will receive the list of paths. When configured with this, import-tree will not return a nix module but the result of the function being piped to.

# import-tree.pipeTo : ([paths] -> any) -> import-tree

import-tree.pipeTo lib.id # equivalent to  `.leafs`

import-tree.leafs#

leafs takes no arguments, it is equivalent to calling import-tree.pipeTo lib.id. That is, instead of producing a nix module, just return the list of results.

# import-tree.leafs : import-tree

import-tree.leafs