packages feed

opt-env-conf 0.16.0.0 → 0.17.0.0

raw patch · 6 files changed

+158/−35 lines, 6 filesdep ~autodocodec-nixPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: autodocodec-nix

API changes (from Hackage documentation)

+ OptEnvConf: decodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf: decodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf: exampleValue :: a -> Builder a
+ OptEnvConf: unprefixedDecodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf: unprefixedDecodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf.Setting: BuildAddValueExample :: !a -> BuildInstruction a
+ OptEnvConf.Setting: [configValSettingEncoder] :: ConfigValSetting a -> !Maybe (a -> Value)
+ OptEnvConf.Setting: [settingValueExamples] :: Setting a -> ![a]
+ OptEnvConf.Setting: decodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf.Setting: decodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf.Setting: exampleValue :: a -> Builder a
+ OptEnvConf.Setting: unprefixedDecodeOnlyConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf.Setting: unprefixedDecodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
- OptEnvConf: confWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf: confWith :: String -> JSONCodec a -> Builder a
- OptEnvConf: confWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf: confWith' :: String -> JSONCodec (Maybe a) -> Builder a
- OptEnvConf: unprefixedConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf: unprefixedConfWith :: String -> JSONCodec a -> Builder a
- OptEnvConf: unprefixedConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf: unprefixedConfWith' :: String -> JSONCodec (Maybe a) -> Builder a
- OptEnvConf.Setting: ConfigValSetting :: !NonEmpty String -> !Bool -> !ValueCodec void (Maybe a) -> ConfigValSetting a
+ OptEnvConf.Setting: ConfigValSetting :: !NonEmpty String -> !Bool -> !ValueCodec void (Maybe a) -> !Maybe (a -> Value) -> ConfigValSetting a
- OptEnvConf.Setting: Setting :: ![Dashed] -> ![Reader a] -> !Bool -> !Maybe a -> !Bool -> !Maybe (NonEmpty EnvVarSetting) -> !Maybe (NonEmpty (ConfigValSetting a)) -> !Maybe (a, String) -> ![String] -> !Bool -> !Maybe Metavar -> !Maybe String -> !Maybe Completer -> !Set Capability -> Setting a
+ OptEnvConf.Setting: Setting :: ![Dashed] -> ![Reader a] -> !Bool -> !Maybe a -> !Bool -> !Maybe (NonEmpty EnvVarSetting) -> !Maybe (NonEmpty (ConfigValSetting a)) -> !Maybe (a, String) -> ![String] -> ![a] -> !Bool -> !Maybe Metavar -> !Maybe String -> !Maybe Completer -> !Set Capability -> Setting a
- OptEnvConf.Setting: confWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf.Setting: confWith :: String -> JSONCodec a -> Builder a
- OptEnvConf.Setting: confWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf.Setting: confWith' :: String -> JSONCodec (Maybe a) -> Builder a
- OptEnvConf.Setting: unprefixedConfWith :: String -> ValueCodec void a -> Builder a
+ OptEnvConf.Setting: unprefixedConfWith :: String -> JSONCodec a -> Builder a
- OptEnvConf.Setting: unprefixedConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a
+ OptEnvConf.Setting: unprefixedConfWith' :: String -> JSONCodec (Maybe a) -> Builder a

Files

