From 93e76047d79d2ff4e68347d72e6399d7c76ef0b3 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Fri, 16 Jul 2021 17:57:31 -1000
Subject: [PATCH] tools: rename tools/doctest -> tools/docshelltest, update

---
 tools/{doctest.hs => docshelltest.hs} | 50 ++++++++++++++-------------
 1 file changed, 26 insertions(+), 24 deletions(-)
 rename tools/{doctest.hs => docshelltest.hs} (72%)

diff --git a/tools/doctest.hs b/tools/docshelltest.hs
similarity index 72%
rename from tools/doctest.hs
rename to tools/docshelltest.hs
index e361dbf15..0778629e8 100755
--- a/tools/doctest.hs
+++ b/tools/docshelltest.hs
@@ -1,43 +1,44 @@
-#!/usr/bin/env runhaskell
+#!/usr/bin/env stack
+{- stack script --resolver nightly-2021-07-16 --compile
+-}
+-- add this to see packages being installed instead of a long silence:
+--   --verbosity=info
+   --package base-prelude
+   --package directory
+   --package extra
+   --package process
+   --package regex
+   --package safe
+   --package shake
+   --package time
+
 {- |
 Extract (shell) tests from haddock comments in Haskell code, run them and
-verify expected output, like Python's doctest system.
+verify expected output. Like https://hackage.haskell.org/package/doctest, 
+but tests shell commands instead of GHCI commands.
 
-Here, a doctest is a haddock literal block whose first line begins with a
-$ (leading whitespace ignored). The rest of the line is a shell command
-and the remaining lines are the expected output.
+A docshelltest is a haddock literal block whose first line begins with a
+$ (leading whitespace ignored), the rest of the line is a shell command
+and the remaining lines are the expected output. The exit code is expected
+to be zero.
 
 Usage example: $ doctest.hs doctest.hs
 
-Doctest examples:
-
 @
-$ ls doctest.hs
-This doctest will fail.
+$ echo This test shall pass
+This test shall pass
 @
 
 @
-$ ls doctest.hs
-doctest.hs
+$ echo This test shall fail
+
 @
 
-Issues:
-
-After writing this I found the doctest on hackage; that one runs haskell
-expressions in comments, converting them to hunit tests. We might add this
-to that, and/or add this to hledger's built-in test runner.
-
-Error output seems to vary depending on whether things are compiled, eg:
-hledger: parse error at (line 1, column 4)
-vs:
-"-" (line 2, column 1)
-ledger-style functional tests may be more useful for this, see functest.hs.
-
 -}
 
 module Main where
 import Data.List (isPrefixOf)
-import System (getArgs)
+import System.Environment (getArgs)
 import System.Exit (exitFailure, exitWith, ExitCode(ExitSuccess)) -- base 3 compatible
 import System.IO (hGetContents, hPutStr, hPutStrLn, stderr)
 import System.Process (runInteractiveCommand, waitForProcess)
@@ -49,6 +50,7 @@ main = do
   let tests = doctests s
   putStrLn $ printf "Running %d doctests from %s" (length tests) f
   ok <-  mapM runShellDocTest $ doctests s
+  putStrLn ""
   if any not ok then exitFailure else exitWith ExitSuccess
 
 runShellDocTest :: String -> IO Bool