Options.Harg

Summary

harg is a wrapper around optparse-applicative that allows blending command-line configuration with environment variables, defaults as well as other sources such as JSON or YAML files. Here are some very simple examples:

• Flat configuration type

  data Config
    = Config
        { host :: String
        , port :: Int
        , log  :: Bool
        , dir  :: Maybe String
        }

  -- Using HKD from higgledy
  configOpt :: HKD Config Opt
  configOpt
    = build @Config hostOpt portOpt logOpt dirOpt
    where
      hostOpt
        = optionWith strParser
            ( optLong "host"
            . optShort 'h'
            . optHelp "Hostname"
            . optEnvVar "HOST_NAME"
            )
      portOpt
        = optionWith readParser
            ( optLong "port"
            . optShort 'p'
            . optHelp "Port number"
            . optDefault 5432
            )
      logOpt
        = switchWith
            ( optLong "log"
            . optHelp "Whether to log or not"
            )
      dirOpt
        = argumentWith strParser
            ( optHelp "Some directory"
            . optEnvVar "SOME_DIR"
            . optOptional
            )

  main :: IO Config
  main = do
    result <- execOpt defaultSources configOpt
    pure $ runIdentity (construct result)

The above could also be:

  type ConfigOpt
    =  Single String
    :* Single Int
    :* Single Bool
    :* Single String

  configOpt :: ConfigOpt Opt
  configOpt
    = hostOpt :* portOpt :* logOpt :* dirOpt
    where
      ...

  main :: IO Config
  main = do
    host :* port :* log :* dir <- execOpt defaultSources configOpt
    pure
      $ runIdentity
      $ Config
      <$> getSingle host
      <*> getSingle port
      <*> getSingle log
      <*> getSingle dir

• Nested configuration type

  data Config
    = Config
        { dbConfig :: DbConfig
        , serverConfig :: ServerConfig
        }

  data DbConfig
    = DbConfig
        { dbHost :: String
        , dbPort :: Int
        }

  data ServerConfig
    = ServerConfig
        { srvPort :: Int
        , srvLog  :: Bool
        }

  type ConfigOpt
    =  HKD DbConfig
    :* HKD ServerConfig

  configOpt :: ConfigOpt Opt
  configOpt
    = dbOpt :* srvOpt
    where
      dbOpt = build DbConfig ...
      srvOpt = build ServerConfig ...

  main :: IO Config
  main = do
    db :* srv <- execOpt defaultSources configOpt
    pure
      $ runIdentity
      $ Config
      <$> construct db
      <*> construct srv

• Subparsers

  data OneConfig = OneConfig ...
  data OtherConfig = OtherConfig ...

  data Config
    =  "one" :-> OneConfig
    :+ "other" :-> OtherConfig

  configOpt :: Config Opt
  configOpt
    = oneOpt :+ otherOpt :+ ANil
    where
      oneOpt = ...
      otherOpt = ...

  main :: IO ()
  main = do
    result <- execOpt defaultSources configOpt
    case result of
      HereF one            -> runWithOne one
      ThereF (HereF other) -> runWithOther other
    where
      runWithOne :: One -> IO ()
      runWithOne = ...
      runWithOther :: Other -> IO ()
      runWithOther = ...

TODO: more (and better) examples

Option declaration

option :: OptReader a -> OptionOpt '[] a

Create an option parser, equivalent to option. The result can then be used with toOpt to convert into the global Opt type.

  someOption :: Opt Int
  someOption
    = toOpt ( option readParser
            & optLong "someopt"
            & optHelp "Some option"
            & optDefault 256
            )

