opt-env-conf
Settings parsing for Haskell: command-line arguments, environment variables, and configuration values.
https://github.com/NorfairKing/opt-env-conf#readme
| LTS Haskell 24.67: | 0.9.0.0 |
| Stackage Nightly 2026-11-17: | 0.16.0.0 |
| Latest on Hackage: | 0.16.0.0 |
LGPL-3.0-only licensed by Tom Sydney Kerckhove
Maintained by [email protected]
This version can be pinned in stack with:
opt-env-conf-0.16.0.0@sha256:699f672404a3a5ec6f93bce5530950a400f8c5a4eb3f0ee80895bce9fc8395e9,1878Module documentation for 0.16.0.0
- OptEnvConf
- OptEnvConf.Args
- OptEnvConf.Capability
- OptEnvConf.Casing
- OptEnvConf.Check
- OptEnvConf.Completer
- OptEnvConf.Completion
- OptEnvConf.Doc
- OptEnvConf.EnvMap
- OptEnvConf.Error
- OptEnvConf.Lint
- OptEnvConf.Main
- OptEnvConf.Nix
- OptEnvConf.NonDet
- OptEnvConf.Output
- OptEnvConf.Parser
- OptEnvConf.Reader
- OptEnvConf.Run
- OptEnvConf.Setting
- OptEnvConf.Terminal
- OptEnvConf.Validation
Depends on 19 packages(full list with versions):
Used by 1 package in nightly-2026-11-17(full list with versions):
Changes
Changelog
[0.16.0.0] - 2026-11-14
Added
renderSettingsNixOptionType,renderParserNixOptionTypeand theirWithGeneratedCommentvariants.
Changed
- A setting that is not set is left out of the settings’ value instead of
being
null. --render-nix-optionsis now--render-nix-option-type.- The generated type needs nixpkgs 25.11 or newer.
- The Nix option of a setting with a default documents that default.
Removed
renderSettingsNixOptions,renderParserNixOptions, theirWithGeneratedCommentvariants andparserNixOptionExpr.
Fixed
- The generated file comment no longer comments out the first line of the rendered Nix.
[0.15.0.3] - 2026-08-11
Changed
- Path completers now sort the directory listings they complete from. They previously handed back entries in whatever order the filesystem reported them, so the same completion produced different output on different machines.
[0.15.0.2] - 2026-05-15
Changed
- Fixed an exponential-time blowup when parsing inputs with several
many-style options combined with achoicecontaining positional arguments. Parses that previously took minutes now complete in milliseconds. The fix makes the internalListTnondet stream lazy in its second argument and threads inner branches into the outer parser on demand.
[0.15.0.1] - 2026-03-18
Changed
- Fixed autocompletion for paths containing
..components. Paths like../,../foo, andbar/../now complete correctly.
[0.15.0.0] - 2026-03-17
Added
filePathWithExtensionandfilePathWithExtensionscompleters for completing only files with specific extensions.CompletionResultandCompletionFinalitytypes for per-result trailing-space suppression in zsh.
Changed
- Breaking:
Completernow wrapsString -> IO [CompletionResult]instead ofString -> IO [String]. Each result carries aCompletionFinalityindicating whether it is final (e.g. a file — shell appends trailing space) or non-final (e.g. a directory — no trailing space). The zsh completion script uses this signal instead of the*/suffix heuristic. withLocalYamlConfig(viaconfiguredConfigFile) now completes only.yamland.ymlfiles instead of all files.- Fixed
filePathSettinganddirectoryPathSettingso that user-provided builders (e.g.completer,metavar) take precedence over the built-in defaults instead of being silently overridden. - Fixed completion for options next to default commands with arguments.
When a default command’s argument parser speculatively consumed a dashed
option (e.g.
--archive-dir) as a positional value, sibling parsers in the same applicative could no longer see it, suppressing their completers.
[0.14.1.0] - 2026-02-25
Added
renderSettingsNixOptionsWithGeneratedCommentrenderParserNixOptionsWithGeneratedCommentwithGeneratedComment
Changed
- The
--render-nix-optionsCLI output now includes a generated file comment
[0.14.0.0] - 2025-12-03
Changed
- Source location package names are now cleaned up to not contain a hash. This makes it possible to use them in golden tests.
[0.13.0.0] - 2025-11-18
Added
- Capability support for settings.
This is technically a breaking change, but if you don’t use any opt-env-conf
internals, nothing should break for you.
Changed
- Renamed
requireCapabilitytocheckWithRequiredCapability. - Fixed that
showSettingABitdid not show every part of a setting.
[0.12.2.0] - 2025-11-18
Changed
- Fixed a bug in which parse errors would be ignored during checking as soon as one missing capability was encountered.
[0.12.0.0] - 2025-11-15
Added
- Support for capabilities during settings parsing, and disabling them in the settings check.
This is technically a breaking change, but if you don’t use any opt-env-conf
internals, nothing should break for you.
[0.11.1.0] - 2025-10-23
Added
- Windows support by isolating platform-specific terminal code.
[0.11.0.0] - 2025-09-29
This is technically a breaking change, but if you don’t use any opt-env-conf
internals, nothing should break for you.
Changed
ParserManyandParserSomecan now carry source locations. This is not likely to happen often because theAlternativeclass does not have aHasCallStacksuper class, but could still happen when usingsomeNonEmpty.
[0.10.0.0] - 2025-09-17
This is technically a breaking change, but if you don’t use any opt-env-conf
internals, nothing should break for you.
Added
unprefixedEnvunprefixedConf
[0.9.0.0] - 2025-03-12
Added
- Completions
[0.8.0.1] - 2024-12-22
Changed
- Fixed that
secretTextFileOrBareSettingwould not pass the linter withoutname.
[0.8.0.0] - 2024-11-05
Changed
- Change
withShownDefaultandvalueWithShownto accept a function to use in place ofshowrather than a pre-renderedString.
[0.7.0.1] - 2024-10-27
Changed
- Fixed a bug in which
allOrNothing(andsubSettings) could malfunction when using a common library setting multiple times.
[0.7.0.0] - 2024-10-27
Added
- The
allOrNothingerror now shows which settings were defined.
[0.6.0.4] - 2024-10-26
Added
- Added a lint for an unknown default command.
[0.6.0.3] - 2024-10-24
Added
withDefaultandwithShownDefault.
[0.6.0.2] - 2024-10-20
Changed
- Fixed that configuration parsing errors were double-
shown.
[0.6.0.1] - 2024-10-18
Added
secretTextFileSettingsecretTextFileOrBareSetting
[0.6.0.0] - 2024-10-18
Added
defaultCommand
Changed
commandsnow takesCommandsBuilders.
[0.5.1.1] - 2024-08-08
Changed
- Fixed a bug in which a
settingwith only a defaultvaluewas considered invalid.
[0.5.1.0] - 2024-08-08
Removed
- Removed the “undecodable example” lint because it was faulty when example values aren’t Strings.
[0.5.0.1] - 2024-08-04
Changed
- Errors involving commands now show command descriptions.
[0.5.0.0] - 2024-08-03
Changed
- Made
Builders contain a list ofBuildInstructionsso library functions can pattern-match on the builders. yesNoSwitchandenableDisableSwitchnow no longer take a default value, but accept defaultvaluebuilders instead.- Renamed ‘viaCodec’ to ‘viaStringCodec’.
- Clearer lints when using
name. - Clearer lint about loading configuration.
- Default values are now shown at the end but before example values in documentation.
- Proper
[--optional-option-docs]
[0.4.0.5] - 2024-07-28
Added
- Documentation now shows example values and default values.
[0.4.0.4] - 2024-07-28
Added
- Added a lint for examples that none of the configuration codecs can decode.
Changed
- Fixed: linter would ‘catch’ unreadable examples even though a setting would only read a configuration value
[0.4.0.3] - 2024-07-28
Changed
- Support (commands [..] <|> commands [..]) by concat-ing the lists of commands.
- Improved the documentation of parsers that use
some.
[0.4.0.2] - 2024-07-27
Changed
- Fixed a bug in which unrecognised arguments would be parsed exponentially.
- The special
--versioncommand no longer allows any other arguments. - Fixed a bug in which some source locations still showed up even though debug mode was not on.
- Fixed that only one codec for a configuration setting was tried.
[0.4.0.1] - 2024-07-26
Added
- The
viaCodecreader.
[0.4.0.0] - 2024-07-23
Added
- Added a hidden
--render-reference-documentationcommand. - Added a per-command
--helppage.
Changed
- Changed the name of
mkSettingsChecktomakeSettingsCheck.
[0.3.0.0] - 2024-07-19
Changed
- Debug mode now provides much more info about all the settings that were and weren’t parsed, and why.
- Fixed a bug in which arguments that were consumed in a failed branch were not being unconsumed afterwards.
- Nix functions now produce completion as well as man pages.
[0.2.0.0] – 2024-07-18
Changed
- Fixed that the settings check could not be run with arguments.
- Added a lint to check that
longisn’t used withoutoptionorswitch. - Added a lint to check that
manycannot be used with a parser that can succeed without consuming anything.
[0.1.0.0] - 2024-07-16
Changed
xdgYamlConfigFilenow returns aPath Abs Fileinstead of aFilePath.- Fixed a bug in
withFirstYamlConfigandwithCombinedYamlConfigin which the--config-fileoption was required. --run-settings-checknow allows you to define a static settings check.- Parse the combination of optional switches and optional arguments correctly.
- Fail to parse if any arguments are leftover.
[0.0.0.0] - 2024-07-08
First version