# `registry-options`
[](https://hackage.haskell.org/package/registry-options) [](https://github.com/etorreborre/registry-options/actions)
##### *It's functions all the way down* <img src="https://raw.githubusercontent.com/etorreborre/registry-options/main/doc/images/unboxed-bottomup.jpg" border="0"/>
# Presentation
This library is an addition to the [`registry`](https://github.com/etorreborre/registry) library, supporting the parsing of options from the command line, environment variables or configuration files.
# A `copy` command-line parser
Here is a quick example showing how to create a parser for a simple command-line program. We want to be able to parse the following command-line arguments
```
copy -f secrets.txt .hidden
```
T
`copy` is the name of the command, `-f` is a flag, and `secrets.txt`, `.hidden` are arguments.
The purpose of command line parsing is to transform a list of input strings into a meaningful Haskell value:
```haskell
data Copy = Copy {
copyForce :: Bool,
copySource :: File,
copyTarget :: File
}
newtype File = File { _file :: Text }
```
We can then use this Haskell value to drive the execution of a `copy` function.
# Define and use a Parser
In order to make a parser for the `Copy` data type we create a [registry](https://github.com/etorreborre/registry) containing several declarations
```haskell
import Data.Registry
import Data.Registry.Options
let parsers =
$(makeCommand ''Copy [shortDescription "copy a file from SOURCE to TARGET"])
<: argument @"source" @File [metavar "SOURCE", help "Source path"]
<: argument @"target" @File [metavar "TARGET", help "Target path"]
<: switch @"force" [help "Overwrite when a file with the same name already exists"]
<: decoderOf File
<: defaults
```
That registry allows us to make a parser capable of creating a `Copy` value from command-line arguments
```haskell
let copyParser = make @(Parser Command Copy) parsers
parse copyParser "copy -f secrets.txt .hidden" === Right (Copy True "secrets.txt" ".hidden")
```
# Display the help
We can also use the library to display the help of any Parser
```haskell
let copyParser = make @(Parser Command Copy) parsers
putStrLn $ displayHelp (parserHelp copyParser)
```
and the output is
```haskell
copy - copy a file from SOURCE to TARGET
USAGE
copy [-f|--force] [SOURCE] [TARGET]
OPTIONS
-f,--force BOOL Force the action even if a file already exists with the same name
SOURCE Source path
TARGET Target path
```
_Note_: via the use of another registry it is possible to customize any part of the help.
See the documentation and functions in `Data.Registry.Options.DisplayHelpBox` on how to override various sections of the help text.
# Read option values
When we want to effectively run a parser and retrieve values we call the `run` function
```haskell
run @Command @Copy parsers :: IO (Either Text Copy)
```
The `run` function takes the `Copy` parser registry and uses some default sources to access option values.
By default the option values come from 3 different sources with the following priorities:
1. (highest priority) environment variables
2. "command line arguments
3. a YAML configuration file (off by default)
If you want to use a YAML configuration file, you can user the `runWith` function
```haskell
runWith @Command @Copy (setConfigFilePath ".configuration.yaml") parsers
```
# You want to know more?
- fully developed [example][example]: we explain in detail all the declarations above and their role
- [motivations][motivations]: why was this library created? How does it differ from similar libraries?
- [sources][sources]: how to configure and extend sources
[example]: http://github.com/etorreborre/registry-options/blob/main/doc/example.md
[motivations]: http://github.com/etorreborre/registry-options/blob/main/doc/motivations.md
[sources]: http://github.com/etorreborre/registry-options/blob/main/doc/sources.md