Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

wlib.types set documentation

wlib.types.subWrapperModuleWith

Like lib.types.submoduleWith but for wrapper modules!

Use this when you want any module (nixos and home manager included) to be able to accept other programs along with custom configurations.

The resulting config.optionname value will contain .config from the evaluated wrapper module, just like lib.types.submoduleWith

In other words, it will contain the same thing calling .apply returns.

This means you may grab the wrapped package from config.optionname.wrapper

It takes all the same arguments as lib.types.submoduleWith

wlib.types.subWrapperModuleWith = {
  modules ? [],
  specialArgs ? {},
  shorthandOnlyDefinesConfig ? false,
  description ? null,
  class ? null
}:

In fact, it IS a submodule.

This function simply adds wlib.core to the list of modules you pass, and both wlib and modulesPath (from wlib.modulesPath) to the specialArgs argument you pass.

To perform type-merging with this type, use lib.types.submodule or lib.types.submoduleWith

wlib.types.subWrapperModule

wlib.types.subWrapperModule = module: wlib.types.subWrapperModuleWith { modules = lib.toList module; };

i.e.

  options.myopts.xplr = lib.mkOption {
    type = wlib.types.subWrapperModule wlib.wrapperModules.xplr;
  };
  # and access config.myopts.xplr.wrapped and set settings and options within it.

wlib.types.specWith

Modified submoduleWith type for making options which are either an item, or a set with the item in it.

It will auto-normalize the values into the set form on merge, so you can avoid custom normalization logic when using the config value associated with the option.

The dag and dal types are made using this type.

wlib.types.specWith =
  {
    modules,
    specialArgs ? { },
    class ? null,
    description ? null,
    mainField ? null,
    dontConvertFunctions ? false,
  }:
  • modules, specialArgs, class, description are the same as for submoduleWith.
  • mainField ? null You may specify your main field with this option.
    • If you don’t, it will detect this value based on the option you do not give a default value to in your base modules.
    • You may only have 1 option without a default.
      • Any nested options will be assumed to have defaults.
      • If you have more than 1, and do not set mainField, it will error, and if you do set it, conversion will fail. In that case a submodule type would be a better match.
  • dontConvertFunctions ? false: true allows passing function-type submodules as specs. If your data field’s type may contain a function, or is a submodule type itself, this should be left as false.
  • Setting freeformType allows entries to have unchecked extra attributes. If your item is a set, and might contain your main field, you will want to avoid this to avoid false positives.

wlib.types.spec

wlib.types.spec = module: wlib.types.specWith { modules = lib.toList module; };

wlib.types.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, wlib.dag.sortAndUnwrap, and wlib.dag.unwrapSort

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.

The config.optionname value from the associated option will be normalized such that all items are DAG entries

If you wish to alter the type, you may provide different options to wlib.dag.dalWith by updating this type wlib.types.dalOf // { strict = false; }

You can further modify the type with type merging! Redefine the option with the type lib.types.listOf (wlib.types.spec ({ your module here }))

wlib.types.dagOf

A directed acyclic graph (attrset) 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, wlib.dag.sortAndUnwrap, and wlib.dag.unwrapSort

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.

The config.optionname value from the associated option will be normalized such that all items are DAG entries

If you wish to alter the type, you may provide different options to wlib.dag.dagWith by updating this type wlib.types.dagOf // { strict = false; }

You can further modify the type with type merging! Redefine the option with the type lib.types.attrsOf (wlib.types.spec ({ your module here }))

wlib.types.seriesOf

This type functions like the lib.types.listOf type, but has reversed order across imports. The individual lists assigned are unaffected.

This means, when you import a module, and it sets config.optionwiththistype, it will append to the importing module’s definitions rather than prepending to them.

This type is sometimes very useful when you want multiple .wrap, .apply, .eval, and .extendModules calls in series to apply to this option in a particular way.

This is because in that case with lib.types.listOf, each successive call will place its new items BEFORE the last call.

In some cases, where the first item will win, e.g. lndir this makes sense, or is inconsequential.

In others, (for example, with the config.overrides field from the core module) you really want them to run in series. So you can use seriesOf!

wlib.types.dalWithEsc

same as dalOf except with an extra field esc-fn

esc-fn is to be null, or a function that returns a string

used by wlib.modules.makeWrapper

wlib.types.dagWithEsc

same as dagOf except with an extra field esc-fn

esc-fn is to be null, or a function that returns a string

used by wlib.modules.makeWrapper

wlib.types.withPackagesType

The kind of type you would provide to pkgs.lua.withPackages or pkgs.python3.withPackages

This type is a function from a set of packages to a list of packages.

If you set it in multiple files, it will merge the resulting lists according to normal module rules for a listOf package.

wlib.types.stringable

Type for a value that can be converted to string "${like_this}"

used by wlib.modules.makeWrapper

wlib.types.nonEmptyLine

A single-line, non-empty string

wlib.types.fixedList

Arguments:

  • length: int,
  • elemType: type

It’s a list, but it rejects lists of the wrong length.

Still has regular list merge across multiple definitions, best used inside another list

wlib.types.wrapperFlags

Arguments:

  • length: int,

len: wlib.types.dalOf (wlib.types.fixedList len wlib.types.stringable)

wlib.types.wrapperFlag

DAL (list) of (stringable or list of stringable)

More flexible than wlib.types.wrapperFlags, allows single items, or lists of items of varied length

wlib.types.file

File type with content and path options

Arguments:

  • pkgs: nixpkgs instance

Fields:

  • content: File contents as string
  • path: Derived path using pkgs.writeText

wlib.types.attrsRecursive

Like lib.types.anything, but allows contained lists to also be merged