diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +1.5.3 + +- [Link to code in documentation examples](https://github.com/Gabriella439/optparse-generic/pull/118) +- [Allow newer `optparse-applicative`](https://github.com/Gabriella439/optparse-generic/pull/116) +- [Allow newer `time`](https://github.com/Gabriella439/optparse-generic/pull/115) +- [Allow newer `text`, `bytestring`, and `filepath`](https://github.com/Gabriella439/optparse-generic/pull/113) + 1.5.2 * [Add support for `OsPath`](https://github.com/Gabriella439/optparse-generic/pull/111) diff --git a/optparse-generic.cabal b/optparse-generic.cabal --- a/optparse-generic.cabal +++ b/optparse-generic.cabal @@ -1,5 +1,5 @@ Name: optparse-generic -Version: 1.5.2 +Version: 1.5.3 Cabal-Version: >=1.10 Build-Type: Simple License: BSD3 @@ -25,16 +25,16 @@ Hs-Source-Dirs: src Build-Depends: base >= 4.8 && < 5 , - text < 2.1 , + text < 2.2 , transformers >= 0.2.0.0 && < 0.7 , transformers-compat >= 0.3 && < 0.8 , Only < 0.2 , - optparse-applicative >= 0.16.0.0 && < 0.19, - time >= 1.5 && < 1.13, + optparse-applicative >= 0.16.0.0 && < 0.20, + time >= 1.5 && < 1.15, void < 0.8 , - bytestring < 0.12, - filepath < 1.5 - + bytestring < 0.13, + filepath < 1.6 + if impl(ghc < 8.0) Build-Depends: semigroups >= 0.5.0 && < 0.20 diff --git a/src/Options/Generic.hs b/src/Options/Generic.hs --- a/src/Options/Generic.hs +++ b/src/Options/Generic.hs @@ -21,22 +21,24 @@ -- For example, suppose that you want to parse a record with named fields like -- this: -- --- > -- Example.hs --- > --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE OverloadedStrings #-} --- > --- > import Options.Generic --- > --- > data Example = Example { foo :: Int, bar :: Double } --- > deriving (Generic, Show) --- > --- > instance ParseRecord Example --- > --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Example) +-- @ +-- -- Example.hs -- +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE OverloadedStrings #-} +-- +-- import Options.Generic +-- +-- data Example = Example { foo :: Int, bar :: Double } +-- deriving (Generic, Show) +-- +-- instance 'ParseRecord' Example +-- +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Example) +-- @ +-- -- Named fields translate to flags which you can provide in any order: -- -- > $ stack build optparse-generic @@ -47,39 +49,41 @@ -- -- > $ stack runghc Example.hs -- --help -- > Test program --- > +-- > -- > Usage: Example.hs --foo INT --bar DOUBLE --- > +-- > -- > Available options: -- > -h,--help Show this help text -- -- You can also add help descriptions to each field, like this: -- --- > {-# LANGUAGE DataKinds #-} --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE OverloadedStrings #-} --- > {-# LANGUAGE TypeOperators #-} --- > --- > import Options.Generic --- > --- > data Example = Example --- > { foo :: Int "Documentation for the foo flag" --- > , bar :: Double "Documentation for the bar flag" --- > } deriving (Generic, Show) --- > --- > instance ParseRecord Example --- > --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Example) +-- @ +-- {-# LANGUAGE DataKinds #-} +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE OverloadedStrings #-} +-- {-# LANGUAGE TypeOperators #-} -- +-- import Options.Generic +-- +-- data Example = Example +-- { foo :: Int '' "Documentation for the foo flag" +-- , bar :: Double '' "Documentation for the bar flag" +-- } deriving (Generic, Show) +-- +-- instance 'ParseRecord' Example +-- +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Example) +-- @ +-- -- ... which produces the following @--help@ output: -- -- > $ stack runghc Example.hs -- --help -- > Test program --- > +-- > -- > Usage: Example.hs --foo INT --bar DOUBLE --- > +-- > -- > Available options: -- > -h,--help Show this help text -- > --foo INT Documentation for the foo flag @@ -95,52 +99,56 @@ -- generalize the definition of your record with a parameter 'w', and use -- 'unwrapRecord'. -- --- > {-# LANGUAGE DataKinds #-} --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE FlexibleInstances #-} -- One more extension. --- > {-# LANGUAGE OverloadedStrings #-} --- > {-# LANGUAGE StandaloneDeriving #-} -- To derive Show --- > {-# LANGUAGE TypeOperators #-} --- > --- > import Options.Generic --- > --- > data Example w = Example --- > { foo :: w ::: Int "Documentation for the foo flag" --- > , bar :: w ::: Double "Documentation for the bar flag" --- > } deriving (Generic) --- > --- > instance ParseRecord (Example Wrapped) --- > deriving instance Show (Example Unwrapped) --- > --- > main = do --- > x <- unwrapRecord "Test program" --- > print (x :: Example Unwrapped) +-- @ +-- {-# LANGUAGE DataKinds #-} +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE FlexibleInstances #-} -- One more extension. +-- {-# LANGUAGE OverloadedStrings #-} +-- {-# LANGUAGE StandaloneDeriving #-} -- To derive Show +-- {-# LANGUAGE TypeOperators #-} -- --- @Example Unwrapped@ is equivalent to a record type with simple fields: +-- import Options.Generic -- +-- data Example w = Example +-- { foo :: w ::: Int '' "Documentation for the foo flag" +-- , bar :: w ::: Double '' "Documentation for the bar flag" +-- } deriving (Generic) +-- +-- instance 'ParseRecord' (Example 'Wrapped') +-- deriving instance Show (Example 'Unwrapped') +-- +-- main = do +-- x <- 'unwrapRecord' "Test program" +-- print (x :: Example Unwrapped) +-- @ +-- +-- @Example 'Unwrapped'@ is equivalent to a record type with simple fields: +-- -- > $ stack runghc Example.hs -- --foo 1 --bar 2.5 -- > Example {foo = 1, bar = 2.5} -- -- You can also add default values to each `Read`able field, like this: -- --- > {-# LANGUAGE DataKinds #-} --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE OverloadedStrings #-} --- > {-# LANGUAGE TypeOperators #-} --- > --- > import Options.Generic --- > --- > data Example = Example --- > { foo :: Int "1" --- > , bar :: String "hello" --- > } deriving (Generic, Show) --- > --- > instance ParseRecord Example --- > --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Example) +-- @ +-- {-# LANGUAGE DataKinds #-} +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE OverloadedStrings #-} +-- {-# LANGUAGE TypeOperators #-} -- +-- import Options.Generic +-- +-- data Example = Example +-- { foo :: Int '' "1" +-- , bar :: String '' "hello" +-- } deriving (Generic, Show) +-- +-- instance 'ParseRecord' Example +-- +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Example) +-- @ +-- -- Default values will work alongside help descriptions and unwrapping. -- -- For the following examples I encourage you to test what @--help@ output they @@ -181,7 +189,7 @@ -- > Example {switch = True, list = [1,2], optional = Just 1, first = First -- > {getFirst = Just 1}, last = Last {getLast = Just 2}, sum = Sum {getSum = -- > 3}, product = Product {getProduct = 2}} --- > +-- > -- > $ stack runghc Example.hs -- > Example {switch = False, list = [], optional = Nothing, first = First -- > {getFirst = Nothing}, second = Last {getLast = Nothing}, sum = Sum {getSum @@ -204,32 +212,38 @@ -- This library also provides out-of-the-box support for many existing types, -- like tuples and `Either`. -- --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE OverloadedStrings #-} --- > --- > import Options.Generic --- > --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Either Double Int) +-- @ +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE OverloadedStrings #-} -- +-- import Options.Generic +-- +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Either Double Int) +-- @ +-- -- > $ stack runghc Example.hs -- left 1.0 -- > Left 1.0 -- > $ stack runghc Example.hs -- right 2 -- > Right 2 --- --- > main = do --- > x <- getRecord "Test program" --- > print (x :: (Double, Int)) -- +-- @ +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: (Double, Int)) +-- @ +-- -- > $ stack runghc Example.hs -- 1.0 2 -- > (1.0,2) -- -- ... and you can also just parse a single value: -- --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Int) +-- @ +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Int) +-- @ -- -- > $ stack runghc Example.hs -- 2 -- > 2 @@ -262,27 +276,29 @@ -- > In the instance declaration for ‘ParseRecord TheTypeOfYourRecord’ -- -- You can customize the library's default behavior using the --- `parseRecordWithModifiers` utility, like this: +-- 'parseRecordWithModifiers' utility, like this: -- --- > {-# LANGUAGE DeriveGeneric #-} --- > {-# LANGUAGE OverloadedStrings #-} --- > --- > import Options.Generic --- > --- > data Example = Example { foo :: Int, bar :: Double } --- > deriving (Generic, Show) --- > --- > modifiers :: Modifiers --- > modifiers = defaultModifiers --- > { shortNameModifier = firstLetter --- > } --- > --- > instance ParseRecord Example where --- > parseRecord = parseRecordWithModifiers modifiers --- > --- > main = do --- > x <- getRecord "Test program" --- > print (x :: Example) +-- @ +-- {-# LANGUAGE DeriveGeneric #-} +-- {-# LANGUAGE OverloadedStrings #-} +-- +-- import Options.Generic +-- +-- data Example = Example { foo :: Int, bar :: Double } +-- deriving (Generic, Show) +-- +-- modifiers :: 'Modifiers' +-- modifiers = 'defaultModifiers' +-- { shortNameModifier = firstLetter +-- } +-- +-- instance 'ParseRecord' Example where +-- 'parseRecord' = 'parseRecordWithModifiers' modifiers +-- +-- main = do +-- x <- 'getRecord' "Test program" +-- print (x :: Example) +-- @ module Options.Generic ( -- * Parsers @@ -1217,7 +1233,7 @@ prefs = Options.prefs (defaultParserPrefs <> prefsMods) info = Options.info parseRecord infoMods --- | Marshal any value that implements `ParseRecord` from the commmand line +-- | Marshal any value that implements `ParseRecord` from the command line -- alongside an io action that prints the help message. getWithHelp :: (MonadIO io, ParseRecord a) @@ -1227,7 +1243,7 @@ -- ^ (options, io action to print help message) getWithHelp desc = getWithHelpWith desc mempty --- | Marshal any value that implements `ParseRecord` from the commmand line +-- | Marshal any value that implements `ParseRecord` from the command line -- alongside an io action that prints the help message. getWithHelpWith :: (MonadIO io, ParseRecord a)