Summary

Create an option parser, equivalent to option. The second argument is the modifiers to add to the option, and can be defined by using function composition (.).

  someOption :: Opt Int
  someOption
    = option readParser
        ( long "someopt"
        . help "Some option"
        . defaultVal 256
        )

Create a flag parser, equivalent to option. The first argument is the default value (returned when the flag modifier is absent), and the second is the active value (returned when the flag modifier is present). The second argument is the modifiers to add to the option, and can be defined by using function composition (.).

  someFlag :: Opt Int
  someFlag
    = flag 0 1
        ( long "someflag"
        . help "Some flag"
        )

A flag parser, specialized to Bool. The parser (e.g. when parsing an environment variable) will accept true and false, but case insensitive, rather than using the Read instance for Bool. The default value is False, and the active value is True.

  someSwitch :: Opt Bool
  someSwitch
    = switch
        ( long "someswitch"
        . help "Some switch"
        )

Similar to switch, but the default value is True and the active is False.

Create an argument parser, equivalent to argument. The second argument is the modifiers to add to the option, and can be defined by using function composition (.).

  someArgument :: Opt Int
  someArgument
    = argument
        ( help "Some argument"
        . defaultVal "this is the default"
        )

Single a f is a newtype around f a, which allows mixing non-nested with nested values when creating configuration parsers, using :*.

  data User = User { name :: String, age :: Int }
    deriving Generic

  myConfig :: (Nested User :* Single Int) Opt
  myConfig
    =  nested @User nameOpt ageOpt
    :* single intOpt
    where
      ...

Wrap a value into a Single.

Helper for when f ~ Identity

Newtype wrapper around HKD.

See documentation for build

  data User = User { name :: String, age :: Int }
    deriving Generic

  someNestedValue :: Nested User Maybe
  someNestedValue
    = nested @User (Just Joe) (Just 30)

See documentation for construct

  data User = User { name :: String, age :: Int }
    deriving Generic

  getUserBack :: Maybe User
  getUserBack
    = getNested hkdUser
    where
      hkdUser :: Nested User Maybe
      hkdUser
        = nested @User (Just Joe) (Just 30)

Helper for when f ~ Identity

A heterogeneous list that holds higher-kinded types and the associated type constructor, along with a type level list of Symbols that act as tags for each type.

Helper type-level function to construct an AssocList which is not yet applied to the type constructor that needs to be fully applied.

  type Config
    =  "run" :-> RunConfig
    :+ "test" :-> TestConfig

Config above has type (Type -> Type) -> Type, and requires a type like Opt to be fully applied.

Infix version of Product. Allows to combine higher-kinded types, and keep them partially applied until needed:

  data User = User { name :: String, age :: Int }
    deriving Generic

  type Config = Nested User :* Single Int

  configOpt :: Config Opt
  configOpt = ...

This type adds a type-level phantom tag to a higher-kinded type. Its JSON instance allows using :* with JSONSource.

Add a long modifier to an option

Add a short modifier to an option

Add help to an option

Add a metavar metavar to an option, to be displayed as the meta-parameter next to long/short modifiers

Specify an environment variable to lookup for an option

Add a default value to an option. Cannot be used in conjuction with with required, defaultStr or optional.

Add a default unparsed value to an option. Cannot be used in conjuction with defaultVal, required or optional.

Mark an option as required. Cannot be used in conjunction with optional, defaultVal or requiredStr.

Specify that an option is optional. This will convert an Opt a to an Opt (Maybe a). Cannot be used in conjunction with defaultVal, defaultStr or required.

Convert an intermediate option to an Opt

The basic option type

Convert a parser that returns Maybe to a parser that returns Either, with the default Left value unable to parse: <input>.

A parser that uses the Read instance to parse into a type.

A parser that returns a string. Any type that has an instance of IsString will work, and this parser always succeeds.

A parser that returns a Bool. This will succeed for the strings true and false in a case-insensitive manner.

A parser that can parse many items, returning a list.

Run the option parser and combine with values from the specified sources

Run the option parser only with default sources (environment variables)

Run the subcommand parser and combine with values from the specified sources

Run the subcommand parser only with default sources (environment variables)

Source that enables a parser to read options from environment variables.

Source that enables a parser to read options from a JSON file.

Source that enables a parser to read options from a YAML file.

This type describes configuration files, for use with e.g. the JSON source. The reason to not use FilePath directly is that the user might prefer to do nothing if the option for the config file has not been not provided, and there's no default. Because this type has an IsString instance, it's very easy to define an option. For example, to define a json source with a default value:

  srcOpt :: JSONSource Opt
  srcOpt = JSONSource jsonOpt
    where
      jsonOpt
        = optionWith strParser
            ( long "json-config"
            . defaultVal (ConfigFile "~/config.json")
            )

