diff --git a/examples/example.1 b/examples/example.1 --- a/examples/example.1 +++ b/examples/example.1 @@ -9,7 +9,8 @@ .Nm .Bk -words .Op Fl v -.Fl i Ar INPUT +.Op Fl a | Fl b +.Op Fl i Ar INPUT .Op Fl Fl debug .Ar FILE .Op Ar FILE ... @@ -17,6 +18,10 @@ .Sh DESCRIPTION The options are as follows: .Bl -tag -width indent +.It Fl a , Fl Fl apple +Use apples +.It Fl b , Fl Fl banana +Use bananas .It Fl i Ar INPUT .It Fl v , Fl Fl verbose .It Fl Fl debug diff --git a/mdoc.cabal b/mdoc.cabal --- a/mdoc.cabal +++ b/mdoc.cabal @@ -1,6 +1,6 @@ cabal-version: 1.18 name: mdoc -version: 0.4.1.0 +version: 0.4.1.1 license: AGPL-3 license-file: COPYING maintainer: Pat Brisbin diff --git a/src/Mdoc/Data/Positional.hs b/src/Mdoc/Data/Positional.hs --- a/src/Mdoc/Data/Positional.hs +++ b/src/Mdoc/Data/Positional.hs @@ -71,8 +71,6 @@ instance Pretty Positional1 where pretty p = case p.unwrap of - PositionalSwitch f -> case f of - Flag c _ -> pretty c - GNUFlag {} -> pretty $ Flag1 f + PositionalSwitch f -> pretty $ Flag1 f PositionalOption o -> pretty $ Option1 o PositionalArgument a -> pretty a diff --git a/src/Mdoc/Examples/Docker.hs b/src/Mdoc/Examples/Docker.hs --- a/src/Mdoc/Examples/Docker.hs +++ b/src/Mdoc/Examples/Docker.hs @@ -16,18 +16,18 @@ {- FOURMOLU_DISABLE -} dockerOpt :: OptEnvConf.Parser () -dockerOpt = void $ (,,,,,,,,,,,) - <$> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "config", OptEnvConf.metavar "string", OptEnvConf.help "Location of client config files", OptEnvConf.value "~/.docker"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'c', OptEnvConf.long "context", OptEnvConf.metavar "string", OptEnvConf.help "Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with \"docker context use\")"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'D', OptEnvConf.long "debug", OptEnvConf.help "Enable debug mode"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'H', OptEnvConf.long "host", OptEnvConf.metavar "string", OptEnvConf.help "Daemon socket to connect to"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'l', OptEnvConf.long "log-level", OptEnvConf.metavar "string", OptEnvConf.help "Set the logging level (\"debug\", \"info\", \"warn\", \"error\", \"fatal\")", OptEnvConf.value "info"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tls", OptEnvConf.help "Use TLS; implied by --tlsverify"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscacert", OptEnvConf.metavar "string", OptEnvConf.help "Trust certs signed only by this CA", OptEnvConf.value "~/.docker/ca.pem"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscert", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS certificate file", OptEnvConf.value "~/.docker/cert.pem"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlskey", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS key file", OptEnvConf.value "~/.docker/key.pem"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tlsverify", OptEnvConf.help "Use TLS and verify the remote"]) - <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'v', OptEnvConf.long "version", OptEnvConf.help "Print version information and quit"]) +dockerOpt = void $ (,,,,,,,,,,,,) + <$> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "config", OptEnvConf.metavar "string", OptEnvConf.help "Location of client config files", OptEnvConf.value "~/.docker"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'c', OptEnvConf.long "context", OptEnvConf.metavar "string", OptEnvConf.help "Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with \"docker context use\")"]) + <*> OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'D', OptEnvConf.long "debug", OptEnvConf.help "Enable debug mode"] + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'H', OptEnvConf.long "host", OptEnvConf.metavar "string", OptEnvConf.help "Daemon socket to connect to"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.short 'l', OptEnvConf.long "log-level", OptEnvConf.metavar "string", OptEnvConf.help "Set the logging level (\"debug\", \"info\", \"warn\", \"error\", \"fatal\")", OptEnvConf.value "info"]) + <*> OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tls", OptEnvConf.help "Use TLS; implied by --tlsverify"] + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscacert", OptEnvConf.metavar "string", OptEnvConf.help "Trust certs signed only by this CA", OptEnvConf.value "~/.docker/ca.pem"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlscert", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS certificate file", OptEnvConf.value "~/.docker/cert.pem"]) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.option, OptEnvConf.reader (OptEnvConf.str @Text), OptEnvConf.long "tlskey", OptEnvConf.metavar "string", OptEnvConf.help "Path to TLS key file", OptEnvConf.value "~/.docker/key.pem"]) + <*> OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.long "tlsverify", OptEnvConf.help "Use TLS and verify the remote"] + <*> OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.value False, OptEnvConf.short 'v', OptEnvConf.long "version", OptEnvConf.help "Print version information and quit"] <*> OptEnvConf.commands [ OptEnvConf.command "run" "Create and run a new container from an image" runOpt , OptEnvConf.command "exec" "Execute a command in a running container" execOpt diff --git a/src/Mdoc/Examples/OptEnvConf.hs b/src/Mdoc/Examples/OptEnvConf.hs --- a/src/Mdoc/Examples/OptEnvConf.hs +++ b/src/Mdoc/Examples/OptEnvConf.hs @@ -64,14 +64,18 @@ & name "examplerc" "opt-env-conf example config" {- FOURMOLU_DISABLE -} -exampleParser :: OptEnvConf.Parser (Bool, Bool, Text, Text, [Text]) -exampleParser = (,,,,) +exampleParser :: OptEnvConf.Parser () +exampleParser = void $ (,,,,,) <$> OptEnvConf.setting [OptEnvConf.env "DEBUG", OptEnvConf.conf "debug", OptEnvConf.switch True, OptEnvConf.long "debug", OptEnvConf.help "Enable debug", OptEnvConf.value False , OptEnvConf.example "# enable debug" , OptEnvConf.example "debug: true" ] <*> OptEnvConf.setting [OptEnvConf.conf "verbose", OptEnvConf.switch True, OptEnvConf.short 'v', OptEnvConf.long "verbose", OptEnvConf.value False] - <*> OptEnvConf.setting [OptEnvConf.env "INPUT", OptEnvConf.option, OptEnvConf.reader OptEnvConf.str, OptEnvConf.short 'i', OptEnvConf.metavar "INPUT"] - <*> OptEnvConf.setting [OptEnvConf.conf "file", OptEnvConf.argument, OptEnvConf.reader OptEnvConf.str, OptEnvConf.metavar "FILE"] - <*> OptEnvConf.many (OptEnvConf.setting [OptEnvConf.argument, OptEnvConf.reader OptEnvConf.str, OptEnvConf.metavar "FILE"]) + <*> + ( OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.short 'a', OptEnvConf.long "apple", OptEnvConf.value False, OptEnvConf.help "Use apples"] + <|> OptEnvConf.setting [OptEnvConf.switch True, OptEnvConf.short 'b', OptEnvConf.long "banana", OptEnvConf.value False, OptEnvConf.help "Use bananas"] + ) + <*> OptEnvConf.optional (OptEnvConf.setting [OptEnvConf.env "INPUT", OptEnvConf.option, OptEnvConf.reader $ OptEnvConf.str @Text, OptEnvConf.short 'i', OptEnvConf.metavar "INPUT"]) + <*> OptEnvConf.setting [OptEnvConf.conf "file", OptEnvConf.argument, OptEnvConf.reader $ OptEnvConf.str @Text, OptEnvConf.metavar "FILE"] + <*> OptEnvConf.many (OptEnvConf.setting [OptEnvConf.argument, OptEnvConf.reader $ OptEnvConf.str @Text, OptEnvConf.metavar "FILE"]) {- FOURMOLU_ENABLE -} diff --git a/src/OptEnvConf/Mdoc.hs b/src/OptEnvConf/Mdoc.hs --- a/src/OptEnvConf/Mdoc.hs +++ b/src/OptEnvConf/Mdoc.hs @@ -8,6 +8,38 @@ -- Portability : POSIX -- -- See "Mdoc.Examples.OptEnvConf". +-- +-- == Limitations +-- +-- "OptEnvConf" uses an /or Nothing/ pattern for both 'optional' and +-- 'some'/'many' cases (unlike @optparse-applicative@, which introduces +-- 'BindNode' specifically to distinguish the latter case.) +-- +-- This means we cannot tell the difference and have to decide if this should +-- result in processing that option as optional (showing @[x]@), multiple +-- (showing @x ...@), or both (showing @[x ...]@). +-- +-- We cannot get this right, because "OptEnvConf" does not encode the +-- difference. It never includes @...@ in its rendered help or man-pages, so it +-- doesn't need to. +-- +-- Therefore, we code for the following outcomes: +-- +-- +------------+-----------------+------------------+----------+ +-- | Modifier | Positional type | Result | Correct? | +-- +============+=================+==================+==========+ +-- | 'optional' | option | @[option]@ | yes | +-- +------------+-----------------+------------------+----------+ +-- | 'optional' | argument | @[argument ...]@ | no | +-- +------------+-----------------+------------------+----------+ +-- | 'many' | option | @[option]@ | no | +-- +------------+-----------------+------------------+----------+ +-- | 'many' | argument | @argument ...@ | yes | +-- +------------+-----------------+------------------+----------+ +-- +-- Any behavior here is wrong; we do this primarily because a @SYNOPSIS@ with a +-- final @[file ...]@ argument is so common that we would like to render that +-- case in particular correctly. module OptEnvConf.Mdoc ( getPage ) where @@ -105,10 +137,9 @@ pure $ addCommands (zipWith getCommand [1 ..] cdocs) acc AnyDocsAnd ds -> foldM (foldSetDocsM f) acc ds AnyDocsOr [d] -> foldSetDocsM f acc d - -- Optionality represented as "<|> Nothing" - AnyDocsOr [d, AnyDocsSingle Nothing] -> foldSetDocsM fForOr acc d + AnyDocsOr [d, AnyDocsSingle Nothing] -> foldSetDocsM fAsOrNothing acc d AnyDocsOr ds -> do - sub <- foldM (foldSetDocsM fForOr) mempty $ traceShowId ds + sub <- foldM (foldSetDocsM f) mempty ds pure $ addAlternation Optional (getPositionals sub) acc AnyDocsSingle Nothing -> pure acc -- hidden/internal AnyDocsSingle (Just d) -> do @@ -124,14 +155,13 @@ , example = exampleMdoc <$> nonEmpty (setDocExamples d) } where - -- This is crazy wrong but I keep adding shit based on test cases - fForOr i m d = + fAsOrNothing i m d = f i m $ d { optionality = case d.optionality of Required -> Optional o -> o - , multiple = null $ setDocDasheds d.item + , multiple = setDocTryArgument d.item } exampleMdoc :: NonEmpty String -> Mdoc