docstrings

TAP/Options.idr

@@ -1,3 +1,4 @@
+||| command line options
 module TAP.Options
 
 import Data.String
@@ -7,25 +8,45 @@ import System.Console.GetOpt
 %default total
 
 
+||| which TAP version to use for output.
+||| - `V14` supports subtests
+||| - `V13` flattens the tree before running it
 public export
 data TAPVersion = V13 | V14
 
+||| try to read a numeric TAP version number
 export
 readVersion : String -> Maybe TAPVersion
 readVersion "13" = Just V13
 readVersion "14" = Just V14
 readVersion _    = Nothing
 
+||| prints as just the number
 export Show TAPVersion where show V13 = "13"; show V14 = "14"
 
 
+||| command line options
+|||
+||| apart from these there is also a usage message with
+||| `-?`, `-h`, `--help`
 public export
 record Options where
   constructor Opts
+  ||| `-V`, `--version`:
+  ||| which TAP version to output
   version : TAPVersion
+  ||| `-F`, `--filter`:
+  ||| search for a substring in test or group names.
+  ||| if it is present in a group name then all subtests are run
+  ||| regardless of their own names
   pattern : Maybe String
+  ||| `-c`, `--color`, `--colour`:
+  ||| colour code test results and a few other things.
+  ||| this is not TAP compliant so it is off by default.
   color   : Bool
 
+||| default options
+||| (version 13 (because of `prove`), no filter, no colour)
 export
 defaultOpts : Options
 defaultOpts = Opts {
@@ -34,11 +55,16 @@ defaultOpts = Opts {
   color   = False
 }
 
+||| value for each option.
+||| i'm using the old idiom where each option is a function that updates
+||| an accumulated record. with IO because of the error messages being printed
 public export
 Mod : Type
 Mod = Options -> IO Options
 
 
+||| print the given messages as TAP comments and then say `Bail out!`.
+||| so the error is a valid TAP transcript too :3
 export
 failureWith : List String -> IO a
 failureWith msgs = do
@@ -46,6 +72,7 @@ failureWith msgs = do
   putStrLn "\nBail out!"
   exitFailure
 
+
 private
 setTapVer : String -> Mod
 setTapVer ver opts =
@@ -54,10 +81,11 @@ setTapVer ver opts =
        Nothing => failureWith ["unrecognised TAP version '\{ver}'"]
 
 private
-setPat : String -> Mod
-setPat str opts = pure $ {pattern := Just str} opts
+setFilter : String -> Mod
+setFilter str opts = pure $ {pattern := Just str} opts
 
 mutual
+  ||| option descriptions
   export
   opts : List (OptDescr Mod)
   opts =
@@ -74,7 +102,7 @@ mutual
       MkOpt {
         description = "only run tests containing STR in their group or label",
         shortNames  = ['F'], longNames = ["filter"],
-        argDescr    = ReqArg setPat "STR"
+        argDescr    = ReqArg setFilter "STR"
       },
       MkOpt {
         description = "don't colour-code results (default)",
@@ -88,16 +116,19 @@ mutual
       }
     ]
 
+  ||| usage message
   export
   usage : List String
   usage = assert_total $ "quox test suite" :: lines (usageInfo "" opts)
 
 
+||| interpret the result of `getOpt`
 export
 makeOpts : List Mod -> IO Options
 makeOpts = foldlM (\x, f => f x) defaultOpts
 
 
+||| like `getArgs` but skip the first one, which is the executable name
 export
 getArgs1 : IO (List String)
 getArgs1 =
@@ -105,9 +136,20 @@ getArgs1 =
        _ :: args => pure args
        []        => failureWith ["expected getArgs to start with exe name"]
 
+
+||| read & interpret the command line arguments
+|||
+||| [todo] allow unrecognised things and pass them back out
 export
-getTestOpts : IO Options
-getTestOpts =
-  case getOpt Permute opts !getArgs1 of
+getTestOpts' : List String -> IO Options
+getTestOpts' args =
+  case getOpt Permute opts args of
        MkResult opts [] [] [] => makeOpts opts
        res                    => failureWith $ res.errors ++ usage
+
+||| interpret some command line arguments passed in
+|||
+||| [todo] allow unrecognised things and pass them back out
+export
+getTestOpts : IO Options
+getTestOpts = getTestOpts' !getArgs1