Merge pull request #44 from apauley/move-cli-options

Re-organise the command-line interface

.circleci/config.yml

@@ -25,6 +25,9 @@ jobs:
       - run:
           name: Install hledger-flow executable
           command: stack install
+      - run:
+          name: hledger-flow --help
+          command: ~/.local/bin/hledger-flow --help
       - run:
           name: hledger-flow --version
           command: ~/.local/bin/hledger-flow --version
@@ -45,10 +48,10 @@ jobs:
           command: git clone --recurse-submodules https://github.com/apauley/hledger-flow-example.git $HOME/hledger-flow-example
       - run:
           name: hledger-flow import
-          command: ~/.local/bin/hledger-flow --verbose import --show-options $HOME/hledger-flow-example
+          command: ~/.local/bin/hledger-flow --verbose --show-options import $HOME/hledger-flow-example
       - run:
           name: hledger-flow report
-          command: ~/.local/bin/hledger-flow --verbose report --show-options $HOME/hledger-flow-example
+          command: ~/.local/bin/hledger-flow --verbose --show-options report $HOME/hledger-flow-example
       - run:
           name: Undo package.yaml change before cache_save
           command: git checkout HEAD package.yaml

.travis.yml

@@ -45,6 +45,7 @@ install:
   - stack build --interleaved-output --test --bench --no-run-tests --no-run-benchmarks
   - stack install
   - which hledger-flow
+  - hledger-flow --help
   - hledger-flow --version
   - ldd $(which hledger-flow) || true
   - ./bin/release-tarball ~/.local/bin/hledger-flow
@@ -56,8 +57,8 @@ install:
 script:
   - stack test --interleaved-output
   - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then git checkout HEAD package.yaml; fi
-  - hledger-flow --verbose import --show-options $HOME/hledger-flow-example
-  - hledger-flow --verbose report --show-options $HOME/hledger-flow-example
+  - hledger-flow --verbose --show-options import $HOME/hledger-flow-example
+  - hledger-flow --verbose --show-options report $HOME/hledger-flow-example
 
 deploy:
   - provider: releases

ChangeLog.md

@@ -1,5 +1,13 @@
 # Changelog for [hledger-flow](https://github.com/apauley/hledger-flow)
 
