diff --git a/ChangeLog.md b/ChangeLog.md index e428275..a4b7b7f 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,5 +1,38 @@ # Revision history for butcher +## 2.0.0.0 -- Sept 2020 + +Large internal refactor including some breaking API changes. + +- Add the "Applicative" interface in addition to the existing "Monadic" one. + This is slightly less expressive but conceptually cleaner/safer (and its + implementation is nicer). For best readability you may need `ApplicativeDo`. +- The applicative interface is *NOT* finished and the test-suite does not + cover it. +- Add the `traverseBarbie` construct to elegantly define a parser for a + config data-structure.\ + Introduces a dependency on the `barbies` library. +- Refactor the module structure a bit, and change the API of the central + `runCmdParser` function. It now returns a `PartialParseInfo`. Essentially, + `runCmdParser` is a combination of the previous `runCmdParser` and the + previous `simpleCompletion`. This API design is a curious advantage to + laziness: Returning a complex struct is harmless as fields that the user + does not use won't be evaluated. The downside is that the core function now + looks like a complex beast, but the upside is that there is no need to + expose multiple functions that are supposed to be chained in a certain way + to get all functionality (if desired), and we still _can_ provide simpler + versions that are just projections on the `PartialParseInfo`. +- Remove deprecated functions +- `peekCmdDesc` is now guaranteed to yield the proper full `CmdDesc` value + for the current command or child-command. +- Remove the `mainFromCmdParserWithHelpDesc` function, because it is redundant + given the new semantics of `peekCmdDesc`. +- Stop support for an anti-feature: The implicit merging of multiple + sub-commands definitions with the same name. +- Internal refactor: The monadic interface now uses two-phase setup: First step + is to create a full CommandDesc value, second is running the parser on input + while the CommandDesc is chained along + ## 1.3.3.2 -- June 2020 * Support ghc-8.10 diff --git a/README.md b/README.md index 8042aa3..8fc52f3 100644 --- a/README.md +++ b/README.md @@ -9,19 +9,24 @@ The main differences are: * Provides a pure interface by default -* Exposes an evil monadic interface, which allows for much nicer binding of - command part results to some variable name. +* Exposes two interfaces: One based on `Applicative` and one based on `Monad`. + The monadic one is slightly more expressive, the applicative interface is + conceptually cleaner but currently is less tested. - In `optparse-applicative` you easily lose track of what field you are - modifying after the 5th `<*>` (admittedly, i think -XRecordWildCards - improves on that issue already.) +* The monadic interface must be used as if `ApplicativeDo` was enabled, + but does not actually require `ApplicativeDo`. This is implemented via + some evil hackery, but nonetheless useful. - Evil, because you are not allowed to use the monad's full power in this - case, i.e. there is a constraint that is not statically enforced. - See below. +* It is not necessary to define data-structure for diffenent child-commands. + In general this is geared towards keeping names and definitions/parsers + of flags/parameters/child-commands connected, while the default + `MyFlags <$> someParser <*> … <*> … <*> … <*> … <*> …` is harder to read + and prone to accidental swapping. -* The monadic interface allows much clearer definitions of commandparses - with (nested) subcommands. No pesky sum-types are necessary. +* Supports connecting to "barbies" + (see the [`barbies`](https://hackage.haskell.org/package/barbies) package). + This allows re-using data-structure definitions for the parser and config + values without losing track of field order. ## Examples @@ -34,7 +39,9 @@ main = mainFromCmdParser $ addCmdImpl $ putStrLn "Hello, World!" But lets look at a more feature-complete example: ~~~~.hs -main = mainFromCmdParserWithHelpDesc $ \helpDesc -> do +main = mainFromCmdParser $ do + + helpDesc <- peekCmdDesc addCmdSynopsis "a simple butcher example program" addCmdHelpStr "a very long help document" @@ -44,14 +51,14 @@ main = mainFromCmdParserWithHelpDesc $ \helpDesc -> do (flagHelpStr "print nothing but the numeric version") addCmdHelpStr "prints the version of this program" addCmdImpl $ putStrLn $ if porcelain - then "0.0.0.999" - else "example, version 0.0.0.999" + then "1.0" + else "example, version 1.0" addCmd "help" $ addCmdImpl $ print $ ppHelpShallow helpDesc short <- addSimpleBoolFlag "" ["short"] (flagHelpStr "make the greeting short") - name <- addStringParam "NAME" + name <- addParamString "NAME" (paramHelpStr "your name, so you can be greeted properly") addCmdImpl $ do @@ -62,9 +69,7 @@ main = mainFromCmdParserWithHelpDesc $ \helpDesc -> do Further: -- [Full description of the above example, including sample behaviour](example1.md) -- [Example of a pure usage of a CmdParser](example2.md) -- [Example of using a CmdParser on interactive input](example3.md) +- See the examples folder included in the package - The [brittany](https://github.com/lspitzner/brittany) formatting tool is a program that uses butcher for implementing its commandline interface. See its [main module source](https://github.com/lspitzner/brittany/blob/master/src-brittany/Main.hs) diff --git a/butcher.cabal b/butcher.cabal index 68e615d..e41f40b 100644 --- a/butcher.cabal +++ b/butcher.cabal @@ -1,6 +1,6 @@ cabal-version: 2.2 name: butcher -version: 1.3.3.2 +version: 2.0.0.0 synopsis: Chops a command or program invocation into digestable pieces. description: See the (it is properly formatted on github). license: BSD-3-Clause