🌲🌴 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]]) ];
}

As an special case, when the single argument given to an import-tree object is an attribute-set meaning it is NOT a path or list of paths, the import-tree object assumes it is being imported as a module. This way, a pre-configured import-tree can also be used directly in a list of module imports.

This is useful for authors exposing pre-configured import-trees that users can directly add to their import list or continue configuring themselves using the API.

let
  # imagine this configured tree is actually provided by some flake or library.
  # users can directly import it or continue using API methods on it.
  configured-tree = import-tree.addPath [./a [./b]]; # paths are configured by library author.
in {
  imports = [ configured-tree ]; # but then imported or further configured by the library user.
}

Configurable behavior#

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

lib.pipe import-tree [
  (i: i.mapWith lib.traceVal) # trace all paths. useful for debugging what is being imported.
  (i: i.filtered (lib.hasInfix ".mod.")) # filter nix files by some predicate
  (i: i ./modules) # finally, call the configured import-tree 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.addPath#

addPath can be used to prepend paths to be filtered as a setup for import-tree. This function can be applied multiple times.

# import-tree.addPath : (path_or_list_of_paths) -> import-tree

# Both of these result in the same imported files.
# however, the first adds ./vendor as a *pre-configured* path.
# and the final user can supply ./modules or [] empty.
(import-tree.addPath ./vendor) ./modules
import-tree [./vendor ./modules]

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

import-tree.result#

Exactly the same as calling the import-tree object with an empty list [ ]. This is useful for import-tree objects that already have paths configured via .addPath.

# import-tree.result : <module-or-piped-result>

# these two are exactly the same:
(import-tree.addPath ./modules).result
(import-tree.addPath ./modules) [ ]