packages feed

autodocodec-nix 0.1.1.0 → 0.2.0.0

raw patch · 5 files changed

+568/−155 lines, 5 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

- Autodocodec.Nix: optionsExpr :: Map Text Option -> Expression
- Autodocodec.Nix: optionsExpression :: Map Text Option -> Expression
- Autodocodec.Nix: renderNixOptionsVia :: ObjectCodec input output -> Text
- Autodocodec.Nix: renderNixOptionsViaCodec :: HasObjectCodec a => Text
- Autodocodec.Nix.Options: optionsExpr :: Map Text Option -> Expression
- Autodocodec.Nix.Options: optionsExpression :: Map Text Option -> Expression
- Autodocodec.Nix.Options: renderNixOptionsVia :: ObjectCodec input output -> Text
- Autodocodec.Nix.Options: renderNixOptionsViaCodec :: HasObjectCodec a => Text
+ Autodocodec.Nix: ExprIf :: !Expression -> !Expression -> !Expression -> Expression
+ Autodocodec.Nix: ExprLam :: !Text -> !Expression -> Expression
+ Autodocodec.Nix: ExprLet :: !Map Text Expression -> !Expression -> Expression
+ Autodocodec.Nix: ExprSelect :: !Expression -> !Text -> Expression
+ Autodocodec.Nix: ExprUpdate :: !Expression -> !Expression -> Expression
+ Autodocodec.Nix: OptionOptional :: OptionRequirement
+ Autodocodec.Nix: OptionRequired :: OptionRequirement
+ Autodocodec.Nix: [optionAlternativeDefaults] :: Option -> ![Maybe Value]
+ Autodocodec.Nix: [optionDocumentedDefault] :: Option -> !Maybe Value
+ Autodocodec.Nix: [optionRequirement] :: Option -> !OptionRequirement
+ Autodocodec.Nix: data OptionRequirement
+ Autodocodec.Nix.Expression: ExprIf :: !Expression -> !Expression -> !Expression -> Expression
+ Autodocodec.Nix.Expression: ExprLam :: !Text -> !Expression -> Expression
+ Autodocodec.Nix.Expression: ExprLet :: !Map Text Expression -> !Expression -> Expression
+ Autodocodec.Nix.Expression: ExprSelect :: !Expression -> !Text -> Expression
+ Autodocodec.Nix.Expression: ExprUpdate :: !Expression -> !Expression -> Expression
+ Autodocodec.Nix.Expression: instance GHC.Classes.Eq Autodocodec.Nix.Expression.Position
+ Autodocodec.Nix.Expression: instance GHC.Classes.Ord Autodocodec.Nix.Expression.Position
+ Autodocodec.Nix.Options: OptionOptional :: OptionRequirement
+ Autodocodec.Nix.Options: OptionRequired :: OptionRequirement
+ Autodocodec.Nix.Options: [optionAlternativeDefaults] :: Option -> ![Maybe Value]
+ Autodocodec.Nix.Options: [optionDocumentedDefault] :: Option -> !Maybe Value
+ Autodocodec.Nix.Options: [optionRequirement] :: Option -> !OptionRequirement
+ Autodocodec.Nix.Options: data OptionRequirement
+ Autodocodec.Nix.Options: instance GHC.Classes.Eq Autodocodec.Nix.Options.OptionRequirement
+ Autodocodec.Nix.Options: instance GHC.Classes.Ord Autodocodec.Nix.Options.OptionRequirement
+ Autodocodec.Nix.Options: instance GHC.Show.Show Autodocodec.Nix.Options.OptionRequirement
- Autodocodec.Nix: Option :: !Maybe OptionType -> !Maybe Text -> !Maybe Value -> Option
+ Autodocodec.Nix: Option :: !Maybe OptionType -> !Maybe Text -> !Maybe Value -> ![Maybe Value] -> !OptionRequirement -> !Maybe Value -> Option
- Autodocodec.Nix.Options: Option :: !Maybe OptionType -> !Maybe Text -> !Maybe Value -> Option
+ Autodocodec.Nix.Options: Option :: !Maybe OptionType -> !Maybe Text -> !Maybe Value -> ![Maybe Value] -> !OptionRequirement -> !Maybe Value -> Option

Files

