diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,14 @@ +## Version 0.9.1 (23 Jul 2014) + +- Documentation tweaks. + +- Added low-level function to handle parse results (pull request \#94). + +- `ParserResult` now has a `Show` instance (see issue \#95). + +- Fixed bugs + * \#93 - Formatting problem for several sub-parsers + ## Version 0.9.0 (23 May 2014) - The option returned by `abortOption` is now visible by default. diff --git a/Options/Applicative/BashCompletion.hs b/Options/Applicative/BashCompletion.hs --- a/Options/Applicative/BashCompletion.hs +++ b/Options/Applicative/BashCompletion.hs @@ -1,3 +1,8 @@ +-- | You don't need to import this module to enable bash completion. +-- +-- See +-- +-- for more information on bash completion. module Options.Applicative.BashCompletion ( bashCompletionParser ) where diff --git a/Options/Applicative/Builder.hs b/Options/Applicative/Builder.hs --- a/Options/Applicative/Builder.hs +++ b/Options/Applicative/Builder.hs @@ -170,7 +170,10 @@ noArgError :: ParseError -> Mod OptionFields a noArgError e = fieldMod $ \p -> p { optNoArgError = e } --- | Specify the metavariable. +-- | Specify a metavariable for the argument. +-- +-- Metavariables have no effect on the actual parser, and only serve to specify +-- the symbolic name for an argument to be displayed in the help text. metavar :: HasMetavar f => String -> Mod f a metavar var = optionMod $ \p -> p { propMetaVar = var } diff --git a/Options/Applicative/Extra.hs b/Options/Applicative/Extra.hs --- a/Options/Applicative/Extra.hs +++ b/Options/Applicative/Extra.hs @@ -10,6 +10,7 @@ customExecParser, customExecParserMaybe, execParserPure, + handleParseResult, ParserFailure(..), ParserResult(..), ParserPrefs(..), @@ -57,18 +58,21 @@ -- | Run a program description with custom preferences. customExecParser :: ParserPrefs -> ParserInfo a -> IO a -customExecParser pprefs pinfo = do - args <- getArgs - case execParserPure pprefs pinfo args of - Success a -> return a - Failure failure -> do +customExecParser pprefs pinfo + = execParserPure pprefs pinfo <$> getArgs + >>= handleParseResult + +-- | Handle `ParserResult`. +handleParseResult :: ParserResult a -> IO a +handleParseResult (Success a) = return a +handleParseResult (Failure failure) = do progn <- getProgName let (msg, exit) = execFailure failure progn case exit of ExitSuccess -> putStrLn msg _ -> hPutStrLn stderr msg exitWith exit - CompletionInvoked compl -> do +handleParseResult (CompletionInvoked compl) = do progn <- getProgName msg <- execCompletion compl progn putStr msg diff --git a/Options/Applicative/Help/Core.hs b/Options/Applicative/Help/Core.hs --- a/Options/Applicative/Help/Core.hs +++ b/Options/Applicative/Help/Core.hs @@ -16,7 +16,7 @@ import Control.Monad (guard) import Data.List (intersperse, sort) import Data.Maybe (maybeToList, catMaybes) -import Data.Monoid (Monoid, mempty, mappend, mconcat) +import Data.Monoid (Monoid, mempty, mappend) import Options.Applicative.Common import Options.Applicative.Types @@ -61,7 +61,7 @@ -- | Generate descriptions for commands. cmdDesc :: Parser a -> Chunk Doc -cmdDesc = mconcat . mapParser desc +cmdDesc = vcatChunks . mapParser desc where desc _ opt = case optMain opt of diff --git a/Options/Applicative/Types.hs b/Options/Applicative/Types.hs --- a/Options/Applicative/Types.hs +++ b/Options/Applicative/Types.hs @@ -236,14 +236,25 @@ newtype CompletionResult = CompletionResult { execCompletion :: String -> IO String } +instance Show CompletionResult where + showsPrec p _ = showParen (p > 10) $ + showString "CompletionResult _" + newtype ParserFailure = ParserFailure { execFailure :: String -> (String, ExitCode) } +instance Show ParserFailure where + showsPrec p (ParserFailure f) + = showParen (p > 10) + $ showString "ParserFailure " + . showsPrec 11 (f "") + -- | Result of 'execParserPure'. data ParserResult a = Success a | Failure ParserFailure | CompletionInvoked CompletionResult + deriving Show type Args = [String] diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ [![Continuous Integration status][status-png]][status] +[Hackage page (downloads and documentation)][hackage] + ## Getting started Here is a simple example of an applicative option parser: @@ -69,6 +71,11 @@ containing a detailed list of options with descriptions. +The specified metavars are used as placeholders for the option arguments, and +can be referred to in the program description. This makes it possible to +explicitly describe the connection between the options and the behaviour of the +program. + Parsers are instances of both `Applicative` and `Alternative`, and work with any generic combinator, like `many` and `some`. For example, to make a option return `Nothing` instead of failing when it's not supplied, you can use the @@ -306,16 +313,18 @@ Modifiers are instances of the `Monoid` typeclass, so they can be combined using the composition function `mappend` (or simply `(<>)`). -See the haddock documentation for `Options.Applicative.Builder` for a full list -of builders and modifiers. +See the [haddock documentation][builder-documentation] for `Options.Applicative.Builder` +for a full list of builders and modifiers. ## Advanced features -* [Bash completion][bash] -* [Arrow interface][arrows] +* [Bash completion] +* [Arrow interface] +* [Disambiguation] - [bash]: https://github.com/pcapriotti/optparse-applicative/wiki/Bash-Completion - [arrows]: https://github.com/pcapriotti/optparse-applicative/wiki/Arrows + [Bash completion]: https://github.com/pcapriotti/optparse-applicative/wiki/Bash-Completion + [Arrow interface]: https://github.com/pcapriotti/optparse-applicative/wiki/Arrows + [Disambiguation]: https://github.com/pcapriotti/optparse-applicative/wiki/Disambiguation ## How it works @@ -332,4 +341,5 @@ [status-png]: https://secure.travis-ci.org/pcapriotti/optparse-applicative.png?branch=master [status]: http://travis-ci.org/pcapriotti/optparse-applicative?branch=master [blog]: http://paolocapriotti.com/blog/2012/04/27/applicative-option-parser/ - [arrows]: http://www.haskell.org/arrows/syntax.html + [builder-documentation]: http://hackage.haskell.org/package/optparse-applicative/docs/Options-Applicative-Builder.html + [hackage]: http://hackage.haskell.org/package/optparse-applicative-0.9.0 diff --git a/optparse-applicative.cabal b/optparse-applicative.cabal --- a/optparse-applicative.cabal +++ b/optparse-applicative.cabal @@ -1,5 +1,5 @@ name: optparse-applicative -version: 0.9.0 +version: 0.9.1 synopsis: Utilities and combinators for parsing command line options description: Here is a simple example of an applicative option parser: diff --git a/tests/Tests.hs b/tests/Tests.hs --- a/tests/Tests.hs +++ b/tests/Tests.hs @@ -403,6 +403,17 @@ let text = head . lines . fst . err $ "test" "Usage: test FOO" @=? text +case_multiple_subparsers :: Assertion +case_multiple_subparsers = do + let p1 = subparser + (command "add" (info (pure ()) + ( progDesc "Add a file to the repository" ))) + p2 = subparser + (command "commit" (info (pure ()) + ( progDesc "Record changes to the repository" ))) + i = info (p1 *> p2 <**> helper) idm + checkHelpText "subparsers" i ["--help"] + --- deriving instance Arbitrary a => Arbitrary (Chunk a)