And an optional JSON source:

  srcOpt :: JSONSource Opt
  srcOpt = JSONSource jsonOpt
    where
      jsonOpt
        = optionWith strParser
            ( long "json-config"
            . defaultVal NoConfigFile
            )

Shorthand for writing NoSource.

Default sources, equivalent to EnvSource

A Variant is similar to nested Eithers. For example, Variant '[Int, Bool, Char] is isomorphic to Either Int (Either Bool Char). VariantF is a variant for higher-kinded types, which means that the type-level list holds types of kind (Type -> Type) -> Type, and the second parameter is the type constructor f :: Type -> Type. To pattern match on a variant, HereF and ThereF can be used:

  getFromVariant :: Variant '[Int, Bool, String] -> Bool
  getFromVariant (ThereF (HereF b)) = b

Barbie-types that can be mapped over. Instances of FunctorB should satisfy the following laws:

  bmap id = id
  bmap f . bmap g = bmap (f . g)

There is a default bmap implementation for Generic types, so instances can derived automatically.

Barbie-types that can be traversed from left to right. Instances should satisfy the following laws:

 t . btraverse f   = btraverse (t . f)  -- naturality
btraverse Identity = Identity           -- identity
btraverse (Compose . fmap g . f) = Compose . fmap (btraverse g) . btraverse f -- composition

There is a default btraverse implementation for Generic types, so instances can derived automatically.

Barbie-types that can form products, subject to the laws:

bmap (\(Pair a _) -> a) . uncurry bprod = fst
bmap (\(Pair _ b) -> b) . uncurry bprod = snd

Notice that because of the laws, having an internal product structure is not enough to have a lawful instance. E.g.

data Ok  f = Ok {o1 :: f String, o2 :: f Int}
data Bad f = Bad{b1 :: f String, hiddenFromArg: Int} -- no lawful instance

Intuitively, the laws for this class require that b hides no structure from its argument f. Because of this, if we are given any:

x :: forall a . f a

then this determines a unique value of type b f, witnessed by the buniq method. For example:

buniq x = Ok {o1 = x, o2 = x}

Formally, buniq should satisfy:

const (buniq x) = bmap (const x)

There is a default implementation of bprod and buniq for Generic types, so instances can derived automatically.

Higher-kinded data (HKD) is the design pattern in which every field in our type is wrapped in some functor f:

  data User f
   = User
       { name :: f String
       , age  :: f Int
       }

Depending on the functor, we can get different behaviours: with Maybe, we get a partial structure; with Validation, we get a piecemeal validator; and so on. The HKD newtype allows us to lift any type into an HKD-style API via its generic representation.

>>> :set -XDeriveGeneric -XTypeApplications
>>> :{
data User
  = User { name :: String, age :: Int }
  deriving Generic
:}

The HKD type is indexed by our choice of functor and the structure we're lifting. In other words, we can define a synonym for our behaviour:

>>> import Data.Monoid (Last (..))
>>> type Partial a = HKD a Last

... and then we're ready to go!

>>> mempty @(Partial User)
User {name = Last {getLast = Nothing}, age = Last {getLast = Nothing}}

>>> mempty @(HKD (Int, Bool) [])
(,) [] []

With many HKD applications, we're working with types like Maybe where it makes sense for us to start with mempty and add values in as we go.

This isn't always the case, however: if all the component parts of our type are gathered using some IO action, we'd like to construct something like HKD MyType IO, and IO a isn't a Monoid for all types a. When this happens, we need to pass in our parameters when we build our structure.

The build function lets us construct our type by passing explicit values for each parameter:

>>> :set -XDeriveGeneric -XTypeApplications

>>> :{
data User
  = User { name :: String, age :: Int, likesDogs :: Bool }
  deriving Generic
:}

>>> :{
test :: _
test = build @User
:}
...
... Found type wildcard ...
... standing for ...f [Char] -> f Int -> f Bool -> HKD User f...
...

Once we call the build function, and indicate the type we want to build, we are free to pick whichever f we like and get to work!

When working with the HKD representation, it is useful to have a way to convert to and from our original type. To do this, we can:

• construct the original type from our HKD representation, and
• deconstruct the original type into our HKD representation.

As an example, we can try (unsuccessfully) to construct an (Int, Bool) tuple from an unpopulated partial structure.

>>> :set -XTypeApplications
>>> import Data.Monoid (Last)

>>> construct (mempty @(HKD (Int, Bool) Last))
Last {getLast = Nothing}

We can also deconstruct a tuple into a partial structure:

>>> deconstruct @[] ("Hello", True)
(,) ["Hello"] [True]

These two methods also satisfy the round-tripping property:

construct (deconstruct x) == [ x :: (Int, Bool, String) ]