From 0feea2dbd2eb76ffa1ba1db7d291bcb1a274d529 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Sun, 28 Jan 2024 16:23:21 +0100 Subject: [PATCH] doc/option-types: Write about sum and union types --- .../development/option-types.section.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index 1dfb4354f887..e656a1002f5a 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -42,6 +42,9 @@ merging is handled. : One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`. Multiple definitions cannot be merged. + If you want to pair these values with more information, possibly of + distinct types, consider using a [sum type](#sec-option-types-sums). + `types.anything` : A type that accepts any value and recursively merges attribute sets @@ -279,6 +282,24 @@ Submodules are detailed in [Submodule](#section-option-types-submodule). more convenient and discoverable than expecting the module user to type-merge with the `attrsOf submodule` option. +## Union types {#sec-option-types-unions} + +A union of types is a type such that a value is valid when it is valid for at least one of those types. + +If some values are instances of more than one of the types, it is not possible to distinguish which type they are meant to be instances of. If that's needed, consider using a [sum type](#sec-option-types-sums). + + + +## Sum types {#sec-option-types-sums} + +A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with a type, through some value syntax. +Nix does not have a built-in syntax for this pairing of a label and a type or value, so sum types may be represented in multiple ways. + +If the built-in Nix value types provide enough distinction, you simplify your syntax with a [union type](#sec-option-types-unions) instead. + + + + ## Composed types {#sec-option-types-composed} Composed types are types that take a type as parameter. `listOf