lib.modules.doRename

The following is the current implementation of this function.

doRename = {
    # List of strings representing the attribute path of the old option.
    from,
    # List of strings representing the attribute path of the new option.
    to,
    # Boolean, whether the old option is to be included in documentation.
    visible,
    # Whether to warn when a value is defined for the old option.
    # NOTE: This requires the NixOS assertions module to be imported, so
    #        - this generally does not work in submodules
    #        - this may or may not work outside NixOS
    warn,
    # A function that is applied to the option value, to form the value
    # of the old `from` option.
    #
    # For example, the identity function can be passed, to return the option value unchanged.
    # ```nix
    # use = x: x;
    # ```
    #
    # To add a warning, you can pass the partially applied `warn` function.
    # ```nix
    # use = lib.warn "Obsolete option `${opt.old}' is used. Use `${opt.to}' instead.";
    # ```
    use,
    # Legacy option, enabled by default: whether to preserve the priority of definitions in `old`.
    withPriority ? true,
    # A boolean that defines the `mkIf` condition for `to`.
    # If the condition evaluates to `true`, and the `to` path points into an
    # `attrsOf (submodule ...)`, then `doRename` would cause an empty module to
    # be created, even if the `from` option is undefined.
    # By setting this to an expression that may return `false`, you can inhibit
    # this undesired behavior.
    #
    # Example:
    #
    # ```nix
    # { config, lib, ... }:
    # let
    #   inherit (lib) mkOption mkEnableOption types doRename;
    # in
    # {
    #   options = {
    #
    #     # Old service
    #     services.foo.enable = mkEnableOption "foo";
    #
    #     # New multi-instance service
    #     services.foos = mkOption {
    #       type = types.attrsOf (types.submodule …);
    #     };
    #   };
    #   imports = [
    #     (doRename {
    #       from = [ "services" "foo" "bar" ];
    #       to = [ "services" "foos" "" "bar" ];
    #       visible = true;
    #       warn = false;
    #       use = x: x;
    #       withPriority = true;
    #       # Only define services.foos."" if needed. (It's not just about `bar`)
    #       condition = config.services.foo.enable;
    #     })
    #   ];
    # }
    # ```
    condition ? true
  }:
    { config, options, ... }:
    let
      fromOpt = getAttrFromPath from options;
      toOf = attrByPath to
        (abort "Renaming error: option `${showOption to}' does not exist.");
      toType = let opt = attrByPath to {} options; in opt.type or (types.submodule {});
    in
    {
      options = setAttrByPath from (mkOption {
        inherit visible;
        description = "Alias of {option}`${showOption to}`.";
        apply = x: use (toOf config);
      } // optionalAttrs (toType != null) {
        type = toType;
      });
      config = mkIf condition (mkMerge [
        (optionalAttrs (options ? warnings) {
          warnings = optional (warn && fromOpt.isDefined)
            "The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";
        })
        (if withPriority
          then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt
          else mkAliasAndWrapDefinitions (setAttrByPath to) fromOpt)
      ]);
    };