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 +20/−0
- opt-env-conf.cabal +2/−2
- src/OptEnvConf.hs +5/−0
- src/OptEnvConf/Nix.hs +34/−13
- src/OptEnvConf/Parser.hs +14/−1
- src/OptEnvConf/Setting.hs +83/−19
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 --