Repository navigation
Expand file tree
/
Copy pathtypes.nix
More file actions
2702 lines (2454 loc) · 87.9 KB
/
Copy pathtypes.nix
File metadata and controls
2702 lines (2454 loc) · 87.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
Option types are a way to put constraints on the values a module option
can take. Types are also responsible of how values are merged in case of
multiple value definitions.
*/
{ lib }:
let
inherit (lib)
all
elem
flip
hasContext
functionArgs
isAttrs
isBool
isDerivation
isFloat
isFunction
isInt
isList
isPath
isStorePath
isString
substring
sort
toDerivation
toList
types
;
inherit (lib.lists)
concatLists
concatMap
elemAt
filter
foldl'
head
imap1
last
length
tail
;
inherit (lib.attrsets)
attrNames
filterAttrs
hasAttr
mapAttrs
optionalAttrs
zipAttrsWith
;
inherit (lib.options)
getFiles
getValues
mergeDefaultOption
mergeEqualOption
mergeOneOption
mergeUniqueOption
showFiles
showDefs
showOption
;
inherit (lib.strings)
concatMapStringsSep
concatStringsSep
escapeNixString
hasInfix
isStringLike
;
inherit (lib.trivial)
boolToString
;
inherit (lib.modules)
mergeDefinitions
fixupOptionType
mergeOptionDecls
defaultOrderPriority
defaultOverridePriority
mkDefinition
mkOrder
mkOverride
;
inherit (lib.fileset)
isFileset
unions
empty
;
inherit (lib.path) hasStorePathPrefix;
inAttrPosSuffix =
v: name:
let
pos = builtins.unsafeGetAttrPos name v;
in
if pos == null then "" else " at ${pos.file}:${toString pos.line}:${toString pos.column}";
hasColonInfix = hasInfix ":";
hasNewlineInfix = hasInfix "\n";
# Internal functor to help for migrating functor.wrapped to functor.payload.elemType
# Note that individual attributes can be overridden if needed.
elemTypeFunctor =
name:
{ elemType, ... }@payload:
{
inherit name payload;
type = types.${name};
binOp =
a: b:
let
merged = a.elemType.typeMerge b.elemType.functor;
in
if merged == null then null else { elemType = merged; };
};
checkDefsForError =
check: loc: defs:
if all (def: check def.value) defs then
null
else
let
invalidDefs = filter (def: !check def.value) defs;
in
{
message = "Definition values: ${showDefs invalidDefs}";
};
# Check that a type with v2 merge has a coherent check attribute.
# Throws an error if the type uses an ad-hoc `type // { check }` override.
# Returns the last argument like `seq`, allowing usage: checkV2MergeCoherence loc type expr
checkV2MergeCoherence =
loc: type: result:
if type.check.isV2MergeCoherent or false then
result
else
throw ''
The option `${showOption loc}' has a type `${type.description}' that uses
an ad-hoc `type // { check = ...; }' override, which is incompatible with
the v2 merge mechanism.
Please use `lib.types.addCheck` instead of `type // { check }' to add
custom validation. For example:
lib.types.addCheck baseType (value: /* your check */)
instead of:
baseType // { check = value: /* your check */; }
'';
in
rec {
isType = type: x: (x._type or "") == type;
setType =
typeName: value:
value
// {
_type = typeName;
};
# Default type merging function
# takes two type functors and return the merged type
defaultTypeMerge =
f: f':
let
mergedPayload = f.binOp f.payload f'.payload;
hasPayload =
assert (f'.payload != null) == (f.payload != null);
f.payload != null;
in
# Abort early: cannot merge different types
if f.name != f'.name then
null
else
if hasPayload then
if mergedPayload == null then null else f.type mergedPayload
else
f.type;
# Default type functor
defaultFunctor = name: {
inherit name;
type = lib.types.${name} or null;
payload = null;
binOp = a: b: null;
};
isOptionType = isType "option-type";
/**
Custom types can be created with the `mkOptionType` function. As type
creation includes some more complex topics such as submodule handling,
it is recommended to get familiar with `types.nix` code before creating
a new type.
The only required parameter is `name`.
`name`
: A string representation of the type function name.
`description`
: Description of the type used in documentation. Give information of
the type and any of its arguments.
`check`
: A function to type check the definition value. Takes the definition
value as a parameter and returns a boolean indicating the type check
result, `true` for success and `false` for failure.
`merge`
: A function to merge multiple definitions values. Takes two
parameters:
*`loc`*
: The option path as a list of strings, e.g. `["boot" "loader
"grub" "enable"]`.
*`defs`*
: The list of sets of defined `value` and `file` where the value
was defined, e.g. `[ {
file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 }
]`. The `merge` function should return the merged value
or throw an error in case the values are impossible or not meant
to be merged.
`getSubOptions`
: For composed types that can take a submodule as type parameter, this
function generate sub-options documentation. It takes the current
option prefix as a list and return the set of sub-options. Usually
defined in a recursive manner by adding a term to the prefix, e.g.
`prefix:
elemType.getSubOptions (prefix ++
["prefix"])` where *`"prefix"`* is the newly added prefix.
`getSubModules`
: For composed types that can take a submodule as type parameter, this
function should return the type parameters submodules. If the type
parameter is called `elemType`, the function should just recursively
look into submodules by returning `elemType.getSubModules;`.
`substSubModules`
: For composed types that can take a submodule as type parameter, this
function can be used to substitute the parameter of a submodule
type. It takes a module as parameter and return the type with the
submodule options substituted. It is usually defined as a type
function call with a recursive call to `substSubModules`, e.g for a
type `composedType` that take an `elemtype` type parameter, this
function should be defined as `m:
composedType (elemType.substSubModules m)`.
`typeMerge`
: A function to merge multiple type declarations. Takes the type to
merge `functor` as parameter. A `null` return value means that type
cannot be merged.
*`f`*
: The type to merge `functor`.
Note: There is a generic `defaultTypeMerge` that work with most of
value and composed types.
`functor`
: An attribute set representing the type. It is used for type
operations and has the following keys:
`type`
: The type function.
`wrapped`
: Holds the type parameter for composed types.
`payload`
: Holds the value parameter for value types. The types that have a
`payload` are the `enum`, `separatedString` and `submodule`
types.
`binOp`
: A binary operation that can merge the payloads of two same
types. Defined as a function that take two payloads as
parameters and return the payloads merged.
*/
mkOptionType =
{
# Human-readable representation of the type, should be equivalent to
# the type function name.
name,
# Description of the type, defined recursively by embedding the wrapped type if any.
description ? null,
# A hint for whether or not this description needs parentheses. Possible values:
# - "noun": a noun phrase
# Example description: "positive integer",
# - "conjunction": a phrase with a potentially ambiguous "or" connective
# Example description: "int or string"
# - "composite": a phrase with an "of" connective
# Example description: "list of string"
# - "nonRestrictiveClause": a noun followed by a comma and a clause
# Example description: "positive integer, meaning >0"
# See the `optionDescriptionPhrase` function.
descriptionClass ? null,
# DO NOT USE WITHOUT KNOWING WHAT YOU ARE DOING!
# Function applied to each definition that must return false when a definition
# does not match the type. It should not check more than the root of the value,
# because checking nested values reduces laziness, leading to unnecessary
# infinite recursions in the module system.
# Further checks of nested values should be performed by throwing in
# the merge function.
# Strict and deep type checking can be performed by calling lib.deepSeq on
# the merged value.
#
# See https://github.com/NixOS/nixpkgs/pull/6794 that introduced this change,
# https://github.com/NixOS/nixpkgs/pull/173568 and
# https://github.com/NixOS/nixpkgs/pull/168295 that attempted to revert this,
# https://github.com/NixOS/nixpkgs/issues/191124 and
# https://github.com/NixOS/nixos-search/issues/391 for what happens if you ignore
# this disclaimer.
check ? (x: true),
# Merge a list of definitions together into a single value.
# This function is called with two arguments: the location of
# the option in the configuration as a list of strings
# (e.g. ["boot" "loader "grub" "enable"]), and a list of
# definition values and locations (e.g. [ { file = "/foo.nix";
# value = 1; } { file = "/bar.nix"; value = 2 } ]).
merge ? mergeDefaultOption,
# Whether this type has a value representing nothingness. If it does,
# this should be a value of the form { value = <the nothing value>; }
# If it doesn't, this should be {}
# This may be used when a value is required for `mkIf false`. This allows the extra laziness in e.g. `lazyAttrsOf`.
emptyValue ? { },
# Return a flat attrset of sub-options. Used to generate
# documentation.
getSubOptions ? prefix: { },
# List of modules if any, or null if none.
getSubModules ? null,
# Function for building the same option type with a different list of
# modules.
substSubModules ? m: null,
# Function that merge type declarations.
# internal, takes a functor as argument and returns the merged type.
# returning null means the type is not mergeable
typeMerge ? defaultTypeMerge functor,
# The type functor.
# internal, representation of the type as an attribute set.
# name: name of the type
# type: type function.
# wrapped: the type wrapped in case of compound types.
# payload: values of the type, two payloads of the same type must be
# combinable with the binOp binary operation.
# binOp: binary operation that merge two payloads of the same type.
functor ? defaultFunctor name,
# The deprecation message to display when this type is used by an option
# If null, the type isn't deprecated
deprecationMessage ? null,
# The types that occur in the definition of this type. This is used to
# issue deprecation warnings recursively. Can also be used to reuse
# nested types
nestedTypes ? { },
}:
{
_type = "option-type";
inherit
name
check
merge
emptyValue
getSubOptions
getSubModules
substSubModules
typeMerge
deprecationMessage
nestedTypes
descriptionClass
functor
;
description = if description == null then name else description;
};
# optionDescriptionPhrase :: (str -> bool) -> optionType -> str
#
# Helper function for producing unambiguous but readable natural language
# descriptions of types.
#
# Parameters
#
# optionDescriptionPhase unparenthesize optionType
#
# `unparenthesize`: A function from descriptionClass string to boolean.
# It must return true when the class of phrase will fit unambiguously into
# the description of the caller.
#
# `optionType`: The option type to parenthesize or not.
# The option whose description we're returning.
#
# Returns value
#
# The description of the `optionType`, with parentheses if there may be an
# ambiguity.
optionDescriptionPhrase =
unparenthesize: t:
if unparenthesize (t.descriptionClass or null) then t.description else "(${t.description})";
noCheckForDocsModule = {
# When generating documentation, our goal isn't to check anything.
# Quite the opposite in fact. Generating docs is somewhat of a
# challenge, evaluating modules in a *lacking* context. Anything
# that makes the docs avoid an error is a win.
config._module.check = lib.mkForce false;
_file = "<built-in module that disables checks for the purpose of documentation generation>";
};
/**
A type which doesn't do any checking, merging or nested evaluation. It
accepts a single arbitrary value that is not recursed into, making it
useful for values coming from outside the module system, such as package
sets or arbitrary data. Options of this type are still evaluated according
to priorities and conditionals, so `mkForce`, `mkIf` and co. still work on
the option value itself, but not for any value nested within it. This type
should only be used when checking, merging and nested evaluation are not
desirable.
*/
raw = mkOptionType {
name = "raw";
description = "raw value";
descriptionClass = "noun";
check = value: true;
merge = mergeOneOption;
};
/**
A type that accepts any value and recursively merges attribute sets
together. This type is recommended when the option type is unknown.
::: {.example}
# `types.anything`
Two definitions of this type like
```nix
{
str = lib.mkDefault "foo";
pkg.hello = pkgs.hello;
fun.fun = x: x + 1;
}
```
```nix
{
str = lib.mkIf true "bar";
pkg.gcc = pkgs.gcc;
fun.fun = lib.mkForce (x: x + 2);
}
```
will get merged to
```nix
{
str = "bar";
pkg.gcc = pkgs.gcc;
pkg.hello = pkgs.hello;
fun.fun = x: x + 2;
}
```
:::
*/
anything = mkOptionType {
name = "anything";
description = "anything";
descriptionClass = "noun";
check = value: true;
merge =
loc: defs:
let
getType =
value: if isAttrs value && isStringLike value then "stringCoercibleSet" else builtins.typeOf value;
# Returns the common type of all definitions, throws an error if they
# don't have the same type
commonType = foldl' (
type: def:
if getType def.value == type then
type
else
throw "The option `${showOption loc}' has conflicting option types in ${showFiles (getFiles defs)}"
) (getType (head defs).value) defs;
mergeFunction =
{
# Recursively merge attribute sets
set = (attrsOf anything).merge;
# This is the type of packages, only accept a single definition
stringCoercibleSet = mergeOneOption;
lambda =
loc: defs: arg:
anything.merge (loc ++ [ "<function body>" ]) (
map (def: {
file = def.file;
value = def.value arg;
}) defs
);
# Otherwise fall back to only allowing all equal definitions
}
.${commonType} or mergeEqualOption;
in
mergeFunction loc defs;
};
unspecified = mkOptionType {
name = "unspecified";
description = "unspecified value";
descriptionClass = "noun";
};
/**
A boolean, its values can be `true` or `false`.
All definitions must have the same value, after priorities. An error is thrown in case of a conflict.
*/
bool = mkOptionType {
name = "bool";
description = "boolean";
descriptionClass = "noun";
check = isBool;
merge = mergeEqualOption;
};
/**
A boolean, its values can be `true` or `false`.
The result is `true` if _any_ of multiple definitions is `true`.
In other words, definitions are merged with the logical _OR_ operator.
*/
boolByOr = mkOptionType {
name = "boolByOr";
description = "boolean (merged using or)";
descriptionClass = "noun";
check = isBool;
merge =
loc: defs:
foldl' (
result: def:
# Under the assumption that .check always runs before merge, we can assume that all defs.*.value
# have been forced, and therefore we assume we don't introduce order-dependent strictness here
result || def.value
) false defs;
};
/**
A signed integer.
*/
int = mkOptionType {
name = "int";
description = "signed integer";
descriptionClass = "noun";
check = isInt;
merge = mergeEqualOption;
};
/**
`types.ints.{s8, s16, s32}`
: Signed integers with a fixed length (8, 16 or 32 bits). They go from
−2^n/2 to
2^n/2−1 respectively (e.g. `−128` to
`127` for 8 bits).
`types.ints.unsigned`
: An unsigned integer (that is >= 0).
`types.ints.{u8, u16, u32}`
: Unsigned integers with a fixed length (8, 16 or 32 bits). They go
from 0 to 2^n−1 respectively (e.g. `0`
to `255` for 8 bits).
`types.ints.between` *`lowest highest`*
: An integer between *`lowest`* and *`highest`* (both inclusive).
:::{.example}
# `lib.types.ints.between` usage example
```nix
(ints.between 0 100).check (-1)
=> false
(ints.between 0 100).check (101)
=> false
(ints.between 0 0).check 0
=> true
```
:::
`types.ints.positive`
: A positive integer (that is > 0).
*/
ints =
let
betweenDesc = lowest: highest: "${toString lowest} and ${toString highest} (both inclusive)";
between =
lowest: highest:
assert lowest <= highest || throw "ints.between: lowest must be smaller than highest";
addCheck int (x: x >= lowest && x <= highest)
// {
name = "intBetween";
description = "integer between ${betweenDesc lowest highest}";
};
ign =
lowest: highest: name: docStart:
between lowest highest
// {
inherit name;
description = docStart + "; between ${betweenDesc lowest highest}";
};
unsign =
bit: range: ign 0 (range - 1) "unsignedInt${toString bit}" "${toString bit} bit unsigned integer";
sign =
bit: range:
ign (0 - (range / 2)) (
range / 2 - 1
) "signedInt${toString bit}" "${toString bit} bit signed integer";
in
{
inherit between;
unsigned = addCheck lib.types.int (x: x >= 0) // {
name = "unsignedInt";
description = "unsigned integer, meaning >=0";
descriptionClass = "nonRestrictiveClause";
};
positive = addCheck lib.types.int (x: x > 0) // {
name = "positiveInt";
description = "positive integer, meaning >0";
descriptionClass = "nonRestrictiveClause";
};
u8 = unsign 8 256;
u16 = unsign 16 65536;
# the biggest int Nix accepts is 2^63 - 1 (9223372036854775807)
# the smallest int Nix accepts is -2^63 (-9223372036854775808)
u32 = unsign 32 4294967296;
# u64 = unsign 64 18446744073709551616;
s8 = sign 8 256;
s16 = sign 16 65536;
s32 = sign 32 4294967296;
};
/**
A port number. This type is an alias to
`types.ints.u16`.
*/
port = ints.u16;
/**
A floating point number.
::: {.warning}
Converting a floating point number to a string with `toString` or `toJSON`
may result in [precision loss](https://github.com/NixOS/nix/issues/5733).
:::
*/
float = mkOptionType {
name = "float";
description = "floating point number";
descriptionClass = "noun";
check = isFloat;
merge = mergeEqualOption;
};
/**
Either a signed integer or a floating point number. No implicit conversion
is done between the two types, and multiple equal definitions will only be
merged if they have the same type.
*/
number = either int float;
/**
`types.numbers.between` *`lowest highest`*
: An integer or floating point number between *`lowest`* and *`highest`* (both inclusive).
`types.numbers.nonnegative`
: A nonnegative integer or floating point number (that is >= 0).
`types.numbers.positive`
: A positive integer or floating point number (that is > 0).
*/
numbers =
let
betweenDesc =
lowest: highest: "${builtins.toJSON lowest} and ${builtins.toJSON highest} (both inclusive)";
in
{
between =
lowest: highest:
assert lowest <= highest || throw "numbers.between: lowest must be smaller than highest";
addCheck number (x: x >= lowest && x <= highest)
// {
name = "numberBetween";
description = "integer or floating point number between ${betweenDesc lowest highest}";
};
nonnegative = addCheck number (x: x >= 0) // {
name = "numberNonnegative";
description = "nonnegative integer or floating point number, meaning >=0";
descriptionClass = "nonRestrictiveClause";
};
positive = addCheck number (x: x > 0) // {
name = "numberPositive";
description = "positive integer or floating point number, meaning >0";
descriptionClass = "nonRestrictiveClause";
};
};
/**
A string. Multiple definitions cannot be merged.
*/
str = mkOptionType {
name = "str";
description = "string";
descriptionClass = "noun";
check = isString;
merge = mergeEqualOption;
};
nonEmptyStr = mkOptionType {
name = "nonEmptyStr";
description = "non-empty string";
descriptionClass = "noun";
check = x: str.check x && builtins.match "[ \t\n]*" x == null;
inherit (str) merge;
};
# Allow a newline character at the end and trim it in the merge function.
singleLineStr =
let
inherit (strMatching "[^\n\r]*\n?") check merge;
removeNewlineSuffix = lib.removeSuffix "\n";
in
mkOptionType {
name = "singleLineStr";
description = "(optionally newline-terminated) single-line string";
descriptionClass = "noun";
inherit check;
merge = loc: defs: removeNewlineSuffix (merge loc defs);
};
/**
A string matching a specific regular expression. Multiple
definitions cannot be merged. The regular expression is processed
using `builtins.match`.
*/
strMatching =
pattern:
mkOptionType {
name = "strMatching ${escapeNixString pattern}";
description = "string matching the pattern ${pattern}";
descriptionClass = "noun";
check = x: str.check x && builtins.match pattern x != null;
inherit (str) merge;
functor = defaultFunctor "strMatching" // {
type = payload: strMatching payload.pattern;
payload = { inherit pattern; };
binOp = lhs: rhs: if lhs == rhs then lhs else null;
};
};
/**
`types.separatedString` *`sep`*
A string. Multiple definitions are concatenated with *`sep`*, e.g.
`types.separatedString "|"`.
*/
separatedString =
sep:
mkOptionType rec {
name = "separatedString";
description = "strings concatenated with ${builtins.toJSON sep}";
descriptionClass = "noun";
check = isString;
merge = loc: defs: concatStringsSep sep (getValues defs);
functor = (defaultFunctor name) // {
payload = { inherit sep; };
type = payload: lib.types.separatedString payload.sep;
binOp = lhs: rhs: if lhs.sep == rhs.sep then { inherit (lhs) sep; } else null;
};
};
/**
A string. Multiple definitions are concatenated with a new line
`"\n"`.
*/
lines = separatedString "\n";
/**
A string. Multiple definitions are concatenated with a comma `","`.
*/
commas = separatedString ",";
/**
A string. Multiple definitions are concatenated with a colon `":"`.
*/
envVar = separatedString ":";
passwdEntry =
entryType:
addCheck entryType (str: !(hasColonInfix str || hasNewlineInfix str))
// {
name = "passwdEntry ${entryType.name}";
description = "${
optionDescriptionPhrase (class: class == "noun") entryType
}, not containing newlines or colons";
descriptionClass = "nonRestrictiveClause";
};
/**
A free-form attribute set.
::: {.warning}
This type will be deprecated in the future because it doesn't
recurse into attribute sets, silently drops earlier attribute
definitions, and doesn't discharge `lib.mkDefault`, `lib.mkIf`
and co. For allowing arbitrary attribute sets, prefer
`types.attrsOf types.anything` instead which doesn't have these
problems.
:::
*/
attrs = mkOptionType {
name = "attrs";
description = "attribute set";
check = isAttrs;
merge = loc: foldl' (res: def: res // def.value) { };
emptyValue = {
value = { };
};
};
fileset = mkOptionType {
name = "fileset";
description = "fileset";
descriptionClass = "noun";
check = isFileset;
merge = loc: defs: unions (getValues defs);
emptyValue.value = empty;
};
# A package is a top-level store path (/nix/store/hash-name). This includes:
# - derivations
# - more generally, attribute sets with an `outPath` or `__toString` attribute
# pointing to a store path, e.g. flake inputs
# - strings with context, e.g. "${pkgs.foo}" or (toString pkgs.foo)
# - hardcoded store path literals (/nix/store/hash-foo) or strings without context
# ("/nix/store/hash-foo"). These get a context added to them using builtins.storePath.
# If you don't need a *top-level* store path, consider using pathInStore instead.
/**
A top-level store path. This can be an attribute set pointing
to a store path, like a derivation or a flake input.
*/
package = mkOptionType {
name = "package";
descriptionClass = "noun";
check = x: isDerivation x || isStorePath x;
merge =
loc: defs:
let
res = mergeOneOption loc defs;
in
if isPath res || (isString res && !hasContext res) then toDerivation res else res;
};
shellPackage = package // {
check = x: isDerivation x && hasAttr "shellPath" x;
};
/**
A type for the top level Nixpkgs package set.
*/
pkgs = addCheck (
unique { message = "A Nixpkgs pkgs set can not be merged with another pkgs set."; } attrs
// {
name = "pkgs";
descriptionClass = "noun";
description = "Nixpkgs package set";
}
) (x: (x._type or null) == "pkgs");
/**
A filesystem path that starts with a slash. Even if derivations can be
considered as paths, the more specific `types.package` should be preferred.
*/
path = pathWith {
absolute = true;
};
/**
A path that is contained in the Nix store. This can be a top-level store
path like `pkgs.hello` or a descendant like `"${pkgs.hello}/bin/hello"`,
(or, more simply, `lib.getExe pkgs.hello`).
*/
pathInStore = pathWith {
inStore = true;
};
/**
A path that is not contained in the Nix store. Typical use cases are:
secrets, password or any other external file.
::: {.warning}
This type only validates that the path is not *currently* in the Nix store.
It does NOT prevent the value from being copied to the store later when:
- Referenced in a derivation
- Used in certain path operations (e.g., `${path}` interpolation)
- Passed to functions that copy to the store
Users must still be careful about how they reference these paths.
:::
*/
externalPath = pathWith {
absolute = true;
inStore = false;
};
/**
`types.pathWith` { *`inStore`* ? `null`, *`absolute`* ? `null` }
A filesystem path. Either a string or something that can be coerced
to a string.
**Parameters**
`inStore` (`Boolean` or `null`, default `null`)
: Whether the path must be in the store (`true`), must not be in the store
(`false`), or it doesn't matter (`null`)
`absolute` (`Boolean` or `null`, default `null`)
: Whether the path must be absolute (`true`), must not be absolute
(`false`), or it doesn't matter (`null`)
**Behavior**
- `pathWith { inStore = true; }` is equivalent to `pathInStore`
- `pathWith { absolute = true; }` is equivalent to `path`
- `pathWith { inStore = false; absolute = true; }` requires an absolute
path that is not in the store. Useful for password files that shouldn't be
leaked into the store.
*/
pathWith =
{
inStore ? null,
absolute ? null,
}:
if inStore != null && absolute != null && inStore && !absolute then
throw "In pathWith, inStore means the path must be absolute"
else
mkOptionType {
name = "path";
description = (
(if absolute == null then "" else (if absolute then "absolute " else "relative "))
+ "path"
+ (
if inStore == null then "" else (if inStore then " in the Nix store" else " not in the Nix store")
)
);
descriptionClass = "noun";
merge = mergeEqualOption;
functor = defaultFunctor "path" // {
type = pathWith;
payload = { inherit inStore absolute; };
binOp = lhs: rhs: if lhs == rhs then lhs else null;
};
check =
x:
let
isInStore = hasStorePathPrefix (
if isPath x then
x
# Discarding string context is necessary to convert the value to