optionWith :: OptReader a -> (OptionOpt '[] a -> OptionOpt attr b) -> Opt b

Similar to option, but accepts a modifier function and returns an Opt directly.

  someOption :: Opt Int
  someOption
    = optionWith readParser
        ( optLong "someopt"
        . optHelp "Some option"
        . optDefault 256
        )

flag

Arguments

:: a

Default value

-> a

Active value

-> FlagOpt '[] a

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 result can then be used with toOpt to convert into the global Opt type.

  someFlag :: Opt Int
  someFlag
    = toOpt ( flag 0 1
            & optLong "someflag"
            & optHelp "Some flag"
            )

flagWith

Arguments

:: a

Default value

-> a

Active value

-> (FlagOpt '[] a -> FlagOpt attr b)

-> Opt b

Similar to flag, but accepts a modifier function and returns an Opt directly.

  someFlag :: Opt Int
  someFlag
    = flagWith 0 1
        ( optLong "someflag"
        . optHelp "Some flag"
        )

switch :: FlagOpt '[] Bool

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
    = toOpt ( switch
            & optLong "someswitch"
            & optHelp "Some switch"
            )

switchWith :: (FlagOpt '[] Bool -> FlagOpt attr Bool) -> Opt Bool

Similar to switch, but accepts a modifier function and returns an Opt directly.

  someSwitch :: Opt Bool
  someSwitch
    = switchWith
        ( optLong "someswitch"
        . optHelp "Some switch"
        )

switch' :: FlagOpt '[] Bool

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

switchWith' :: (FlagOpt '[] Bool -> FlagOpt attr Bool) -> Opt Bool

Similar to switch', but accepts a modifier function and returns an Opt directly.

argument :: OptReader a -> ArgumentOpt '[] a

Create an argument parser, equivalent to argument. The result can then be used with toOpt to convert into the global Opt type.

  someArgument :: Opt String
  someArgument
    = toOpt ( argument strParser
            & optHelp "Some argument"
            & optDefault "this is the default"
            )

argumentWith :: OptReader a -> (ArgumentOpt '[] a -> ArgumentOpt attr b) -> Opt b

Similar to argument, but accepts a modifier function and returns an Opt directly.

  someArgument :: Opt Int
  someArgument
    = argumentWith
        ( optHelp "Some argument"
        . optDefault "this is the default"
        )

newtype Single (a :: Type) (f :: Type -> Type)

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
      ...

Constructors

Single

Fields

• getSingle :: f a

Instances

ProductB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

bprod :: Single a f -> Single a g -> Single a (Product f g)

buniq :: (forall (a0 :: k). f a0) -> Single a f

TraversableB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

btraverse :: Applicative t => (forall (a0 :: k). f a0 -> t (g a0)) -> Single a f -> t (Single a g)

FunctorB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> Single a f -> Single a g

(Show a, Show (f a)) => Show (Single a f)

Defined in Options.Harg.Single

Methods

showsPrec :: Int -> Single a f -> ShowS

show :: Single a f -> String

showList :: [Single a f] -> ShowS

Generic (f a) => Generic (Single a f)

Defined in Options.Harg.Single

Associated Types

type Rep (Single a f) :: Type -> Type

Methods

from :: Single a f -> Rep (Single a f) x

to :: Rep (Single a f) x -> Single a f

FromJSON (f a) => FromJSON (Single a f)

Defined in Options.Harg.Single

Methods

parseJSON :: Value -> Parser (Single a f)

parseJSONList :: Value -> Parser [Single a f]

type Rep (Single a f)

Defined in Options.Harg.Single

type Rep (Single a f) = Rep (f a)

single :: f a -> Single a f

Wrap a value into a Single.

newtype Nested (b :: Type) (f :: Type -> Type)

Newtype wrapper around HKD.

Constructors

Nested (HKD b f)

Instances

ProductB (HKD b) => ProductB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

bprod :: Nested b f -> Nested b g -> Nested b (Product f g)

buniq :: (forall (a :: k). f a) -> Nested b f

TraversableB (HKD b) => TraversableB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> Nested b f -> t (Nested b g)

FunctorB (HKD b) => FunctorB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

bmap :: (forall (a :: k). f a -> g a) -> Nested b f -> Nested b g

Generic (HKD b f) => Generic (Nested b f)

Defined in Options.Harg.Nested

Associated Types

type Rep (Nested b f) :: Type -> Type

Methods

from :: Nested b f -> Rep (Nested b f) x

to :: Rep (Nested b f) x -> Nested b f

FromJSON (HKD b f) => FromJSON (Nested b f)

Defined in Options.Harg.Nested

Methods

parseJSON :: Value -> Parser (Nested b f)

parseJSONList :: Value -> Parser [Nested b f]

type Rep (Nested b f)

Defined in Options.Harg.Nested

type Rep (Nested b f) = Rep (HKD b f)

nested :: forall b f k. (Build b f k, Coercible (HKD b f) (Nested b f), Coercible k (Nest k f)) => Nest k f

See documentation for build

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

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

getNested :: Construct f b => Nested b f -> f b

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)

data AssocListF (ts :: [Symbol]) (xs :: [(Type -> Type) -> Type]) (f :: Type -> Type) where

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.

Constructors

ANil :: AssocListF '[] '[] f

ACons :: x f -> AssocListF ts xs f -> AssocListF (t ': ts) (x ': xs) f

type family l :+ r = (res :: (Type -> Type) -> Type) where ... infixr 4

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.

Equations

(tl :-> vl) :+ (tr :-> vr) = AssocListF '[tl, tr] '[vl, vr]

(tl :-> vl) :+ (AssocListF ts vs) = AssocListF (tl ': ts) (vl ': vs)

l :+ r = TypeError (((Text "Invalid type for tagged options. Construct like this:" :$$: Text "type MyConfig") :$$: Text " = \"one\" :-> ConfigForOne") :$$: Text " :+ \"two\" :-> ConfigForTwo")

pattern (:+) :: x f -> AssocListF ts xs f -> AssocListF (t ': ts) (x ': xs) f infixr 4

data (t :: Symbol) :-> (v :: (Type -> Type) -> Type) :: (Type -> Type) -> Type infixr 5

data ((a :: (Type -> Type) -> Type) :* (b :: (Type -> Type) -> Type)) (f :: Type -> Type) infixr 4

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 = ...

Constructors

(a f) :* (b f) infixr 4

Instances

(ProductB a, ProductB b) => ProductB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bprod :: (a :* b) f -> (a :* b) g -> (a :* b) (Product f g)

buniq :: (forall (a0 :: k). f a0) -> (a :* b) f

(TraversableB a, TraversableB b) => TraversableB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

btraverse :: Applicative t => (forall (a0 :: k). f a0 -> t (g a0)) -> (a :* b) f -> t ((a :* b) g)

(FunctorB a, FunctorB b) => FunctorB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> (a :* b) f -> (a :* b) g

(Show (a Identity), Show (b Identity)) => Show ((a :* b) Identity)

Defined in Options.Harg.Het.Prod

Methods

showsPrec :: Int -> (a :* b) Identity -> ShowS

show :: (a :* b) Identity -> String

showList :: [(a :* b) Identity] -> ShowS

Generic ((a :* b) f)

Defined in Options.Harg.Het.Prod

Associated Types

type Rep ((a :* b) f) :: Type -> Type

Methods

from :: (a :* b) f -> Rep ((a :* b) f) x

to :: Rep ((a :* b) f) x -> (a :* b) f

(FromJSON (a Maybe), FromJSON (b Maybe), ProductB a, ProductB b, KnownSymbol ta, KnownSymbol tb) => FromJSON ((Tagged ta a :* Tagged tb b) Maybe)

Defined in Options.Harg.Het.Prod

Methods

parseJSON :: Value -> Parser ((Tagged ta a :* Tagged tb b) Maybe)

parseJSONList :: Value -> Parser [(Tagged ta a :* Tagged tb b) Maybe]

(FromJSON (a Maybe), FromJSON (b' Maybe), ProductB a, ProductB b', KnownSymbol ta, b' ~ (Tagged tb b :* c)) => FromJSON ((Tagged ta a :* (Tagged tb b :* c)) Maybe)

Defined in Options.Harg.Het.Prod

Methods

parseJSON :: Value -> Parser ((Tagged ta a :* (Tagged tb b :* c)) Maybe)

parseJSONList :: Value -> Parser [(Tagged ta a :* (Tagged tb b :* c)) Maybe]

type Rep ((a :* b) f)

Defined in Options.Harg.Het.Prod

type Rep ((a :* b) f) = D1 (MetaData ":*" "Options.Harg.Het.Prod" "harg-0.1.0.0-CWc90gQ80Z92IUrOjmdtgz" False) (C1 (MetaCons ":*" (InfixI RightAssociative 4) False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (a f)) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (b f))))

newtype Tagged (t :: k) (a :: (Type -> Type) -> Type) (f :: Type -> Type)

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

Constructors

Tagged

Fields

• unTagged :: a f

Instances

ProductB a => ProductB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bprod :: Tagged t a f -> Tagged t a g -> Tagged t a (Product f g)

buniq :: (forall (a0 :: k). f a0) -> Tagged t a f

TraversableB a => TraversableB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

btraverse :: Applicative t0 => (forall (a0 :: k). f a0 -> t0 (g a0)) -> Tagged t a f -> t0 (Tagged t a g)

FunctorB a => FunctorB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> Tagged t a f -> Tagged t a g

(FromJSON (a Maybe), FromJSON (b Maybe), ProductB a, ProductB b, KnownSymbol ta, KnownSymbol tb) => FromJSON ((Tagged ta a :* Tagged tb b) Maybe)

Defined in Options.Harg.Het.Prod

Methods

parseJSON :: Value -> Parser ((Tagged ta a :* Tagged tb b) Maybe)

parseJSONList :: Value -> Parser [(Tagged ta a :* Tagged tb b) Maybe]

(FromJSON (a Maybe), FromJSON (b' Maybe), ProductB a, ProductB b', KnownSymbol ta, b' ~ (Tagged tb b :* c)) => FromJSON ((Tagged ta a :* (Tagged tb b :* c)) Maybe)

Defined in Options.Harg.Het.Prod

Methods

parseJSON :: Value -> Parser ((Tagged ta a :* (Tagged tb b :* c)) Maybe)

parseJSONList :: Value -> Parser [(Tagged ta a :* (Tagged tb b :* c)) Maybe]

Generic (Tagged t a f)

Defined in Options.Harg.Het.Prod

Associated Types

type Rep (Tagged t a f) :: Type -> Type

Methods

from :: Tagged t a f -> Rep (Tagged t a f) x

to :: Rep (Tagged t a f) x -> Tagged t a f

FromJSON (a f) => FromJSON (Tagged t a f)

Defined in Options.Harg.Het.Prod

Methods

parseJSON :: Value -> Parser (Tagged t a f)

parseJSONList :: Value -> Parser [Tagged t a f]

type Rep (Tagged t a f)

Defined in Options.Harg.Het.Prod

type Rep (Tagged t a f) = D1 (MetaData "Tagged" "Options.Harg.Het.Prod" "harg-0.1.0.0-CWc90gQ80Z92IUrOjmdtgz" True) (C1 (MetaCons "Tagged" PrefixI True) (S1 (MetaSel (Just "unTagged") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (a f))))

Option modifiers

optLong :: HasLong o attr => String -> o attr a -> o attr a

Add a long modifier to an option

optShort :: HasShort o attr => Char -> o attr a -> o attr a

Add a short modifier to an option

optHelp :: HasHelp o attr => String -> o attr a -> o attr a

Add help to an option

optMetavar :: HasMetavar o attr => String -> o attr a -> o attr a

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

optEnvVar :: HasEnvVar o attr => String -> o attr a -> o attr a

Specify an environment variable to lookup for an option

optDefault :: (HasDefault o attr, NotInAttrs OptOptional attr "optDefault" "optOptional") => a -> o attr a -> o (OptDefault ': attr) a

Add a default value to an option. Cannot be used in conjuction with optOptional.

optOptional :: (HasOptional o attr, NotInAttrs OptDefault attr "optOptional" "optDefault") => o attr a -> o (OptOptional ': attr) (Maybe a)

Specify that an option is optional. This will convert an Opt a to an Opt (Maybe a)

toOpt :: IsOpt o attr => o attr a -> Opt a

Convert an intermediate option to an Opt

data Opt a

The basic option type

Instances

Functor Opt

Defined in Options.Harg.Types

Methods

fmap :: (a -> b) -> Opt a -> Opt b

(<$) :: a -> Opt b -> Opt a

Option parsers

parseWith

Arguments

:: (String -> Maybe a)

Original parser

-> String

Input

-> Either String a

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

readParser :: Read a => OptReader a

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

strParser :: IsString s => String -> Either String s

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

boolParser :: String -> Either String Bool

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

Executing options

execOpt

Arguments

:: (TraversableB a, ProductB a, TraversableB c, ProductB c, GetSource c Identity, RunSource (SourceVal c) a)

=> c Opt

Source options

-> a Opt

Target configuration options

-> IO (a Identity)

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

execOptDef

Arguments

:: (TraversableB a, ProductB a)

=> a Opt

Target configuration options

-> IO (a Identity)

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

execCommands

Arguments

:: (TraversableB (VariantF xs), TraversableB c, ProductB c, Subcommands ts xs, GetSource c Identity, All (RunSource (SourceVal c)) xs, All (RunSource ()) xs, MapAssocList xs)

=> c Opt

Source options

-> AssocListF ts xs Opt

Target options associated with subcommands

-> IO (VariantF xs Identity)

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

execCommandsDef

Arguments

:: (TraversableB (VariantF xs), Subcommands ts xs, All (RunSource EnvSourceVal) xs, All (RunSource ()) xs, MapAssocList xs)

=> AssocListF ts xs Opt

Target options associated with subcommands

-> IO (VariantF xs Identity)

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

Option sources

data EnvSource (f :: Type -> Type)

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

Constructors

EnvSource

Instances

Generic (EnvSource f)

Defined in Options.Harg.Sources.Env

Associated Types

type Rep (EnvSource f) :: Type -> Type

Methods

from :: EnvSource f -> Rep (EnvSource f) x

to :: Rep (EnvSource f) x -> EnvSource f

ProductB EnvSource

Defined in Options.Harg.Sources.Env

Methods

bprod :: EnvSource f -> EnvSource g -> EnvSource (Product f g)

buniq :: (forall (a :: k). f a) -> EnvSource f

TraversableB EnvSource

Defined in Options.Harg.Sources.Env

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> EnvSource f -> t (EnvSource g)

FunctorB EnvSource

Defined in Options.Harg.Sources.Env

Methods

bmap :: (forall (a :: k). f a -> g a) -> EnvSource f -> EnvSource g

type Rep (EnvSource f)

Defined in Options.Harg.Sources.Env

type Rep (EnvSource f) = D1 (MetaData "EnvSource" "Options.Harg.Sources.Env" "harg-0.1.0.0-CWc90gQ80Z92IUrOjmdtgz" False) (C1 (MetaCons "EnvSource" PrefixI False) (U1 :: Type -> Type))

newtype JSONSource f

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

Constructors

JSONSource (f ConfigFile)

Instances

Generic (JSONSource f)

Defined in Options.Harg.Sources.JSON

Associated Types

type Rep (JSONSource f) :: Type -> Type

Methods

from :: JSONSource f -> Rep (JSONSource f) x

to :: Rep (JSONSource f) x -> JSONSource f

ProductB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

bprod :: JSONSource f -> JSONSource g -> JSONSource (Product f g)

buniq :: (forall (a :: k). f a) -> JSONSource f

TraversableB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> JSONSource f -> t (JSONSource g)

FunctorB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

bmap :: (forall (a :: k). f a -> g a) -> JSONSource f -> JSONSource g

type Rep (JSONSource f)

Defined in Options.Harg.Sources.JSON

type Rep (JSONSource f) = D1 (MetaData "JSONSource" "Options.Harg.Sources.JSON" "harg-0.1.0.0-CWc90gQ80Z92IUrOjmdtgz" True) (C1 (MetaCons "JSONSource" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (f ConfigFile))))

newtype YAMLSource f

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

Constructors

YAMLSource (f ConfigFile)

Instances

Generic (YAMLSource f)

Defined in Options.Harg.Sources.YAML

Associated Types

type Rep (YAMLSource f) :: Type -> Type

Methods

from :: YAMLSource f -> Rep (YAMLSource f) x

to :: Rep (YAMLSource f) x -> YAMLSource f

ProductB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

bprod :: YAMLSource f -> YAMLSource g -> YAMLSource (Product f g)

buniq :: (forall (a :: k). f a) -> YAMLSource f

TraversableB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> YAMLSource f -> t (YAMLSource g)

FunctorB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

bmap :: (forall (a :: k). f a -> g a) -> YAMLSource f -> YAMLSource g

type Rep (YAMLSource f)

Defined in Options.Harg.Sources.YAML

type Rep (YAMLSource f) = D1 (MetaData "YAMLSource" "Options.Harg.Sources.YAML" "harg-0.1.0.0-CWc90gQ80Z92IUrOjmdtgz" True) (C1 (MetaCons "YAMLSource" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (f ConfigFile))))

data ConfigFile

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
            ( optLong "json-config"
            . optDefault (ConfigFile "~/config.json")
            )

And an optional JSON source:

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

Constructors

ConfigFile FilePath

NoConfigFile

Instances

IsString ConfigFile

Defined in Options.Harg.Sources.Types

Methods

fromString :: String -> ConfigFile

noSources :: NoSource f

Shorthand for writing NoSource.

defaultSources :: EnvSource f

Default sources, equivalent to EnvSource

Parser context

getCtx :: IO HargCtx

ctxFromArgs :: Args -> IO HargCtx

ctxFromEnv :: Environment -> IO HargCtx

pureCtx :: Environment -> Args -> HargCtx

Variant

data VariantF (xs :: [(Type -> Type) -> Type]) (f :: Type -> Type) where

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

Constructors

HereF :: x f -> VariantF (x ': xs) f

ThereF :: VariantF xs f -> VariantF (y ': xs) f

Instances

(TraversableB x, TraversableB (VariantF xs)) => TraversableB (VariantF (x ': xs) :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Variant

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> VariantF (x ': xs) f -> t (VariantF (x ': xs) g)

TraversableB (VariantF ([] :: [(Type -> Type) -> Type]))

Defined in Options.Harg.Het.Variant

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> VariantF [] f -> t (VariantF [] g)

(FunctorB x, FunctorB (VariantF xs)) => FunctorB (VariantF (x ': xs) :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Variant

Methods

bmap :: (forall (a :: k). f a -> g a) -> VariantF (x ': xs) f -> VariantF (x ': xs) g

FunctorB (VariantF ([] :: [(Type -> Type) -> Type]))

Defined in Options.Harg.Het.Variant

Methods

bmap :: (forall (a :: k). f a -> g a) -> VariantF [] f -> VariantF [] g

fromVariantF :: FromVariantF xs result f => VariantF xs f -> FoldSignatureF xs result f

pattern In1 :: x1 f -> VariantF (x1 ': xs) f

pattern In2 :: x2 f -> VariantF (x1 ': (x2 ': xs)) f

pattern In3 :: x3 f -> VariantF (x1 ': (x2 ': (x3 ': xs))) f

pattern In4 :: x4 f -> VariantF (x1 ': (x2 ': (x3 ': (x4 ': xs)))) f

pattern In5 :: x5 f -> VariantF (x1 ': (x2 ': (x3 ': (x4 ': (x5 ': xs))))) f

Re-exports

class FunctorB (b :: (k -> Type) -> Type)

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.

Instances

GFunctorB (Rep structure) => FunctorB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

bmap :: (forall (a :: k). f a -> g a) -> HKD structure f -> HKD structure g

(FunctorB x, FunctorB (VariantF xs)) => FunctorB (VariantF (x ': xs) :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Variant

Methods

bmap :: (forall (a :: k). f a -> g a) -> VariantF (x ': xs) f -> VariantF (x ': xs) g

FunctorB (VariantF ([] :: [(Type -> Type) -> Type]))

Defined in Options.Harg.Het.Variant

Methods

bmap :: (forall (a :: k). f a -> g a) -> VariantF [] f -> VariantF [] g

FunctorB (HKD b) => FunctorB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

bmap :: (forall (a :: k). f a -> g a) -> Nested b f -> Nested b g

FunctorB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> Single a f -> Single a g

FunctorB (Void :: (k -> Type) -> Type)

Defined in Data.Barbie.Trivial

Methods

bmap :: (forall (a :: k0). f a -> g a) -> Void f -> Void g

FunctorB (Unit :: (k -> Type) -> Type)

Defined in Data.Barbie.Trivial

Methods

bmap :: (forall (a :: k0). f a -> g a) -> Unit f -> Unit g

FunctorB (Proxy :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Functor

Methods

bmap :: (forall (a :: k0). f a -> g a) -> Proxy f -> Proxy g

FunctorB b => FunctorB (Barbie b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Instances

Methods

bmap :: (forall (a :: k0). f a -> g a) -> Barbie b f -> Barbie b g

FunctorB (Const x :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Functor

Methods

bmap :: (forall (a :: k0). f a -> g a) -> Const x f -> Const x g

FunctorB a => FunctorB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> Tagged t a f -> Tagged t a g

(FunctorB a, FunctorB b) => FunctorB (Sum a b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Functor

Methods

bmap :: (forall (a0 :: k0). f a0 -> g a0) -> Sum a b f -> Sum a b g

(FunctorB a, FunctorB b) => FunctorB (Product a b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Functor

Methods

bmap :: (forall (a0 :: k0). f a0 -> g a0) -> Product a b f -> Product a b g

(Functor f, FunctorB b) => FunctorB (Compose f b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Functor

Methods

bmap :: (forall (a :: k0). f0 a -> g a) -> Compose f b f0 -> Compose f b g

FunctorB EnvSource

Defined in Options.Harg.Sources.Env

Methods

bmap :: (forall (a :: k). f a -> g a) -> EnvSource f -> EnvSource g

FunctorB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

bmap :: (forall (a :: k). f a -> g a) -> YAMLSource f -> YAMLSource g

FunctorB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

bmap :: (forall (a :: k). f a -> g a) -> JSONSource f -> JSONSource g

(FunctorB a, FunctorB b) => FunctorB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bmap :: (forall (a0 :: k). f a0 -> g a0) -> (a :* b) f -> (a :* b) g

class FunctorB b => TraversableB (b :: (k -> Type) -> Type)

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.

Instances

(FunctorB (HKD structure), GTraversableB (Rep structure)) => TraversableB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> HKD structure f -> t (HKD structure g)

(TraversableB x, TraversableB (VariantF xs)) => TraversableB (VariantF (x ': xs) :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Variant

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> VariantF (x ': xs) f -> t (VariantF (x ': xs) g)

TraversableB (VariantF ([] :: [(Type -> Type) -> Type]))

Defined in Options.Harg.Het.Variant

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> VariantF [] f -> t (VariantF [] g)

TraversableB (HKD b) => TraversableB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> Nested b f -> t (Nested b g)

TraversableB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

btraverse :: Applicative t => (forall (a0 :: k). f a0 -> t (g a0)) -> Single a f -> t (Single a g)

TraversableB (Proxy :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Traversable

Methods

btraverse :: Applicative t => (forall (a :: k0). f a -> t (g a)) -> Proxy f -> t (Proxy g)

TraversableB (Void :: (k -> Type) -> Type)

Defined in Data.Barbie.Trivial

Methods

btraverse :: Applicative t => (forall (a :: k0). f a -> t (g a)) -> Void f -> t (Void g)

TraversableB (Unit :: (k -> Type) -> Type)

Defined in Data.Barbie.Trivial

Methods

btraverse :: Applicative t => (forall (a :: k0). f a -> t (g a)) -> Unit f -> t (Unit g)

TraversableB (Const a :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Traversable

Methods

btraverse :: Applicative t => (forall (a0 :: k0). f a0 -> t (g a0)) -> Const a f -> t (Const a g)

TraversableB b => TraversableB (Barbie b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Instances

Methods

btraverse :: Applicative t => (forall (a :: k0). f a -> t (g a)) -> Barbie b f -> t (Barbie b g)

TraversableB a => TraversableB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

btraverse :: Applicative t0 => (forall (a0 :: k). f a0 -> t0 (g a0)) -> Tagged t a f -> t0 (Tagged t a g)

(TraversableB a, TraversableB b) => TraversableB (Sum a b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Traversable

Methods

btraverse :: Applicative t => (forall (a0 :: k0). f a0 -> t (g a0)) -> Sum a b f -> t (Sum a b g)

(TraversableB a, TraversableB b) => TraversableB (Product a b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Traversable

Methods

btraverse :: Applicative t => (forall (a0 :: k0). f a0 -> t (g a0)) -> Product a b f -> t (Product a b g)

(Traversable f, TraversableB b) => TraversableB (Compose f b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Traversable

Methods

btraverse :: Applicative t => (forall (a :: k0). f0 a -> t (g a)) -> Compose f b f0 -> t (Compose f b g)

TraversableB EnvSource

Defined in Options.Harg.Sources.Env

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> EnvSource f -> t (EnvSource g)

TraversableB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> YAMLSource f -> t (YAMLSource g)

TraversableB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> JSONSource f -> t (JSONSource g)

(TraversableB a, TraversableB b) => TraversableB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

btraverse :: Applicative t => (forall (a0 :: k). f a0 -> t (g a0)) -> (a :* b) f -> t ((a :* b) g)

class FunctorB b => ProductB (b :: (k -> Type) -> Type)

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.

Instances

(FunctorB (HKD structure), GProductB (Rep structure)) => ProductB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

bprod :: HKD structure f -> HKD structure g -> HKD structure (Product f g)

buniq :: (forall (a :: k). f a) -> HKD structure f

ProductB (HKD b) => ProductB (Nested b :: (Type -> Type) -> Type)

Defined in Options.Harg.Nested

Methods

bprod :: Nested b f -> Nested b g -> Nested b (Product f g)

buniq :: (forall (a :: k). f a) -> Nested b f

ProductB (Single a :: (Type -> Type) -> Type)

Defined in Options.Harg.Single

Methods

bprod :: Single a f -> Single a g -> Single a (Product f g)

buniq :: (forall (a0 :: k). f a0) -> Single a f

ProductB (Proxy :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Product

Methods

bprod :: Proxy f -> Proxy g -> Proxy (Product f g)

buniq :: (forall (a :: k0). f a) -> Proxy f

ProductB (Unit :: (k -> Type) -> Type)

Defined in Data.Barbie.Trivial

Methods

bprod :: Unit f -> Unit g -> Unit (Product f g)

buniq :: (forall (a :: k0). f a) -> Unit f

ProductB b => ProductB (Barbie b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Instances

Methods

bprod :: Barbie b f -> Barbie b g -> Barbie b (Product f g)

buniq :: (forall (a :: k0). f a) -> Barbie b f

ProductB a => ProductB (Tagged t a :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bprod :: Tagged t a f -> Tagged t a g -> Tagged t a (Product f g)

buniq :: (forall (a0 :: k). f a0) -> Tagged t a f

(ProductB a, ProductB b) => ProductB (Product a b :: (k -> Type) -> Type)

Defined in Data.Barbie.Internal.Product

Methods

bprod :: Product a b f -> Product a b g -> Product a b (Product f g)

buniq :: (forall (a0 :: k0). f a0) -> Product a b f

ProductB EnvSource

Defined in Options.Harg.Sources.Env

Methods

bprod :: EnvSource f -> EnvSource g -> EnvSource (Product f g)

buniq :: (forall (a :: k). f a) -> EnvSource f

ProductB YAMLSource

Defined in Options.Harg.Sources.YAML

Methods

bprod :: YAMLSource f -> YAMLSource g -> YAMLSource (Product f g)

buniq :: (forall (a :: k). f a) -> YAMLSource f

ProductB JSONSource

Defined in Options.Harg.Sources.JSON

Methods

bprod :: JSONSource f -> JSONSource g -> JSONSource (Product f g)

buniq :: (forall (a :: k). f a) -> JSONSource f

(ProductB a, ProductB b) => ProductB (a :* b :: (Type -> Type) -> Type)

Defined in Options.Harg.Het.Prod

Methods

bprod :: (a :* b) f -> (a :* b) g -> (a :* b) (Product f g)

buniq :: (forall (a0 :: k). f a0) -> (a :* b) f

data HKD structure (f :: Type -> Type)

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) [])
(,) [] []

Instances

GBuild f structure ([] :: [Type]) (HKD structure f)

Defined in Data.Generic.HKD.Build

Methods

gbuild :: (HList [] -> HKD structure f) -> HKD structure f

(ProductB (HKD structure), ConstraintsB (HKD structure), GProductBC (Rep structure)) => ProductBC (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

bdicts :: AllB c (HKD structure) => HKD structure (Dict c)

(FunctorB (HKD structure), GConstraintsB (Rep structure), GAllBC (Rep structure)) => ConstraintsB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Associated Types

type AllB c (HKD structure) :: Constraint

Methods

baddDicts :: AllB c (HKD structure) => HKD structure f -> HKD structure (Product (Dict c) f)

(FunctorB (HKD structure), GProductB (Rep structure)) => ProductB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

bprod :: HKD structure f -> HKD structure g -> HKD structure (Product f g)

buniq :: (forall (a :: k). f a) -> HKD structure f

(FunctorB (HKD structure), GTraversableB (Rep structure)) => TraversableB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

btraverse :: Applicative t => (forall (a :: k). f a -> t (g a)) -> HKD structure f -> t (HKD structure g)

GFunctorB (Rep structure) => FunctorB (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

Methods

bmap :: (forall (a :: k). f a -> g a) -> HKD structure f -> HKD structure g

(Eq tuple, Generic xs, Tuple f xs tuple) => Eq (HKD xs f)

Defined in Data.Generic.HKD.Types

Methods

(==) :: HKD xs f -> HKD xs f -> Bool

(/=) :: HKD xs f -> HKD xs f -> Bool

(Ord tuple, Generic xs, Tuple f xs tuple) => Ord (HKD xs f)

Defined in Data.Generic.HKD.Types

Methods

compare :: HKD xs f -> HKD xs f -> Ordering

(<) :: HKD xs f -> HKD xs f -> Bool

(<=) :: HKD xs f -> HKD xs f -> Bool

(>) :: HKD xs f -> HKD xs f -> Bool

(>=) :: HKD xs f -> HKD xs f -> Bool

max :: HKD xs f -> HKD xs f -> HKD xs f

min :: HKD xs f -> HKD xs f -> HKD xs f

(Generic structure, GShow True (HKD_ f structure)) => Show (HKD structure f)

Defined in Data.Generic.HKD.Types

Methods

showsPrec :: Int -> HKD structure f -> ShowS

show :: HKD structure f -> String

showList :: [HKD structure f] -> ShowS

(Semigroup tuple, Generic xs, Tuple f xs tuple) => Semigroup (HKD xs f)

Defined in Data.Generic.HKD.Types

Methods

(<>) :: HKD xs f -> HKD xs f -> HKD xs f

sconcat :: NonEmpty (HKD xs f) -> HKD xs f

stimes :: Integral b => b -> HKD xs f -> HKD xs f

(Monoid tuple, Generic xs, Tuple f xs tuple) => Monoid (HKD xs f)

Defined in Data.Generic.HKD.Types

Methods

mempty :: HKD xs f

mappend :: HKD xs f -> HKD xs f -> HKD xs f

mconcat :: [HKD xs f] -> HKD xs f

(Generic structure, Function tuple, Tuple f structure tuple) => Function (HKD structure f)

Defined in Data.Generic.HKD.Types

Methods

function :: (HKD structure f -> b) -> HKD structure f :-> b

(Arbitrary tuple, GToTuple (HKD_ f structure) tuple) => Arbitrary (HKD structure f)

Defined in Data.Generic.HKD.Types

Methods

arbitrary :: Gen (HKD structure f)

shrink :: HKD structure f -> [HKD structure f]

(CoArbitrary tuple, GToTuple (HKD_ f structure) tuple) => CoArbitrary (HKD structure f)

Defined in Data.Generic.HKD.Types

Methods

coarbitrary :: HKD structure f -> Gen b -> Gen b

GFromJSON Zero (HKD_ f structure) => FromJSON (HKD structure f)

Defined in Options.Harg.Nested

Methods

parseJSON :: Value -> Parser (HKD structure f)

parseJSONList :: Value -> Parser [HKD structure f]

type AllB (c :: Type -> Constraint) (HKD structure :: (Type -> Type) -> Type)

Defined in Data.Generic.HKD.Types

type AllB (c :: Type -> Constraint) (HKD structure :: (Type -> Type) -> Type) = GAllB c (Rep structure)

build :: Build structure f k => k

construct :: Construct f structure => HKD structure f -> f structure