Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

lib/options: refactor and rename (non-breaking) #1661

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

lib/options: refactor and rename (non-breaking) #1661

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
94c4cee
lib/types: add `nixvimTypes.freeformModule`
MattSturgeon Jun 9, 2024
cad8e4f
lib/options: add `rawOpts` helpers
MattSturgeon Jun 9, 2024
5f6d76f
lib/options: move top-level helpers to `nullableOpts`
MattSturgeon Jun 9, 2024
9338e10
lib/options: standardise raw-type support in `defaultNullOpts`
MattSturgeon Jun 9, 2024
428d96d
lib/options: merge `mkNullOrStrLuaOr'` (etc)
MattSturgeon Jun 9, 2024
b6850ec
contributing: update `defaultNullOpts` docs
MattSturgeon Jun 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,8 @@ These option declarations should be in `settingsOptions` and their names should
There are a number of helpers to help you correctly implement them:

- `helpers.defaultNullOpts.{mkBool,mkInt,mkStr,...}`: This family of helpers takes a default value and a description, and sets the Nix default to `null`. These are the main functions you should use to define options.
- `helpers.defaultNullOpts.mkNullable`: This takes a type, a default and a description. This is useful for more complex options.
- `helpers.defaultNullOpts.mkNullableWithRaw`: This takes a type, a default and a description. This is useful for more complex options.
- The `helpers.defaultNullOpts` functions also have "prime variants", these use the same function arguments as `lib.mkOption`. Any unused arguments are passed through to `mkOption`; this is useful for setting an `example` or other advanced cases.
- `helpers.nixvimTypes.rawLua`: A type to represent raw lua code. The values are of the form `{ __raw = "<code>";}`. This should not be used if the option can only be raw lua code, `mkLua`/`mkLuaFn` should be used in this case.

The resulting `settings` attrs will be directly translated to `lua` and will be forwarded the plugin:
Expand Down
185 changes: 107 additions & 78 deletions lib/options.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,76 +6,100 @@
with lib;
with nixvimUtils;
rec {
# Creates an option with a nullable type that defaults to null.
mkNullOrOption' =
{
type,
default ? null,
...
}@args:
lib.mkOption (
args
// {
type = lib.types.nullOr type;
inherit default;
}
);
mkNullOrOption = type: description: mkNullOrOption' { inherit type description; };

# Make these available as top-level functions
# Mainly for backwards compatibility
mkNullOrOption' = nullableOpts.mkOption';
mkNullOrOption = nullableOpts.mkOption;
mkNullOrLua' = nullableOpts.mkLua';
mkNullOrLua = nullableOpts.mkLua;
mkNullOrLuaFn' = nullableOpts.mkLuaFn';
mkNullOrLuaFn = nullableOpts.mkLuaFn;
mkNullOrStrLuaOr = nullableOpts.mkStrLuaOr;
mkNullOrStrLuaFnOr = nullableOpts.mkStrLuaFnOr;

# TODO: should we deprecate this?
mkCompositeOption' =
{ options, ... }@args:
mkNullOrOption' (
nullableOpts.mkOption' (
(filterAttrs (n: _: n != "options") args) // { type = types.submodule { inherit options; }; }
);
mkCompositeOption = description: options: mkCompositeOption' { inherit description options; };

mkNullOrStr' = args: mkNullOrOption' (args // { type = with nixvimTypes; maybeRaw str; });
mkNullOrStr = description: mkNullOrStr' { inherit description; };

mkNullOrLua' =
args:
mkNullOrOption' (
args
// {
type = nixvimTypes.strLua;
apply = mkRaw;
}
);
mkNullOrLua = description: mkNullOrLua' { inherit description; };

mkNullOrLuaFn' =
args:
mkNullOrOption' (
args
// {
type = nixvimTypes.strLuaFn;
apply = mkRaw;
}
);
mkNullOrLuaFn = description: mkNullOrLua' { inherit description; };

mkNullOrStrLuaOr' =
{ type, ... }@args:
mkNullOrOption' (
args
// {
type = with nixvimTypes; either strLua type;
apply = v: if isString v then mkRaw v else v;
}
);
mkNullOrStrLuaOr = type: description: mkNullOrStrLuaOr' { inherit type description; };

mkNullOrStrLuaFnOr' =
{ type, ... }@args:
mkNullOrOption' (
args
// {
type = with nixvimTypes; either strLuaFn type;
apply = v: if isString v then mkRaw v else v;
}
);
mkNullOrStrLuaFnOr = type: description: mkNullOrStrLuaFnOr' { inherit type description; };

# TODO: Deprecate in favor of explicitly named functions
inherit (rawOpts) mkNullOrStr' mkNullOrStr;