CHANGELOG.md view
@@ -1,5 +1,25 @@ # Changelog +## [0.17.0.0] - 2026-11-16++### Added++* `exampleValue`, to document an example value of a configuration setting.+* `decodeOnlyConfWith`, `decodeOnlyConfWith'`, `unprefixedDecodeOnlyConfWith`+  and `unprefixedDecodeOnlyConfWith'`, for a codec that can only parse.++### Changed++* `confWith`, `confWith'`, `unprefixedConfWith` and `unprefixedConfWith'` take+  a `JSONCodec`, which can also encode.+  To migrate a codec that can only parse, like `f <$> codec`, make it encode+  with `dimapCodec` or `bimapCodec`, or use `decodeOnlyConfWith` instead.+  Such a `dimapCodec` or `bimapCodec` also works with older versions.+* The Nix option of a setting with a default documents that default whenever+  its codec can encode it, not only when it shows as JSON.+* The Nix option of a setting with an `exampleValue` has that `example`.+* Requires `autodocodec-nix >=0.3.0.0`.+ ## [0.16.0.0] - 2026-11-14  ### Added
opt-env-conf.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           opt-env-conf-version:        0.16.0.0+version:        0.17.0.0 synopsis:       Settings parsing for Haskell: command-line arguments, environment variables, and configuration values. homepage:       https://github.com/NorfairKing/opt-env-conf#readme bug-reports:    https://github.com/NorfairKing/opt-env-conf/issues@@ -53,7 +53,7 @@   build-depends:       aeson     , autodocodec >=0.3.0.0-    , autodocodec-nix >=0.2.0.0+    , autodocodec-nix >=0.3.0.0     , autodocodec-schema     , autodocodec-yaml     , base <5
src/OptEnvConf.hs view
@@ -29,11 +29,16 @@     conf,     confWith,     confWith',+    decodeOnlyConfWith,+    decodeOnlyConfWith',     unprefixedConf,     unprefixedConfWith,     unprefixedConfWith',+    unprefixedDecodeOnlyConfWith,+    unprefixedDecodeOnlyConfWith',     name,     value,+    exampleValue,     hidden,     metavar,     completer,
src/OptEnvConf/Nix.hs view
@@ -16,6 +16,7 @@ import qualified Data.List.NonEmpty as NE import Data.Map (Map) import qualified Data.Map as M+import Data.Maybe (listToMaybe) import Data.Text (Text) import qualified Data.Text as T import OptEnvConf.Parser@@ -78,26 +79,46 @@                               (optionalFieldWith' p configValSettingCodec)                               (optionalFieldWith p configValSettingCodec)                               (T.pack <$> settingHelp s)-                          -- The codec can only decode, so the default is only-                          -- documented when what it shows as is a value that-                          -- the codec accepts, like a number or a string.-                          -- What else it shows as is Haskell, not Nix.                           documentedDefault :: Maybe JSON.Value                           documentedDefault = do-                            (_, shown) <- settingDefaultValue s-                            v <- JSON.decodeStrictText (T.pack shown)-                            _ <- JSON.parseMaybe (parseJSONVia configValSettingCodec) v-                            pure v-                       in M.map (\o -> o {optionDocumentedDefault = documentedDefault}) $ objectCodecNixOptions oc+                            (a, shown) <- settingDefaultValue s+                            case configValSettingEncoder of+                              Just encode -> pure (encode a)+                              -- A codec that can only decode can still+                              -- document the default when what it shows as is+                              -- a value that the codec accepts, like a number+                              -- or a string.+                              -- What else it shows as is Haskell, not Nix.+                              Nothing -> do+                                v <- JSON.decodeStrictText (T.pack shown)+                                _ <- JSON.parseMaybe (parseJSONVia configValSettingCodec) v+                                pure v+                          optionExampleValue :: Maybe JSON.Value+                          optionExampleValue = do+                            encode <- configValSettingEncoder+                            -- A Nix option has only one example.+                            a <- listToMaybe (settingValueExamples s)+                            pure (encode a)+                       in M.map+                            ( \o ->+                                o+                                  { optionDocumentedDefault = documentedDefault,+                                    optionExample = optionExampleValue+                                  }+                            )+                            $ objectCodecNixOptions oc                     Just rest ->                       let m = go' rest                        in M.singleton p $ emptyOption {optionType = Just (OptionTypeSubmodule m)}                in go' $ NE.map T.pack configValSettingPath     combineOption :: Option -> Option -> Option-    combineOption o1 o2 = case (optionType o1, optionType o2) of-      (Nothing, _) -> o2-      (Just ot1, Nothing) -> o2 {optionType = Just ot1}-      (Just ot1, Just ot2) -> o2 {optionType = Just $ combineOptionType ot1 ot2}+    combineOption o1 o2 =+      let o = case (optionType o1, optionType o2) of+            (Nothing, _) -> o2+            (Just ot1, Nothing) -> o2 {optionType = Just ot1}+            (Just ot1, Just ot2) -> o2 {optionType = Just $ combineOptionType ot1 ot2}+       in -- Any setting's example is a valid example for the key.+          o {optionExample = optionExample o2 <|> optionExample o1}      combineOptionType :: OptionType -> OptionType -> OptionType     combineOptionType ot1 ot2 = simplifyOptionType $ case (ot1, ot2) of
src/OptEnvConf/Parser.hs view
@@ -902,6 +902,7 @@             settingConfigVals = Nothing,             settingDefaultValue = Nothing,             settingExamples = [],+            settingValueExamples = [],             settingHidden = True,             settingMetavar = Nothing,             settingHelp = Nothing,@@ -921,6 +922,7 @@             settingConfigVals = Nothing,             settingDefaultValue = Nothing,             settingExamples = [],+            settingValueExamples = [],             settingHidden = True,             settingMetavar = Nothing,             settingHelp = Nothing,@@ -943,6 +945,7 @@               settingConfigVals = Nothing,               settingDefaultValue = Nothing,               settingExamples = [],+              settingValueExamples = [],               settingHidden = False,               settingMetavar = Just "BOOL",               settingHelp = settingHelp s,@@ -964,6 +967,7 @@               settingConfigVals = Just ne,               settingDefaultValue = Nothing,               settingExamples = [],+              settingValueExamples = settingValueExamples s,               settingHidden = False,               settingMetavar = Nothing,               settingHelp = settingHelp s,@@ -983,6 +987,7 @@             settingConfigVals = Nothing,             settingDefaultValue = Nothing,             settingExamples = [],+            settingValueExamples = [],             settingHidden = False,             settingMetavar = Nothing,             settingHelp = settingHelp s,@@ -1011,6 +1016,8 @@  -- | Load a secret from a text file, with 'readSecretTextFile', or specify it -- directly+--+-- It ignores any 'exampleValue'. secretTextFileOrBareSetting :: (HasCallStack) => [Builder FilePath] -> Parser Text secretTextFileOrBareSetting bs =   withFrozenCallStack $@@ -1025,7 +1032,13 @@         ]   where     mLoc = snd <$> listToMaybe (getCallStack callStack)-    b = mconcat $ bs ++ [reader str]+    -- One example value would document a secret for the bare config setting+    -- and a path for the file config setting, so it cannot mean either.+    b = mconcat $ map (mapMaybeBuilder dropValueExample) bs ++ [reader str]+    dropValueExample :: BuildInstruction FilePath -> Maybe (BuildInstruction FilePath)+    dropValueExample = \case+      BuildAddValueExample _ -> Nothing+      i -> Just i     bareSetting p f = do       let s = completeBuilder $ mconcat [mapMaybeBuilder f b, reader str, metavar "SECRET"]       guard $ p s
src/OptEnvConf/Setting.hs view
@@ -27,14 +27,19 @@     conf,     confWith,     confWith',+    decodeOnlyConfWith,+    decodeOnlyConfWith',     unprefixedConf,     unprefixedConfWith,     unprefixedConfWith',+    unprefixedDecodeOnlyConfWith,+    unprefixedDecodeOnlyConfWith',     name,     value,     valueWithShown,     example,     shownExample,+    exampleValue,     hidden,     completer,     Builder (..),@@ -59,6 +64,7 @@ where  import Autodocodec+import qualified Data.Aeson as JSON import Data.Hashable import Data.List.NonEmpty (NonEmpty (..), (<|)) import qualified Data.List.NonEmpty as NE@@ -102,6 +108,8 @@     settingDefaultValue :: !(Maybe (a, String)),     -- | Example values     settingExamples :: ![String],+    -- | Example values, rendered with the 'configValSettingEncoder's+    settingValueExamples :: ![a],     -- | Whether to hide docs     settingHidden :: !Bool,     -- | Which metavar should be show in documentation@@ -157,7 +165,10 @@   ConfigValSetting   { configValSettingPath :: !(NonEmpty String),     configValSettingAllowPrefix :: !Bool,-    configValSettingCodec :: !(ValueCodec void (Maybe a))+    configValSettingCodec :: !(ValueCodec void (Maybe a)),+    -- | How to render a value as what 'configValSettingCodec' parses, if+    -- that codec can encode.+    configValSettingEncoder :: !(Maybe (a -> JSON.Value))   }  prefixConfigValSetting :: String -> ConfigValSetting a -> ConfigValSetting a@@ -188,6 +199,7 @@       settingMetavar = Nothing,       settingHelp = Nothing,       settingExamples = [],+      settingValueExamples = [],       settingHidden = False,       settingDefaultValue = Nothing,       settingCompleter = Nothing,@@ -197,7 +209,7 @@ -- | Show a 'Setting' as much as possible, for debugging showSettingABit :: Setting a -> ShowS showSettingABit Setting {..} =-  let Setting _ _ _ _ _ _ _ _ _ _ _ _ _ _ = undefined+  let Setting _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ = undefined    in showParen True $         showString "Setting "           . showsPrec 11 settingDasheds@@ -218,6 +230,8 @@           . showString " "           . showsPrec 11 settingExamples           . showString " "+          . showListWith (\_ -> showString "_") settingValueExamples+          . showString " "           . showsPrec 11 settingHidden           . showString " "           . showsPrec 11 settingMetavar@@ -234,6 +248,8 @@     . showsPrec 11 configValSettingPath     . showString " "     . showString (showCodecABit configValSettingCodec)+    . showString " "+    . showMaybeWith (\_ -> showString "_") configValSettingEncoder  showMaybeWith :: (a -> ShowS) -> Maybe a -> ShowS showMaybeWith _ Nothing = showString "Nothing"@@ -262,6 +278,7 @@   | BuildAddConf !(ConfigValSetting a)   | BuildSetDefault !a !String   | BuildAddExample !String+  | BuildAddValueExample !a   | BuildSetHidden   | BuildSetCompleter !Completer   | BuildAddRequiredCapability !Capability@@ -283,6 +300,7 @@   BuildAddConf t -> s {settingConfigVals = Just $ maybe (t :| []) (t <|) $ settingConfigVals s}   BuildSetDefault a shown -> s {settingDefaultValue = Just (a, shown)}   BuildAddExample e -> s {settingExamples = e : settingExamples s}+  BuildAddValueExample a -> s {settingValueExamples = a : settingValueExamples s}   BuildSetHidden -> s {settingHidden = True}   BuildSetCompleter c -> s {settingCompleter = Just c}   BuildAddRequiredCapability c -> s {settingRequiredCapabilities = Set.insert c (settingRequiredCapabilities s)}@@ -385,39 +403,76 @@ conf k = confWith k codec  -- | Like 'conf' but with a custom 'Codec' for parsing the value.-confWith :: String -> ValueCodec void a -> Builder a+--+-- The codec is also used to render the default value and the+-- 'exampleValue's in documentation, so it should parse what it renders back+-- to the same value.+-- A codec mapped with 'fmap' usually does not, because 'fmap' only changes how+-- it parses.+confWith :: String -> JSONCodec a -> Builder a confWith k c = confWith' k (maybeCodec c)  -- | Like 'confWith' but allows interpreting 'Null' as a value other than "Not found".-confWith' :: String -> ValueCodec void (Maybe a) -> Builder a-confWith' k c =-  let t =-        ConfigValSetting-          { configValSettingPath = k :| [],-            configValSettingAllowPrefix = True,-            configValSettingCodec = c-          }-   in Builder [BuildAddConf t]+confWith' :: String -> JSONCodec (Maybe a) -> Builder a+confWith' = bidirectionalConfigVal True +-- | Like 'confWith' but for a codec that can only parse.+--+-- Prefer 'confWith': the default value and the 'exampleValue's of a setting+-- whose codec cannot encode are not rendered in documentation.+decodeOnlyConfWith :: String -> ValueCodec void a -> Builder a+decodeOnlyConfWith k c = decodeOnlyConfWith' k (maybeCodec c)++-- | Like 'confWith'' but for a codec that can only parse.+--+-- Prefer 'confWith''; see 'decodeOnlyConfWith'.+decodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a+decodeOnlyConfWith' = decodeOnlyConfigVal True+ -- | Like 'conf' but ignores any 'subConf', 'subConf_', or 'subAll'. unprefixedConf :: (HasCodec a) => String -> Builder a unprefixedConf k = unprefixedConfWith k codec  -- | Like 'confWith' but ignores any 'subConf', 'subConf_', or 'subAll'.-unprefixedConfWith :: String -> ValueCodec void a -> Builder a+unprefixedConfWith :: String -> JSONCodec a -> Builder a unprefixedConfWith k c = unprefixedConfWith' k (maybeCodec c)  -- | Like 'confWith'' but ignores any 'subConf', 'subConf_', or 'subAll'.-unprefixedConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a-unprefixedConfWith' k c =-  let t =+unprefixedConfWith' :: String -> JSONCodec (Maybe a) -> Builder a+unprefixedConfWith' = bidirectionalConfigVal False++-- | Like 'decodeOnlyConfWith' but ignores any 'subConf', 'subConf_', or 'subAll'.+unprefixedDecodeOnlyConfWith :: String -> ValueCodec void a -> Builder a+unprefixedDecodeOnlyConfWith k c = unprefixedDecodeOnlyConfWith' k (maybeCodec c)++-- | Like 'decodeOnlyConfWith'' but ignores any 'subConf', 'subConf_', or 'subAll'.+unprefixedDecodeOnlyConfWith' :: String -> ValueCodec void (Maybe a) -> Builder a+unprefixedDecodeOnlyConfWith' = decodeOnlyConfigVal False++bidirectionalConfigVal :: Bool -> String -> JSONCodec (Maybe a) -> Builder a+bidirectionalConfigVal allowPrefix k c =+  Builder+    [ BuildAddConf         ConfigValSetting           { configValSettingPath = k :| [],-            configValSettingAllowPrefix = False,-            configValSettingCodec = c+            configValSettingAllowPrefix = allowPrefix,+            configValSettingCodec = c,+            configValSettingEncoder = Just (toJSONVia c . Just)           }-   in Builder [BuildAddConf t]+    ] +decodeOnlyConfigVal :: Bool -> String -> ValueCodec void (Maybe a) -> Builder a+decodeOnlyConfigVal allowPrefix k c =+  Builder+    [ BuildAddConf+        ConfigValSetting+          { configValSettingPath = k :| [],+            configValSettingAllowPrefix = allowPrefix,+            configValSettingCodec = c,+            configValSettingEncoder = Nothing+          }+    ]+ -- | Short-hand function for 'option', 'long', 'env', and 'conf' at the same time. -- -- Multiple 'name's will be tried in order.@@ -456,6 +511,15 @@ -- This only makes sense if you use 'reader' 'auto'. shownExample :: (Show a) => a -> Builder a shownExample = example . show++-- | Provide an example value for the generated Nix option type.+--+-- It is rendered with the codec of each 'conf', so it is not rendered for a+-- 'decodeOnlyConfWith'.+-- Only the first 'exampleValue' is rendered, because a Nix option has one+-- example.+exampleValue :: a -> Builder a+exampleValue a = Builder [BuildAddValueExample a]  -- | Don't show this setting in documentation --