cmdargs 0.10.17 → 0.10.18

raw patch · 4 files changed

+180/−169 lines, 4 filesdep ~basePVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependency ranges changed: base

API changes (from Hackage documentation)

Files

• CHANGES.txt +2/−0
• README.md +167/−167
• System/Console/CmdArgs/Explicit/Type.hs +9/−0
• cmdargs.cabal +2/−2

@@ -1,5 +1,7 @@ Changelog for CmdArgs +0.10.18+    #47, GHC 8.4 compatibility 0.10.17     Add processValueIO for more controlled error messages     #529, don't include the stack trace in processValue

@@ -6,24 +6,24 @@ * It supports programs with multiple modes, such as [darcs](http://darcs.net) or [Cabal](http://haskell.org/cabal/).  A very simple example of a command line processor is:+```haskell+data Sample = Sample {hello :: String} deriving (Show, Data, Typeable) -    data Sample = Sample {hello :: String} deriving (Show, Data, Typeable)-    -    sample = Sample{hello = def &= help "World argument" &= opt "world"}-             &= summary "Sample v1"-    -    main = print =<< cmdArgs sample+sample = Sample{hello = def &= help "World argument" &= opt "world"}+         &= summary "Sample v1" +main = print =<< cmdArgs sample+``` Despite being very concise, this processor is already fairly well featured:      $ runhaskell Sample.hs --hello=world     Sample {hello = "world"}-    +     $ runhaskell Sample.hs --help     Sample v1, (C) Neil Mitchell 2009-    +     sample [FLAG]-    +       -? --help[=FORMAT]  Show usage information (optional format)       -V --version        Show version information       -v --verbose        Higher verbosity@@ -46,19 +46,19 @@ ## Hello World Example  The following code defines a complete command line argument processor:+```haskell+{-# LANGUAGE DeriveDataTypeable #-}+{-# OPTIONS_GHC -fno-cse #-}+module Sample where+import System.Console.CmdArgs -    {-# LANGUAGE DeriveDataTypeable #-}-    {-# OPTIONS_GHC -fno-cse #-}-    module Sample where-    import System.Console.CmdArgs-    -    data Sample = Sample {hello :: String}-                  deriving (Show, Data, Typeable)-    -    sample = Sample{hello = def}-    -    main = print =<< cmdArgs sample+data Sample = Sample {hello :: String}+              deriving (Show, Data, Typeable) +sample = Sample{hello = def}++main = print =<< cmdArgs sample+``` To use the CmdArgs library there are three steps:  * Define a record data type (`Sample`) that contains a field for each argument. This type needs to have instances for `Show`, `Data` and `Typeable`.@@ -69,15 +69,15 @@      $ runhaskell Sample.hs --hello=world     Sample {hello = "world"}-    +     $ runhaskell Sample.hs --version     The sample program-    +     $ runhaskell Sample.hs --help     The sample program-    +     sample [OPTIONS]-    +       -? --help        Display help message       -V --version     Print version information       -h --hello=ITEM@@ -87,13 +87,13 @@ ## Specifying Attributes  In order to control the behaviour we can add attributes. For example to add an attribute specifying the help text for the `--hello` argument we can write:--    sample = Sample{hello = def &= help "Who to say hello to"}-+```haskell+sample = Sample{hello = def &= help "Who to say hello to"}+``` We can add additional attributes, for example to specify the type of the value expected by hello:--    sample = Sample {hello = def &= help "Who to say hello to" &= typ "WORLD"}-+```haskell+sample = Sample {hello = def &= help "Who to say hello to" &= typ "WORLD"}+``` Now when running `--help` the final line is:        -h --hello=WORLD  Who to say hello to@@ -104,37 +104,37 @@ ## Multiple Modes  To specify a program with multiple modes, similar to [darcs](http://darcs.net/), we can supply a data type with multiple constructors, for example:-    -    data Sample = Hello {whom :: String}-                | Goodbye-                  deriving (Show, Data, Typeable)-    -    hello = Hello{whom = def}-    goodbye = Goodbye-    -    main = print =<< cmdArgs (modes [hello,goodbye])+```haskell+data Sample = Hello {whom :: String}+            | Goodbye+              deriving (Show, Data, Typeable) +hello = Hello{whom = def}+goodbye = Goodbye++main = print =<< cmdArgs (modes [hello,goodbye])+``` Compared to the first example, we now have multiple constructors, and a sample value for each constructor is passed to `cmdArgs`. Some sample interactions with this command line are:      $ runhaskell Sample.hs hello --whom=world     Hello {whom = "world"}-    +     $ runhaskell Sample.hs goodbye     Goodbye-    +     $ runhaskell Sample.hs --help     The sample program-    +     sample [OPTIONS]-    +      Common flags       -? --help       Display help message       -V --version    Print version information-    +     sample hello [OPTIONS]-    +       -w --whom=ITEM-    +     sample goodbye [OPTIONS]  As before, the behaviour can be customised using attributes.@@ -154,62 +154,62 @@ * The `cpp_define` field has an underscore in it's name, which is transformed into a hyphen for the flag name.  The code is:+```haskell+{-# LANGUAGE DeriveDataTypeable #-}+module HLint where+import System.Console.CmdArgs -    {-# LANGUAGE DeriveDataTypeable #-}-    module HLint where-    import System.Console.CmdArgs-    -    data HLint = HLint-        {report :: [FilePath]-        ,hint :: [FilePath]-        ,color :: Bool-        ,ignore_ :: [String]-        ,show_ :: Bool-        ,extension :: [String]-        ,language :: [String]-        ,utf8 :: Bool-        ,encoding :: String-        ,find :: [FilePath]-        ,test_ :: Bool-        ,datadir :: [FilePath]-        ,cpp_define :: [String]-        ,cpp_include :: [FilePath]-        ,files :: [FilePath]-        }-        deriving (Data,Typeable,Show,Eq)-    -    hlint = HLint-        {report = def &= opt "report.html" &= typFile &= help "Generate a report in HTML"-        ,hint = def &= typFile &= help "Hint/ignore file to use"-        ,color = def &= name "c" &= name "colour" &= help "Color the output (requires ANSI terminal)"-        ,ignore_ = def &= typ "MESSAGE" &= help "Ignore a particular hint"-        ,show_ = def &= help "Show all ignored ideas"-        ,extension = def &= typ "EXT" &= help "File extensions to search (defaults to hs and lhs)"-        ,language = def &= name "X" &= typ "LANG" &= help "Language extension (Arrows, NoCPP)"-        ,utf8 = def &= help "Use UTF-8 text encoding"-        ,encoding = def &= typ "ENC" &= help "Choose the text encoding"-        ,find = def &= typFile &= help "Find hints in a Haskell file"-        ,test_ = def &= help "Run in test mode"-        ,datadir = def &= typDir &= help "Override the data directory"-        ,cpp_define = def &= typ "NAME[=VALUE]" &= help "CPP #define"-        ,cpp_include = def &= typDir &= help "CPP include path"-        ,files = def &= args &= typ "FILES/DIRS"-        } &=-        verbosity &=-        help "Suggest improvements to Haskell source code" &=-        summary "HLint v0.0.0, (C) Neil Mitchell" &=-        details ["Hlint gives hints on how to improve Haskell code",""-                ,"To check all Haskell files in 'src' and generate a report type:","  hlint src --report"]-    -    mode = cmdArgsMode hlint+data HLint = HLint+    {report :: [FilePath]+    ,hint :: [FilePath]+    ,color :: Bool+    ,ignore_ :: [String]+    ,show_ :: Bool+    ,extension :: [String]+    ,language :: [String]+    ,utf8 :: Bool+    ,encoding :: String+    ,find :: [FilePath]+    ,test_ :: Bool+    ,datadir :: [FilePath]+    ,cpp_define :: [String]+    ,cpp_include :: [FilePath]+    ,files :: [FilePath]+    }+    deriving (Data,Typeable,Show,Eq) +hlint = HLint+    {report = def &= opt "report.html" &= typFile &= help "Generate a report in HTML"+    ,hint = def &= typFile &= help "Hint/ignore file to use"+    ,color = def &= name "c" &= name "colour" &= help "Color the output (requires ANSI terminal)"+    ,ignore_ = def &= typ "MESSAGE" &= help "Ignore a particular hint"+    ,show_ = def &= help "Show all ignored ideas"+    ,extension = def &= typ "EXT" &= help "File extensions to search (defaults to hs and lhs)"+    ,language = def &= name "X" &= typ "LANG" &= help "Language extension (Arrows, NoCPP)"+    ,utf8 = def &= help "Use UTF-8 text encoding"+    ,encoding = def &= typ "ENC" &= help "Choose the text encoding"+    ,find = def &= typFile &= help "Find hints in a Haskell file"+    ,test_ = def &= help "Run in test mode"+    ,datadir = def &= typDir &= help "Override the data directory"+    ,cpp_define = def &= typ "NAME[=VALUE]" &= help "CPP #define"+    ,cpp_include = def &= typDir &= help "CPP include path"+    ,files = def &= args &= typ "FILES/DIRS"+    } &=+    verbosity &=+    help "Suggest improvements to Haskell source code" &=+    summary "HLint v0.0.0, (C) Neil Mitchell" &=+    details ["Hlint gives hints on how to improve Haskell code",""+            ,"To check all Haskell files in 'src' and generate a report type:","  hlint src --report"]++mode = cmdArgsMode hlint+``` Produces the `--help` output:      HLint v0.0.0, (C) Neil Mitchell-    +     hlint [OPTIONS] [FILES/DIRS]     Suggest improvements to Haskell source code-    +     Common flags:       -r --report[=FILE]            Generate a report in HTML       -h --hint=FILE                Hint/ignore file to use@@ -229,13 +229,13 @@       -V --version                    Print version information       -v --verbose                    Loud verbosity       -q --quiet                    Quiet verbosity-    +     Hlint gives hints on how to improve Haskell code-    +     To check all Haskell files in 'src' and generate a report type:       hlint src --report-     + ### Diffy  The Diffy sample is a based on the idea of creating directory listings and comparing them. The tool can operate in two separate modes, `create` or `diff`. This sample is fictional, but the ideas are drawn from a real program. A few notable features:@@ -245,47 +245,47 @@ * Default values are given for the `out` field, which are different in both modes.  The code is:+```haskell+{-# LANGUAGE DeriveDataTypeable #-}+module Diffy where+import System.Console.CmdArgs -    {-# LANGUAGE DeriveDataTypeable #-}-    module Diffy where-    import System.Console.CmdArgs-    -    data Diffy = Create {src :: Maybe FilePath, out :: FilePath}-               | Diff {old :: FilePath, new :: FilePath, out :: FilePath}-                 deriving (Data,Typeable,Show,Eq)-    -    outFlags x = x &= help "Output file" &= typFile-    -    create = Create-        {src = def &= help "Source directory" &= typDir-        ,out = outFlags "ls.txt"-        } &= help "Create a fingerprint"-    -    diff = Diff-        {old = def &= typ "OLDFILE" &= argPos 0-        ,new = def &= typ "NEWFILE" &= argPos 1-        ,out = outFlags "diff.txt"-        } &= help "Perform a diff"-    -    mode = cmdArgsMode $ modes [create,diff] &= help "Create and compare differences" &= program "diffy" &= summary "Diffy v1.0"+data Diffy = Create {src :: Maybe FilePath, out :: FilePath}+           | Diff {old :: FilePath, new :: FilePath, out :: FilePath}+             deriving (Data,Typeable,Show,Eq) +outFlags x = x &= help "Output file" &= typFile++create = Create+    {src = def &= help "Source directory" &= typDir+    ,out = outFlags "ls.txt"+    } &= help "Create a fingerprint"++diff = Diff+    {old = def &= typ "OLDFILE" &= argPos 0+    ,new = def &= typ "NEWFILE" &= argPos 1+    ,out = outFlags "diff.txt"+    } &= help "Perform a diff"++mode = cmdArgsMode $ modes [create,diff] &= help "Create and compare differences" &= program "diffy" &= summary "Diffy v1.0"+``` And `--help` produces:      Diffy v1.0-     +     diffy [COMMAND] ... [OPTIONS]       Create and compare differences-     +     Common flags:       -o --out=FILE     Output file       -? --help         Display help message       -V --version     Print version information-     +     diffy create [OPTIONS]       Create a fingerprint-     +       -s  --src=DIR  Source directory-     +     diffy diff [OPTIONS] OLDFILE NEWFILE       Perform a diff @@ -298,67 +298,67 @@ * The `threads` field is in two of the constructors, but not all three. It is given the short flag `-j`, rather than the default `-t`.  The code is:+```haskell+{-# LANGUAGE DeriveDataTypeable #-}+module Maker where+import System.Console.CmdArgs -    {-# LANGUAGE DeriveDataTypeable #-}-    module Maker where-    import System.Console.CmdArgs-    -    data Method = Debug | Release | Profile-                  deriving (Data,Typeable,Show,Eq)-    -    data Maker-        = Wipe-        | Test {threads :: Int, extra :: [String]}-        | Build {threads :: Int, method :: Method, files :: [FilePath]}-          deriving (Data,Typeable,Show,Eq)-    -    threadsMsg x = x &= help "Number of threads to use" &= name "j" &= typ "NUM"-    -    wipe = Wipe &= help "Clean all build objects"-    -    test_ = Test-        {threads = threadsMsg def-        ,extra = def &= typ "ANY" &= args-        } &= help "Run the test suite"-    -    build = Build-        {threads = threadsMsg def-        ,method = enum-            [Release &= help "Release build"-            ,Debug &= help "Debug build"-            ,Profile &= help "Profile build"]-        ,files = def &= args-        } &= help "Build the project" &= auto-    -    mode = cmdArgsMode $ modes [build,wipe,test_]-         &= help "Build helper program"-         &= program "maker"-         &= summary "Maker v1.0\nMake it"+data Method = Debug | Release | Profile+              deriving (Data,Typeable,Show,Eq) +data Maker+    = Wipe+    | Test {threads :: Int, extra :: [String]}+    | Build {threads :: Int, method :: Method, files :: [FilePath]}+      deriving (Data,Typeable,Show,Eq)++threadsMsg x = x &= help "Number of threads to use" &= name "j" &= typ "NUM"++wipe = Wipe &= help "Clean all build objects"++test_ = Test+    {threads = threadsMsg def+    ,extra = def &= typ "ANY" &= args+    } &= help "Run the test suite"++build = Build+    {threads = threadsMsg def+    ,method = enum+        [Release &= help "Release build"+        ,Debug &= help "Debug build"+        ,Profile &= help "Profile build"]+    ,files = def &= args+    } &= help "Build the project" &= auto++mode = cmdArgsMode $ modes [build,wipe,test_]+     &= help "Build helper program"+     &= program "maker"+     &= summary "Maker v1.0\nMake it"+``` And `--help` produces:      Maker v1.0       Make it-     +     maker [COMMAND] ... [OPTIONS]       Build helper program-     +     Common flags:       -? --help     Display help message       -V --version  Print version information-     +     maker [build] [OPTIONS] [ITEM]       Build the project-     +       -j --threads=NUM  Number of threads to use       -r --release      Release build       -d --debug        Debug build       -p --profile      Profile build-     +     maker wipe [OPTIONS]       Clean all build objects-     +     maker test [OPTIONS] [ANY]       Run the test suite-     +       -j --threads=NUM  Number of threads to use

@@ -1,3 +1,4 @@+{-# LANGUAGE CPP #-}  module System.Console.CmdArgs.Explicit.Type where @@ -7,6 +8,9 @@ import Data.List import Data.Maybe import Data.Monoid+#if __GLASGOW_HASKELL__ >= 802+import Data.Semigroup (Semigroup(..))+#endif import Prelude  @@ -47,6 +51,11 @@  instance Functor Group where     fmap f (Group a b c) = Group (map f a) (map f b) (map (second $ map f) c)++#if __GLASGOW_HASKELL__ > 800+instance Semigroup (Group a) where+    (<>) = mappend+#endif  instance Monoid (Group a) where     mempty = Group [] [] []

@@ -1,7 +1,7 @@ cabal-version:      >= 1.18 build-type:         Simple name:               cmdargs-version:            0.10.17+version:            0.10.18 license:            BSD3 license-file:       LICENSE category:           Console@@ -33,7 +33,7 @@ extra-doc-files:     README.md     CHANGES.txt-tested-with:        GHC==8.0.2, GHC==7.10.3, GHC==7.8.4, GHC==7.6.3, GHC==7.4.2+tested-with:        GHC==8.2.1, GHC==8.0.2, GHC==7.10.3, GHC==7.8.4, GHC==7.6.3, GHC==7.4.2  source-repository head     type:     git