# Functions to create nullable options
# Warning: does not add support for the raw type
nullableOpts = rec {
mkOption' =
{
type,
default ? null,
...
}@args:
lib.mkOption (
args
// {
type = types.nullOr type;
inherit default;
}
);
mkOption = type: description: nullableOpts.mkOption' { inherit type description; };

mkStr' = args: mkOption' (args // { type = types.str; });
mkStr = description: mkStr' { inherit description; };

mkLua' =
args:
mkOption' (
args
// {
type = nixvimTypes.strLua;
apply = mkRaw;
}
// (optionalAttrs (args ? type) {
type = with nixvimTypes; either strLua args.type;
apply = v: if isString v then mkRaw v else v;
})
);
mkLua = description: mkLua' { inherit description; };
mkStrLuaOr = type: description: mkLua' { inherit type description; };

mkLuaFn' =
args:
mkOption' (
args
// {
type = nixvimTypes.strLuaFn;
apply = mkRaw;
}
// (optionalAttrs (args ? type) {
type = with nixvimTypes; either strLuaFn args.type;
apply = v: if isString v then mkRaw v else v;
})
);
mkLuaFn = description: mkLua' { inherit description; };
mkStrLuaFnOr = type: description: mkLuaFn' { inherit type description; };
};

# Functions to create options that support the raw type
rawOpts = rec {
mkOption' = { type, ... }@args: lib.mkOption (args // { type = nixvimTypes.maybeRaw type; });
mkOption = type: description: mkOption' { inherit type description; };

mkListOf' =
{ type, ... }@args: mkOption (args // { type = with nixvimTypes; listOf (maybeRaw type); });
mkListOf = type: description: mkListOf' { inherit type description; };

mkAttrsOf' =
{ type, ... }@args: mkOption (args // { type = with nixvimTypes; attrsOf (maybeRaw type); });
mkAttrsOf = type: description: mkAttrsOf' { inherit type description; };

mkNullOrStr' = args: nullableOpts.mkOption' (args // { type = with nixvimTypes; maybeRaw str; });
mkNullOrStr = description: mkNullOrStr' { inherit description; };
};

# Functions to create options that default to null, also with a "plugin default"
defaultNullOpts =
let
# Convert `defaultNullOpts`-style arguments into normal `mkOption`-style arguments,
Expand Down Expand Up @@ -145,31 +169,34 @@ rec {
${defaultDesc}
'';

mkNullable' = args: mkNullOrOption' (convertArgs args);
mkNullable =
# TODO deprecate, then transition this alias to `mkNullableWithRaw`
mkNullable' = mkNullableNoRaw';
mkNullable = mkNullableNoRaw;
mkNullableNoRaw' = args: nullableOpts.mkOption' (convertArgs args);
mkNullableNoRaw =
type: default: description:
mkNullable' { inherit type default description; };
mkNullableNoRaw' { inherit type default description; };

mkNullableWithRaw' =
{ type, ... }@args: mkNullable' (args // { type = nixvimTypes.maybeRaw type; });
mkNullableWithRaw =
type: default: description:
mkNullableWithRaw' { inherit type default description; };

mkStrLuaOr' = args: mkNullOrStrLuaOr' (convertArgs args);
mkStrLuaOr' = args: nullableOpts.mkStrLuaOr' (convertArgs args);
mkStrLuaOr =
type: default: description:
mkStrLuaOr' { inherit type default description; };

mkStrLuaFnOr' = args: mkNullOrStrLuaFnOr' (convertArgs args);
mkStrLuaFnOr' = args: nullableOpts.mkStrLuaFnOr' (convertArgs args);
mkStrLuaFnOr =
type: default: description:
mkStrLuaFnOr' { inherit type default description; };

mkLua' = args: mkNullOrLua' (convertArgs args);
mkLua' = args: nullableOpts.mkLua' (convertArgs args);
mkLua = default: description: mkLua' { inherit default description; };

mkLuaFn' = args: mkNullOrLuaFn' (convertArgs args);
mkLuaFn' = args: nullableOpts.mkLuaFn' (convertArgs args);
mkLuaFn = default: description: mkLuaFn' { inherit default description; };

mkNum' = args: mkNullableWithRaw' (args // { type = types.number; });
Expand All @@ -196,17 +223,19 @@ rec {
);
mkStr = default: description: mkStr' { inherit default description; };

mkAttributeSet' = args: mkNullable' (args // { type = nixvimTypes.attrs; });
mkAttributeSet' = args: mkNullableWithRaw' (args // { type = nixvimTypes.attrs; });
mkAttributeSet = default: description: mkAttributeSet' { inherit default description; };

mkListOf' =
{ type, ... }@args: mkNullable' (args // { type = with nixvimTypes; listOf (maybeRaw type); });
{ type, ... }@args:
mkNullableWithRaw' (args // { type = with nixvimTypes; listOf (maybeRaw type); });
mkListOf =
type: default: description:
mkListOf' { inherit type default description; };

mkAttrsOf' =
{ type, ... }@args: mkNullable' (args // { type = with nixvimTypes; attrsOf (maybeRaw type); });
{ type, ... }@args:
mkNullableWithRaw' (args // { type = with nixvimTypes; attrsOf (maybeRaw type); });
mkAttrsOf =
type: default: description:
mkAttrsOf' { inherit type default description; };
Expand Down Expand Up @@ -259,7 +288,7 @@ rec {

mkSeverity' =
args:
mkNullOrOption' (
nullableOpts.mkOption' (
args
// {
type =
Expand All @@ -279,7 +308,7 @@ rec {

mkLogLevel' =
args:
mkNullOrOption' (
nullableOpts.mkOption' (
args
// {
type = with nixvimTypes; either ints.unsigned logLevel;
Expand All @@ -295,7 +324,7 @@ rec {
description ? "Highlight settings.",
...
}@args:
mkNullable' (
mkNullableWithRaw' (
args
// {
type = nixvimTypes.highlight;
Expand All @@ -320,7 +349,7 @@ rec {
assert args ? default;
# `name` must be present if `description` is missing
assert (!args ? description) -> args ? name;
mkNullOrOption' (
nullableOpts.mkOption' (
(filterAttrs (n: _: n != "name") args)
// {
type = types.package;
Expand Down
62 changes: 32 additions & 30 deletions lib/types.nix
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ rec {

maybeRaw = type: types.either type rawLua;

freeformModule =
options:
submodule {
inherit options;
freeformType = attrsOf anything;
};

border =
with types;
oneOf [
Expand All @@ -43,36 +50,31 @@ rec {
"trace"
];

highlight = types.submodule {
# Adds flexibility for other keys
freeformType = types.attrs;

# :help nvim_set_hl()
options = with types; {
fg = mkNullOrStr "Color for the foreground (color name or '#RRGGBB').";
bg = mkNullOrStr "Color for the background (color name or '#RRGGBB').";
sp = mkNullOrStr "Special color (color name or '#RRGGBB').";
blend = mkNullOrOption (numbers.between 0 100) "Integer between 0 and 100.";
bold = mkNullOrOption bool "";
standout = mkNullOrOption bool "";
underline = mkNullOrOption bool "";
undercurl = mkNullOrOption bool "";
underdouble = mkNullOrOption bool "";
underdotted = mkNullOrOption bool "";
underdashed = mkNullOrOption bool "";
strikethrough = mkNullOrOption bool "";
italic = mkNullOrOption bool "";
reverse = mkNullOrOption bool "";
nocombine = mkNullOrOption bool "";
link = mkNullOrStr "Name of another highlight group to link to.";
default = mkNullOrOption bool "Don't override existing definition.";
ctermfg = mkNullOrStr "Sets foreground of cterm color.";
ctermbg = mkNullOrStr "Sets background of cterm color.";
cterm = mkNullOrOption (either str attrs) ''
cterm attribute map, like |highlight-args|.
If not set, cterm attributes will match those from the attribute map documented above.
'';
};
# :help nvim_set_hl()
highlight = freeformModule {
fg = mkNullOrStr "Color for the foreground (color name or '#RRGGBB').";
bg = mkNullOrStr "Color for the background (color name or '#RRGGBB').";
sp = mkNullOrStr "Special color (color name or '#RRGGBB').";
blend = mkNullOrOption (numbers.between 0 100) "Integer between 0 and 100.";
bold = mkNullOrOption bool "";
standout = mkNullOrOption bool "";
underline = mkNullOrOption bool "";
undercurl = mkNullOrOption bool "";
underdouble = mkNullOrOption bool "";
underdotted = mkNullOrOption bool "";
underdashed = mkNullOrOption bool "";
strikethrough = mkNullOrOption bool "";
italic = mkNullOrOption bool "";
reverse = mkNullOrOption bool "";
nocombine = mkNullOrOption bool "";
link = mkNullOrStr "Name of another highlight group to link to.";
default = mkNullOrOption bool "Don't override existing definition.";
ctermfg = mkNullOrStr "Sets foreground of cterm color.";
ctermbg = mkNullOrStr "Sets background of cterm color.";
cterm = mkNullOrOption (either str attrs) ''
cterm attribute map, like |highlight-args|.
If not set, cterm attributes will match those from the attribute map documented above.
'';
};

strLua = strLikeType "lua code string";
Expand Down