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 +34/−0
- autodocodec-nix.cabal +1/−1
- src/Autodocodec/Nix.hs +1/−4
- src/Autodocodec/Nix/Expression.hs +107/−20
- src/Autodocodec/Nix/Options.hs +425/−130
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))))+ ]