CHANGELOG.md view
@@ -1,5 +1,39 @@ # Changelog +## [0.2.0.0] - 2026-11-14++### Added++* `ExprLam`, `ExprLet`, `ExprIf`, `ExprUpdate` and `ExprSelect`.+* `optionRequirement`, `optionAlternativeDefaults` and `optionDocumentedDefault`+  in `Option`.++### Changed++* A key that may be left out no longer defaults to `null`, and is left out of+  the value when it is not set.+* A generated submodule throws when a required key is not set.+* The submodules of a choice between objects are merged into one.+* Generated types need nixpkgs 25.11 or newer.++### Removed++* `renderNixOptionsVia`, `renderNixOptionsViaCodec`, `optionsExpression` and+  `optionsExpr`.+  Use `renderNixOptionTypeVia` instead.++### Fixed++* The discriminator of a discriminated union is an enum.+* Strings and quoted attribute keys are rendered as Nix string literals.+  They used to be rendered as Haskell string literals, so Nix read a+  non-ASCII character like `é` as its code point, `233`, and interpolated a+  `${`.+* A negative number in a list or as an argument is put in parentheses.+  Nix read `[ -1 ]` as a subtraction, which it could not parse.+* The element of a list of one element is put in parentheses when it needs+  them, so an application in it is no longer read as two elements.+ ## [0.1.1.0] - 2026-10-06  ### Changed
autodocodec-nix.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           autodocodec-nix-version:        0.1.1.0+version:        0.2.0.0 synopsis:       Autodocodec interpreters for nix homepage:       https://github.com/NorfairKing/autodocodec#readme bug-reports:    https://github.com/NorfairKing/autodocodec/issues
src/Autodocodec/Nix.hs view
@@ -3,12 +3,11 @@ module Autodocodec.Nix   ( -- * Producing a Nixos module type     renderNixOptionTypeViaCodec,-    renderNixOptionsViaCodec,     renderNixOptionTypeVia,-    renderNixOptionsVia,     valueCodecNixOptionType,     objectCodecNixOptions,     Option (..),+    OptionRequirement (..),     emptyOption,     simplifyOption,     OptionType (..),@@ -18,8 +17,6 @@     withNixArgs,     optionExpression,     optionExpr,-    optionsExpression,-    optionsExpr,     optionTypeExpression,     optionTypeExpr, 
src/Autodocodec/Nix/Expression.hs view
@@ -39,61 +39,142 @@   | ExprVar !Text   | ExprAttrSet !(Map Text Expression)   | ExprAp !Expression !Expression-  | ExprFun ![Text] !Expression+  | -- | A function with a set pattern: @{ a, b }: e@+    ExprFun ![Text] !Expression   | ExprWith !Text !Expression+  | -- | A function with a single argument: @a: e@+    ExprLam !Text !Expression+  | ExprLet !(Map Text Expression) !Expression+  | ExprIf !Expression !Expression !Expression+  | -- | @e1 // e2@+    ExprUpdate !Expression !Expression+  | -- | @e.key@+    ExprSelect !Expression !Text   deriving (Show, Eq, Ord)  -- {-# DEPRECATED renderExpr "Use renderExpression instead" #-} renderExpr :: Expr -> Text renderExpr = renderExpression +-- | Where an expression is rendered.+--+-- A later position admits fewer expressions without parentheses, so an+-- expression decides whether it needs them by comparing the position to the+-- last one it can stand in.+data Position+  = -- | Where an expression ends, so anything can stand there.+    -- A function, @let@, @if@ or @with@ extends as far to the right as it+    -- can, so it needs this position.+    PositionEnd+  | -- | Where an expression is followed by more of the expression around it,+    -- like the condition of an @if@.+    PositionInner+  | -- | The right operand of @//@, which groups to the right.+    PositionUpdateRight+  | -- | The left operand of @//@.+    PositionUpdateLeft+  | -- | The function of an application.+    PositionApplied+  | -- | An argument or a list element.+    PositionArgument+  | -- | Where an attribute is selected from.+    PositionSelected+  deriving (Eq, Ord)+ renderExpression :: Expr -> Text-renderExpression = T.unlines . go 0+renderExpression = T.unlines . go PositionEnd   where     parensWhen b ts = if b then parens ts else ts-    go :: Int -> Expr -> [Text]-    go d = \case+    go :: Position -> Expr -> [Text]+    go p = \case       ExprNull -> ["null"]       ExprLitBool b -> [if b then "true" else "false"]-      ExprLitString s -> [T.pack $ show $ T.unpack s]+      ExprLitString s -> [nixString s]       ExprLitNumber s ->-        [ case floatingOrInteger s of-            Left f -> T.pack $ show (f :: Double)-            Right i -> T.pack $ show (i :: Integer)-        ]+        -- Nix reads a minus in a list or an argument as subtraction.+        parensWhen+          (p > PositionApplied && s < 0)+          [ case floatingOrInteger s of+              Left f -> T.pack $ show (f :: Double)+              Right i -> T.pack $ show (i :: Integer)+          ]       ExprLitList es -> case es of         [] -> ["[]"]-        [e] -> surround "[" "]" $ go 0 e+        [e] -> surround "[" "]" $ go PositionArgument e         _ ->           -- If there is more than one list element, put them on separate lines.-          "[" : indent (concatMap (go 11) es) ++ ["]"]+          "[" : indent (concatMap (go PositionArgument) es) ++ ["]"]       ExprVar s -> [s]       ExprAttrSet m | null m -> ["{ }"]       ExprAttrSet m ->         -- We always put "{" and "}" on separate lines.         "{" : indent (concatMap (uncurry goBind) (M.toList m)) ++ ["}"]       ExprAp e1 e2 ->-        parensWhen (d > 10) $-          go 11 e1 `apply` go 11 e2+        parensWhen (p > PositionApplied) $+          go PositionApplied e1 `apply` go PositionArgument e2       ExprFun args e ->-        parensWhen (d > 10) $+        parensWhen (p > PositionEnd) $           surroundWith " " "{" "}:" [T.intercalate ", " args]-            ++ go 0 e+            ++ go PositionEnd e       ExprWith t e ->-        parensWhen (d > 10) $-          ("with " <> t <> ";") : go 0 e+        parensWhen (p > PositionEnd) $+          ("with " <> t <> ";") : go PositionEnd e+      ExprLam arg e ->+        parensWhen (p > PositionEnd) $+          prependWith " " (arg <> ":") (go PositionEnd e)+      ExprLet binds e+        | null binds -> go p e+        | otherwise ->+            parensWhen (p > PositionEnd) $+              concat+                [ ["let"],+                  indent (concatMap (uncurry goBind) (M.toList binds)),+                  ["in"],+                  go PositionEnd e+                ]+      ExprIf c t e ->+        parensWhen (p > PositionEnd) $+          joinWith+            " else "+            ( joinWith+                " then "+                (prependWith " " "if" (go PositionInner c))+                (go PositionInner t)+            )+            (go PositionEnd e)+      ExprUpdate e1 e2 ->+        parensWhen (p > PositionUpdateRight) $+          joinWith " // " (go PositionUpdateLeft e1) (go PositionUpdateRight e2)+      ExprSelect e key ->+        go PositionSelected e `append` T.cons '.' (nixAttrKey key)     goBind key e =       prependWith " " (nixAttrKey key <> " =") $         (`append` ";") $-          go 0 e+          go PositionEnd e  -- | Quote an attribute key if it is not a valid Nix identifier. -- Valid identifiers match @[a-zA-Z_][a-zA-Z0-9_'-]*@. nixAttrKey :: Text -> Text nixAttrKey key   | isNixIdentifier key = key-  | otherwise = T.pack $ show $ T.unpack key+  | otherwise = nixString key +-- | A Nix string literal that Nix reads as the given text.+--+-- Not Haskell's 'show', because Nix has no numeric escapes, so it reads+-- @\"\\233\"@ as @\"233\"@, and because Nix interpolates @${@.+nixString :: Text -> Text+nixString s =+  let escape :: Char -> Text+      escape = \case+        '"' -> "\\\""+        '\\' -> "\\\\"+        '\n' -> "\\n"+        '\r' -> "\\r"+        '\t' -> "\\t"+        c -> T.singleton c+   in T.concat ["\"", T.replace "${" "\\${" (T.concatMap escape s), "\""]+ isNixIdentifier :: Text -> Bool isNixIdentifier t = case T.uncons t of   Nothing -> False@@ -121,11 +202,17 @@       [t] -> [t <> spacer <> u]       (t : ts') -> t : go ts' +-- | Join the last line of the first with the first line of the second.+joinWith :: Text -> [Text] -> [Text] -> [Text]+joinWith spacer ts1 = \case+  [] -> ts1+  (t2 : ts2) -> appendWith spacer ts1 t2 ++ ts2+ apply :: [Text] -> [Text] -> [Text] apply ts1 ts2 = case (ts1, ts2) of   ([t1], [t2]) -> [t1 <> " " <> t2]   ([t1], _) -> prependWith " " t1 ts2-  (_, [t2]) -> ts1 `append` t2+  (_, [t2]) -> appendWith " " ts1 t2   _ -> go ts1     where       go = \case
src/Autodocodec/Nix/Options.hs view
@@ -10,12 +10,11 @@ module Autodocodec.Nix.Options   ( -- * Producing a Nixos module type     renderNixOptionTypeViaCodec,-    renderNixOptionsViaCodec,     renderNixOptionTypeVia,-    renderNixOptionsVia,     valueCodecNixOptionType,     objectCodecNixOptions,     Option (..),+    OptionRequirement (..),     emptyOption,     simplifyOption,     OptionType (..),@@ -25,8 +24,6 @@     withNixArgs,     optionExpression,     optionExpr,-    optionsExpression,-    optionsExpr,     optionTypeExpression,     optionTypeExpr,     renderExpression,@@ -36,10 +33,11 @@ import Autodocodec import Autodocodec.Nix.Expression import Autodocodec.Nix.Render-import Control.Applicative import Data.Aeson as JSON import Data.Containers.ListUtils import qualified Data.HashMap.Strict as HM+import Data.List (intercalate)+import qualified Data.Map.Merge.Strict as Merge import Data.Map.Strict (Map) import qualified Data.Map.Strict as M import Data.Maybe@@ -49,20 +47,12 @@ renderNixOptionTypeViaCodec :: forall a. (HasCodec a) => Text renderNixOptionTypeViaCodec = renderNixOptionTypeVia (codec @a) -renderNixOptionsViaCodec :: forall a. (HasObjectCodec a) => Text-renderNixOptionsViaCodec = renderNixOptionsVia (objectCodec @a)- renderNixOptionTypeVia :: ValueCodec input output -> Text renderNixOptionTypeVia =   renderOptionType     . fromMaybe (OptionTypeSimple "lib.types.anything")     . valueCodecNixOptionType -renderNixOptionsVia :: ObjectCodec input output -> Text-renderNixOptionsVia =-  renderOptions-    . objectCodecNixOptions- valueCodecNixOptionType :: ValueCodec input output -> Maybe OptionType valueCodecNixOptionType = fmap simplifyOptionType . go   where@@ -93,104 +83,178 @@       MapCodec c -> Just $ OptionTypeAttrsOf $ mTyp $ go c       ValueCodec -> Just (OptionTypeSimple "lib.types.unspecified")       ArrayOfCodec _ c -> Just $ OptionTypeListOf $ mTyp $ go c-      ObjectOfCodec _ oc -> Just (OptionTypeSubmodule (objectCodecNixOptions oc))+      ObjectOfCodec _ oc -> Just $ OptionTypeSubmodule $ objectCodecNixOptions oc       EqCodec v c -> Just $ OptionTypeEnum [toNixExpressionVia c v]       BimapCodec _ _ c -> go c       EitherCodec _ c1 c2 -> Just $ OptionTypeOneOf (map mTyp [go c1, go c2])       CommentCodec _ c -> go c       ReferenceCodec {} -> Nothing -- TODO: let-binding? --- [tag:NixOptionNullable]--- Note about nullable options:--- It's not technically accurate to represent optional fields as the 'null' value in Nix,--- but Nix isn't very good at optional values at all, so we use 'null' for both--- optional fields and nullable fields.--- If Nix options ever figure out how to do optional fields, we'll use that--- instead.+-- | A key that may be left out gets an option without a default, so that+-- leaving it out and setting it to 'null' can be told apart.+-- The value of a generated submodule is what was defined in it, and nothing+-- that was not.+-- Reading it throws when a required option was not defined.+--+-- The option that a generated submodule is the type of cannot be declared+-- again, because the module system would merge the declarations into a plain+-- submodule, whose value is not what was defined. objectCodecNixOptions :: ObjectCodec input output -> Map Text Option-objectCodecNixOptions = simplifyOptions . go False-  where-    -- The bool means 'force optional'-    go :: Bool -> ObjectCodec input output -> Map Text Option-    go b = \case-      DiscriminatedUnionCodec k _ m ->-        M.insert-          k-          ( Option-              { optionType = Just $ OptionTypeOneOf $ map (OptionTypeSimple . T.pack . show) $ HM.keys m,-                optionDescription = Nothing,-                optionDefault = Nothing+objectCodecNixOptions =+  let undefaultedOption :: OptionRequirement -> ValueCodec input output -> Maybe Text -> Option+      undefaultedOption requirement c mDesc =+        Option+          { optionType = valueCodecNixOptionType c,+            optionDescription = optionDescriptionFor mDesc c,+            optionDefault = Nothing,+            optionAlternativeDefaults = [],+            optionRequirement = requirement,+            optionDocumentedDefault = Nothing+          }+      requiredByEither :: OptionRequirement -> OptionRequirement -> OptionRequirement+      requiredByEither r1 r2 = case r1 of+        OptionRequired -> OptionRequired+        OptionOptional -> r2+      go :: ObjectCodec input output -> Map Text Option+      go = \case+        DiscriminatedUnionCodec k _ m ->+          -- Ordered by discriminator, so that the output does not depend on+          -- the order of a HashMap.+          let byDiscriminator = M.fromList $ HM.toList m+           in M.insert+                k+                ( Option+                    { optionType = Just $ OptionTypeEnum $ map ExprLitString $ M.keys byDiscriminator,+                      optionDescription = Nothing,+                      optionDefault = Nothing,+                      optionAlternativeDefaults = [],+                      optionRequirement = OptionRequired,+                      optionDocumentedDefault = Nothing+                    }+                )+                $ case map (go . snd) $ M.elems byDiscriminator of+                  [] -> M.empty+                  alternative : alternatives -> foldr mergeAlternatives alternative alternatives+        RequiredKeyCodec key o mDesc -> M.singleton key $ undefaultedOption OptionRequired o mDesc+        OptionalKeyCodec key o mDesc -> M.singleton key $ undefaultedOption OptionOptional o mDesc+        OptionalKeyWithDefaultCodec key c defaultValue mDesc ->+          M.singleton+            key+            Option+              { optionType = valueCodecNixOptionType c,+                optionDescription = optionDescriptionFor mDesc c,+                optionDefault = Just $ toJSONVia c defaultValue,+                optionAlternativeDefaults = [],+                optionRequirement = OptionOptional,+                optionDocumentedDefault = Nothing               }-          )-          $ M.unionsWith-            ( \t1 t2 ->-                Option-                  { optionType = Just $ OptionTypeOneOf $ map (fromMaybe (OptionTypeSimple "lib.types.anything") . optionType) [t1, t2],-                    optionDescription = optionDescription t1 <|> optionDescription t2, -- TODO-                    optionDefault = Nothing+        OptionalKeyWithOmittedDefaultCodec key c defaultValue mDesc ->+          M.singleton+            key+            Option+              { optionType = valueCodecNixOptionType c,+                optionDescription = optionDescriptionFor mDesc c,+                optionDefault = Just $ toJSONVia c defaultValue,+                optionAlternativeDefaults = [],+                optionRequirement = OptionOptional,+                optionDocumentedDefault = Nothing+              }+        PureCodec _ -> M.empty+        ApCodec c1 c2 ->+          M.unionWith+            ( \o1 o2 ->+                (mergeOption o1 o2)+                  { optionRequirement = requiredByEither (optionRequirement o1) (optionRequirement o2)                   }             )-          $ map (go b . snd)-          $ HM.elems m-      RequiredKeyCodec key o mDesc ->-        M.singleton key $-          Option-            { optionType =-                ( if b-                    then fmap OptionTypeNullOr-                    else id-                )-                  $ valueCodecNixOptionType o,-              optionDescription = optionDescriptionFor mDesc o,-              optionDefault =-                if b-                  then Just JSON.Null-                  else Nothing -- [ref:NixOptionNullable]-            }-      OptionalKeyCodec key o mDesc ->-        M.singleton key $-          Option-            { optionType = OptionTypeNullOr <$> valueCodecNixOptionType o,-              optionDescription = optionDescriptionFor mDesc o,-              optionDefault = Just JSON.Null -- [ref:NixOptionNullable]-            }-      OptionalKeyWithDefaultCodec key c defaultValue mDesc ->-        M.singleton-          key-          Option-            { optionType = valueCodecNixOptionType c,-              optionDescription = optionDescriptionFor mDesc c,-              optionDefault = Just $ toJSONVia c defaultValue+            (go c1)+            (go c2)+        BimapCodec _ _ c -> go c+        EitherCodec _ c1 c2 -> mergeAlternatives (go c1) (go c2)+   in simplifyOptions . go++-- | The options of a choice between objects.+--+-- A value for any one alternative is a valid value, so a key is only required+-- when every alternative requires it, and only keeps a default when every+-- alternative has the same one.+-- Otherwise the defaults of the alternatives are kept for the documentation,+-- because the codec applies the default of the alternative that it parses.+mergeAlternatives :: Map Text Option -> Map Text Option -> Map Text Option+mergeAlternatives =+  let -- What the alternatives that an option comes from do when it is not+      -- defined: apply a default, or leave it out.+      -- An alternative that requires it does not parse without it, so it+      -- does nothing.+      whenUnset :: Option -> [Maybe JSON.Value]+      whenUnset o = case optionRequirement o of+        OptionRequired -> []+        OptionOptional -> case optionAlternativeDefaults o of+          [] -> [optionDefault o]+          defaults -> defaults+      withWhenUnset :: [Maybe JSON.Value] -> Option -> Option+      withWhenUnset unset o = case nubOrd unset of+        [d] ->+          o+            { optionDefault = d,+              optionAlternativeDefaults = []             }-      OptionalKeyWithOmittedDefaultCodec key c defaultValue mDesc ->-        M.singleton-          key-          Option-            { optionType = valueCodecNixOptionType c,-              optionDescription = optionDescriptionFor mDesc c,-              optionDefault = Just $ toJSONVia c defaultValue+        unset' ->+          o+            { optionDefault = Nothing,+              optionAlternativeDefaults = unset'             }-      PureCodec _ -> M.empty-      ApCodec c1 c2 -> M.unionWith mergeOption (go b c1) (go b c2)-      BimapCodec _ _ c -> go b c-      EitherCodec _ c1 c2 -> M.unionWith mergeOption (go True c1) (go True c2)-    -- This throwing away of the description and the default is not ideal but-    -- better than just taking the first option.-    mergeOption :: Option -> Option -> Option-    mergeOption o1 o2 =-      o1-        { optionType =-            ( \ot1 ot2 ->-                simplifyOptionType $-                  OptionTypeOneOf-                    [ ot1,-                      ot2-                    ]+      -- The alternative that does not have the key leaves it out.+      onlyInOne :: Option -> Option+      onlyInOne o =+        withWhenUnset (whenUnset o ++ [Nothing]) $+          o {optionRequirement = OptionOptional}+      requiredByBoth :: OptionRequirement -> OptionRequirement -> OptionRequirement+      requiredByBoth r1 r2 = case r1 of+        OptionRequired -> r2+        OptionOptional -> OptionOptional+   in Merge.merge+        (Merge.mapMissing (const onlyInOne))+        (Merge.mapMissing (const onlyInOne))+        ( Merge.zipWithMatched+            ( \_ o1 o2 ->+                withWhenUnset (whenUnset o1 ++ whenUnset o2) $+                  (mergeOption o1 o2)+                    { optionRequirement = requiredByBoth (optionRequirement o1) (optionRequirement o2)+                    }             )-              <$> optionType o1-              <*> optionType o2-        }+        ) +-- | Two options for the same key.+--+-- Keeping only the first description is not ideal but better than dropping+-- both.+-- A default is only kept when both agree on it, because the value of the+-- option is written out whichever alternative the rest of the value is for.+mergeOption :: Option -> Option -> Option+mergeOption o1 o2 =+  o1+    { optionDefault =+        if optionDefault o1 == optionDefault o2+          then optionDefault o1+          else Nothing,+      optionAlternativeDefaults = nubOrd (optionAlternativeDefaults o1 ++ optionAlternativeDefaults o2),+      optionDocumentedDefault =+        if optionDocumentedDefault o1 == optionDocumentedDefault o2+          then optionDocumentedDefault o1+          else Nothing,+      optionType =+        ( \ot1 ot2 ->+            simplifyOptionType $+              OptionTypeOneOf+                [ ot1,+                  ot2+                ]+        )+          <$> optionType o1+          <*> optionType o2+    }+ -- | What an option says about itself: the field's own description, and then -- whatever comments the codec under it carries. --@@ -230,16 +294,35 @@ data Option = Option   { optionType :: !(Maybe OptionType),     optionDescription :: !(Maybe Text),-    optionDefault :: !(Maybe JSON.Value)+    optionDefault :: !(Maybe JSON.Value),+    -- | What the alternatives of a choice between objects do when the option+    -- is not defined, when they do not all do the same: apply a default+    -- ('Just'), or leave it out ('Nothing').+    -- The option then has no default, and its documentation lists these.+    optionAlternativeDefaults :: ![Maybe JSON.Value],+    optionRequirement :: !OptionRequirement,+    -- | The default that whatever reads the value applies when the option is+    -- left out, for an option without a default in Nix.+    -- It is only documented, so that the value still leaves the option out.+    optionDocumentedDefault :: !(Maybe JSON.Value)   }   deriving (Show, Eq, Ord) +-- | Whether an option has to be defined.+data OptionRequirement+  = OptionRequired+  | OptionOptional+  deriving (Show, Eq, Ord)+ emptyOption :: Option emptyOption =   Option     { optionType = Nothing,       optionDescription = Nothing,-      optionDefault = Nothing+      optionDefault = Nothing,+      optionAlternativeDefaults = [],+      optionRequirement = OptionOptional,+      optionDocumentedDefault = Nothing     }  simplifyOption :: Option -> Option@@ -270,7 +353,7 @@         _ -> OptionTypeNullOr $ go t       OptionTypeListOf o -> OptionTypeListOf $ go o       OptionTypeAttrsOf o -> OptionTypeAttrsOf $ go o-      OptionTypeOneOf os -> case goEnums $ nubOrd $ concatMap goOr os of+      OptionTypeOneOf os -> case goEnums $ mergeSubmodules $ nubOrd $ concatMap goOr os of         [ot] -> ot         os' ->           if any canBeNull os'@@ -304,6 +387,32 @@             OptionTypeEnum es' -> goEnum (es ++ es') rest             _ -> t : goEnum es rest +    -- The module system merges a value of a oneOf with the first alternative+    -- whose check it passes, and that of a submodule only asks for an+    -- attribute set, so a value for any later submodule would be merged with+    -- the first one instead.+    mergeSubmodules :: [OptionType] -> [OptionType]+    mergeSubmodules ts = case mapMaybe submoduleOptions ts of+      m : ms@(_ : _) ->+        let (before, after) = break (isJust . submoduleOptions) ts+         in concat+              [ before,+                [OptionTypeSubmodule $ M.map goOpt $ foldr mergeAlternatives m ms],+                filter (isNothing . submoduleOptions) after+              ]+      _ -> ts++    submoduleOptions :: OptionType -> Maybe (Map Text Option)+    submoduleOptions = \case+      OptionTypeSubmodule m -> Just m+      OptionTypeNull -> Nothing+      OptionTypeSimple _ -> Nothing+      OptionTypeEnum _ -> Nothing+      OptionTypeNullOr _ -> Nothing+      OptionTypeListOf _ -> Nothing+      OptionTypeAttrsOf _ -> Nothing+      OptionTypeOneOf _ -> Nothing+     goOpt o = o {optionType = go <$> optionType o}      goOr = \case@@ -316,9 +425,6 @@ renderOption :: Option -> Text renderOption = renderExpression . withNixArgs . optionExpression -renderOptions :: Map Text Option -> Text-renderOptions = renderExpression . withNixArgs . optionsExpression- renderOptionType :: OptionType -> Text renderOptionType = renderExpression . withNixArgs . optionTypeExpression @@ -330,36 +436,86 @@ optionExpr = optionExpression  optionExpression :: Option -> Expression-optionExpression Option {..} =-  ExprAp-    (ExprVar "lib.mkOption")-    ( ExprAttrSet $-        M.fromList $-          concat-            [ [("type", optionTypeExpression typ) | typ <- maybeToList optionType],-              [("description", ExprLitString d) | d <- maybeToList optionDescription],-              case optionDefault of-                Nothing -> case optionType of-                  -- Automatically give submodule options a default of the empty set.-                  Just (OptionTypeSubmodule _) -> [("default", ExprAttrSet M.empty)]-                  _ -> []-                Just d -> [("default", toNixExpressionViaCodec d)]-            ]-    )---- {-# DEPRECATED optionsExpr "Use optionsExpression instead" #-}-optionsExpr :: Map Text Option -> Expression-optionsExpr = optionsExpression--optionsExpression :: Map Text Option -> Expression-optionsExpression = ExprAttrSet . M.map optionExpression+optionExpression o = bindDefinedSubmodule (maybeToList (optionType o)) $ unboundOptionExpression o  -- {-# DEPRECATED optionTypeExpr "Use optionTypeExpression instead" #-} optionTypeExpr :: OptionType -> Expression optionTypeExpr = optionTypeExpression  optionTypeExpression :: OptionType -> Expression-optionTypeExpression = go+optionTypeExpression t = bindDefinedSubmodule [t] $ unboundOptionTypeExpression t++-- | An option that refers to 'definedSubmoduleName' without binding it.+unboundOptionExpression :: Option -> Expression+unboundOptionExpression Option {..} =+  let inlineNix :: JSON.Value -> String+      inlineNix d =+        unwords $+          map (T.unpack . T.strip) $+            T.lines $+              renderExpression $+                toNixExpressionViaCodec d+      orList :: [String] -> String+      orList ws = case reverse ws of+        [] -> ""+        [w] -> w+        lastWord : rest -> unwords [intercalate ", " (reverse rest), "or", lastWord]+      undefaultedText :: Text+      undefaultedText = case optionRequirement of+        OptionRequired -> "None, required"+        OptionOptional -> case catMaybes optionAlternativeDefaults of+          [] -> "Unspecified"+          defaults ->+            T.pack $+              concat+                [ orList $+                    map (\d -> concat ["`", inlineNix d, "`"]) defaults+                      ++ ["unspecified" | Nothing `elem` optionAlternativeDefaults],+                  ", depending on the first alternative that parses"+                ]+      -- The documentation gives a submodule no default, and a submodule that+      -- is not specified leaves each of its options to its own default, so+      -- there is nothing to say about it.+      isUnspecifiedSubmodule :: Bool+      isUnspecifiedSubmodule = case (optionRequirement, optionAlternativeDefaults, optionDocumentedDefault, optionType) of+        (OptionOptional, [], Nothing, Just (OptionTypeSubmodule _)) -> True+        (OptionOptional, [], Nothing, Just (OptionTypeNullOr (OptionTypeSubmodule _))) -> True+        _ -> False+   in ExprAp+        (ExprVar "lib.mkOption")+        ( ExprAttrSet $+            M.fromList $+              concat+                [ [("type", unboundOptionTypeExpression typ) | typ <- maybeToList optionType],+                  [("description", ExprLitString d) | d <- maybeToList optionDescription],+                  case optionDefault of+                    -- The documentation would otherwise give the empty value+                    -- of the type, like null for a nullOr, as the default.+                    Nothing ->+                      [ ( "defaultText",+                          let text =+                                ExprAp (ExprVar "lib.literalMD") $+                                  ExprLitString $+                                    case optionDocumentedDefault of+                                      Nothing -> undefaultedText+                                      Just d -> T.pack $ concat [T.unpack undefaultedText, ", interpreted as `", inlineNix d, "`"]+                           in -- The documentation keeps the other fields of a+                              -- defaultText, so that whatever renders it can+                              -- tell a required option apart without reading+                              -- the text.+                              case optionRequirement of+                                OptionRequired -> ExprUpdate text (ExprAttrSet (M.singleton "required" (ExprLitBool True)))+                                OptionOptional -> text+                        )+                      | not isUnspecifiedSubmodule+                      ]+                    Just d -> [("default", toNixExpressionViaCodec d)]+                ]+        )++-- | A type that refers to 'definedSubmoduleName' without binding it.+unboundOptionTypeExpression :: OptionType -> Expression+unboundOptionTypeExpression = go   where     go = \case       OptionTypeNull -> ExprAp (ExprVar "lib.types.enum") (ExprLitList [ExprNull])@@ -379,6 +535,145 @@           (ExprVar "lib.types.oneOf")           (ExprLitList (map go os))       OptionTypeSubmodule os ->-        ExprAp-          (ExprVar "lib.types.submodule")-          (ExprAttrSet (M.singleton "options" (optionsExpression os)))+        let requiredKey :: Text -> Option -> Maybe Expression+            requiredKey key o = case optionRequirement o of+              OptionRequired -> Just (ExprLitString key)+              OptionOptional -> Nothing+         in ExprAp+              (ExprAp (ExprVar definedSubmoduleName) (ExprLitList (M.elems (M.mapMaybeWithKey requiredKey os))))+              (ExprAttrSet (M.map unboundOptionExpression os))++-- | Bind 'definedSubmoduleName' around an expression that uses any of the+-- given types, once per expression instead of once per submodule.+bindDefinedSubmodule :: [OptionType] -> Expression -> Expression+bindDefinedSubmodule ts e =+  if any hasSubmodule ts+    then+      ExprLet+        ( M.fromList+            [ (definedSubmoduleName, definedSubmoduleExpression),+              (definedTypeName, definedTypeExpression)+            ]+        )+        e+    else e++hasSubmodule :: OptionType -> Bool+hasSubmodule = \case+  OptionTypeNull -> False+  OptionTypeSimple _ -> False+  OptionTypeEnum _ -> False+  OptionTypeNullOr t -> hasSubmodule t+  OptionTypeListOf t -> hasSubmodule t+  OptionTypeAttrsOf t -> hasSubmodule t+  OptionTypeOneOf ts -> any hasSubmodule ts+  OptionTypeSubmodule _ -> True++definedSubmoduleName :: Text+definedSubmoduleName = "definedSubmodule"++definedTypeName :: Text+definedTypeName = "definedType"++-- | A function from the required keys and the option declarations of a+-- submodule to a submodule type that 'definedTypeExpression' makes of it.+definedSubmoduleExpression :: Expression+definedSubmoduleExpression =+  ExprLam "required" $+    ExprLam "declarations" $+      ExprAp+        (ExprAp (ExprVar definedTypeName) (ExprVar "required"))+        (ExprAp (ExprVar "lib.types.submodule") (ExprAttrSet (M.singleton "options" (ExprVar "declarations"))))++-- | A function from the required keys of a submodule type and that type to a+-- submodule type whose value is what was defined in it: the options that were+-- defined, and the required ones whether they were or not.+--+-- Reading an option that was not defined does not throw when its type has an+-- empty value, like null for a nullOr or [ ] for a listOf, so a required+-- option throws itself.+-- Which options were defined is read from the evaluated submodule that the v2+-- merge of nixpkgs returns next to the value.+-- Its merge is changed, rather than anything reading the value, so that it+-- also covers a submodule nested in any other type, because those merge their+-- elements with the element type's merge.+-- The module system rebuilds the type of an option from its submodules, so the+-- type it ends up with is made the same way.+-- It cannot be merged with another declaration of the same option, because+-- the result would be a plain submodule, whose value is not what was defined.+-- Its functor has a name of its own so that a plain submodule cannot be merged+-- with it either.+-- It has no empty value, so that reading an option of this type that has no+-- definitions throws instead of giving every option of the submodule.+definedTypeExpression :: Expression+definedTypeExpression =+  let apply :: Text -> [Expression] -> Expression+      apply f = foldl ExprAp (ExprVar f)+      submodule :: Text -> Expression+      submodule = ExprSelect (ExprVar "submodule")+      optionOf :: Expression+      optionOf = apply "lib.getAttr" [ExprVar "name", ExprVar "options"]+      requiredValue :: Expression+      requiredValue =+        ExprLam "name" $+          ExprIf+            (ExprAp (ExprVar "isDefined") (ExprVar "name"))+            (ExprAp (ExprVar "configValue") (ExprVar "name"))+            ( apply+                "throw"+                [ apply+                    "lib.concatStrings"+                    [ ExprLitList+                        [ ExprLitString "The option `",+                          ExprAp (ExprVar "lib.showOption") (ExprSelect optionOf "loc"),+                          ExprLitString "' is required but was not defined."+                        ]+                    ]+                ]+            )+      -- The submodule's own merge calls the v2 merge of what it is part of+      -- when it is called as a function, so only the v2 merge is replaced.+      mergeV2 :: Expression+      mergeV2 =+        ExprLam "args" $+          ExprLet+            ( M.fromList+                [ ("merged", ExprAp (ExprSelect (submodule "merge") "v2") (ExprVar "args")),+                  ("options", ExprSelect (ExprSelect (ExprSelect (ExprVar "merged") "valueMeta") "configuration") "options"),+                  ("isDefined", ExprLam "name" (ExprSelect optionOf "isDefined")),+                  ("configValue", ExprLam "name" (apply "lib.getAttr" [ExprVar "name", ExprSelect (ExprVar "merged") "value"])),+                  ("requiredValue", requiredValue)+                ]+            )+            ( ExprUpdate (ExprVar "merged") $+                ExprAttrSet $+                  M.singleton "value" $+                    ExprUpdate+                      (apply "lib.genAttrs" [ExprVar "required", ExprVar "requiredValue"])+                      ( apply+                          "lib.genAttrs"+                          [ apply+                              "lib.filter"+                              [ ExprVar "isDefined",+                                apply "lib.attrNames" [apply "lib.removeAttrs" [ExprVar "options", ExprLitList [ExprLitString "_module"]]]+                              ],+                            ExprVar "configValue"+                          ]+                      )+            )+   in ExprLam "required" $+        ExprLam "submodule" $+          ExprUpdate (ExprVar "submodule") $+            ExprAttrSet $+              M.fromList+                [ ("merge", ExprUpdate (submodule "merge") (ExprAttrSet (M.singleton "v2" mergeV2))),+                  ("emptyValue", ExprAttrSet M.empty),+                  ( "substSubModules",+                    ExprLam "modules" $+                      ExprAp+                        (ExprAp (ExprVar definedTypeName) (ExprVar "required"))+                        (ExprAp (submodule "substSubModules") (ExprVar "modules"))+                  ),+                  ("typeMerge", ExprLam "_" ExprNull),+                  ("functor", ExprUpdate (submodule "functor") (ExprAttrSet (M.singleton "name" (ExprLitString definedSubmoduleName))))+                ]