+## 0.12.0
+
+- Re-organised the command-line interface:
+  moved various command-line options out of subcommands, into the top-level.
+- Added a [contributor's agreement](https://github.com/apauley/hledger-flow/blob/master/CONTRIBUTING.org)
+  after receiving some more valued contributions from
+  [jecaro](https://github.com/apauley/hledger-flow/pull/42)
+
 ## 0.11.3
 
 - Detect the hledger-flow base directory correctly, even when in a subdirectory. Similar to how git behaves.

README.org

@@ -113,9 +113,9 @@ likely change.
 
 Let me know if you can think of some improvements.
 
-* Detailed Step-By-Step Guide
+* Getting Started
   :PROPERTIES:
-  :CUSTOM_ID: detailed-step-by-step-guide
+  :CUSTOM_ID: getting-started
   :END:
 
 Have a look at the [[file:docs/README.org][detailed step-by-step

app/Main.hs

@@ -14,58 +14,59 @@ import Hledger.Flow.Common
 import Hledger.Flow.Reports
 import Hledger.Flow.CSVImport
 
-data SubcommandParams = SubcommandParams { maybeBaseDir :: Maybe FilePath
-                                         , hledgerPathOpt :: Maybe FilePath
-                                         , showOpts :: Bool
-                                         , sequential :: Bool
-                                         }
-                      deriving (Show)
+data SubcommandParams = SubcommandParams { maybeBaseDir :: Maybe FilePath } deriving (Show)
 data Command = Import SubcommandParams | Report SubcommandParams deriving (Show)
 
-data BaseCommand = Version | Command { verbose :: Bool, command :: Command } deriving (Show)
+data MainParams = MainParams { verbose :: Bool
+                             , hledgerPathOpt :: Maybe FilePath
+                             , showOpts :: Bool
+                             , sequential :: Bool
+                             } deriving (Show)
+data BaseCommand = Version | Command { mainParams :: MainParams, command :: Command } deriving (Show)
 
 main :: IO ()
 main = do
   cmd <- options "An hledger workflow focusing on automated statement import and classification:\nhttps://github.com/apauley/hledger-flow#readme" baseCommandParser
   case cmd of
-    Version          -> stdout $ select versionInfo
-    Command verbose' (Import subParams) -> toImportOptions verbose' subParams >>= importCSVs
-    Command verbose' (Report subParams) -> toReportOptions verbose' subParams >>= generateReports
+    Version                                -> stdout $ select versionInfo
+    Command mainParams' (Import subParams) -> toImportOptions mainParams' subParams >>= importCSVs
+    Command mainParams' (Report subParams) -> toReportOptions mainParams' subParams >>= generateReports
 
-toImportOptions :: Bool -> SubcommandParams -> IO IT.ImportOptions
-toImportOptions verbose' params = do
-  bd <- determineBaseDir $ maybeBaseDir params
-  hli <- hledgerInfoFromPath $ hledgerPathOpt params
+toImportOptions :: MainParams -> SubcommandParams -> IO IT.ImportOptions
+toImportOptions mainParams' subParams' = do
+  bd <- determineBaseDir $ maybeBaseDir subParams'
+  hli <- hledgerInfoFromPath $ hledgerPathOpt mainParams'
   return IT.ImportOptions { IT.baseDir = bd
                           , IT.hledgerInfo = hli
-                          , IT.verbose = verbose'
-                          , IT.showOptions = showOpts params
-                          , IT.sequential = sequential params }
+                          , IT.verbose = verbose mainParams'
+                          , IT.showOptions = showOpts mainParams'
+                          , IT.sequential = sequential mainParams' }
 
-toReportOptions :: Bool -> SubcommandParams -> IO RT.ReportOptions
-toReportOptions verbose' params = do
-  bd <- determineBaseDir $ maybeBaseDir params
-  hli <- hledgerInfoFromPath $ hledgerPathOpt params
+toReportOptions :: MainParams -> SubcommandParams -> IO RT.ReportOptions
+toReportOptions mainParams' subParams' = do
+  bd <- determineBaseDir $ maybeBaseDir subParams'
+  hli <- hledgerInfoFromPath $ hledgerPathOpt mainParams'
   return RT.ReportOptions { RT.baseDir = bd
                           , RT.hledgerInfo = hli
-                          , RT.verbose = verbose'
-                          , RT.showOptions = showOpts params
-                          , RT.sequential = sequential params }
+                          , RT.verbose = verbose mainParams'
+                          , RT.showOptions = showOpts mainParams'
+                          , RT.sequential = sequential mainParams' }
 
 baseCommandParser :: Parser BaseCommand
 baseCommandParser = (Command <$> verboseParser <*> commandParser)
   <|> flag' Version (long "version" <> short 'V' <> help "Display version information")
 
 commandParser :: Parser Command
-commandParser = fmap Import (subcommand "import" "Converts CSV transactions into categorised journal files" subcommandParser)
+commandParser = fmap Import (subcommand "import" "Converts electronic transactions into categorised journal files" subcommandParser)
   <|> fmap Report (subcommand "report" "Generate Reports" subcommandParser)
 
-verboseParser :: Parser Bool
-verboseParser = switch (long "verbose" <> short 'v' <> help "Print more verbose output")
+verboseParser :: Parser MainParams
+verboseParser = MainParams
+  <$> switch (long "verbose" <> short 'v' <> help "Print more verbose output")
+  <*> optional (optPath "hledger-path" 'H' "The full path to an hledger executable")
+  <*> switch (long "show-options" <> help "Print the options this program will run with")
+  <*> switch (long "sequential" <> help "Disable parallel processing")
 
 subcommandParser :: Parser SubcommandParams
 subcommandParser = SubcommandParams
   <$> optional (argPath "basedir" "The hledger-flow base directory")
-  <*> optional (optPath "hledger-path" 'H' "The full path to an hledger executable")
-  <*> switch (long "show-options" <> help "Print the options this program will run with")
-  <*> switch (long "sequential" <> help "Disable parallel processing")

package.yaml

@@ -1,5 +1,5 @@
 name:                hledger-flow
-version:             0.11.3.0
+version:             0.12.0.0
 synopsis:            An hledger workflow focusing on automated statement import and classification.
 category:            Finance, Console
 license:             GPL-3

src/Hledger/Flow/Common.hs

@@ -393,19 +393,19 @@ changeOutputPath newOutputLocation srcFile = mconcat $ map changeSrcDir $ splitD
   where changeSrcDir file = if (file == "1-in/" || file == "2-preprocessed/") then newOutputLocation else file
 
 errorMessageBaseDir :: FilePath -> Text
-errorMessageBaseDir startDir = format ("Unable to find an hledger-flow import directory at '"%fp
+errorMessageBaseDir startDir = format ("\nUnable to find an hledger-flow import directory at '"%fp
                                        %"' (or in any of its parent directories).\n\n"
-                                       %"Have a look at the documentation for more information:\n"%s)
-                               startDir (docURL "input-files")
+                                       %"Have a look at the documentation for more information:\n"%s%"\n")
+                               startDir (docURL "getting-started")
 
 determineBaseDir :: Maybe FilePath -> IO FilePath
 determineBaseDir (Just suppliedDir) = determineBaseDir' suppliedDir
 determineBaseDir Nothing = pwd >>= determineBaseDir'
 
 determineBaseDir' :: FilePath -> IO FilePath
 determineBaseDir' startDir = do
-  ee <- determineBaseDir'' startDir startDir
-  case ee of
+  ebd <- determineBaseDir'' startDir startDir
+  case ebd of
     Right bd -> return bd
     Left  t  -> die t