More generic FailWhen and WhenError implementation, refined tests and docs

Author: OlegZee

XakeLibTests/ActionTests.fs

@@ -243,19 +243,12 @@ let ``exception handling with 'try finally'``() =
 
       phony "main" (action {
         note "before try"
-
         try
             printfn "Body executed"
             do! anote "try"
         finally
             printfn "Finally executed"
             do note "finally"
-        
-        //try
-        //    failwith "ee"
-        //with e ->
-        //    do note e.Message
-        
         do note "4"
       })
     }
@@ -335,13 +328,32 @@ let ``WhenError function to handle exceptions within actions``() =
                 WhenError (fun _ -> excCount := 1) <|
                 action {
                     printfn "Some useful job"
-                    do! taskReturn 3 |> FailWhen ((=) 3) "err"
+                    do! taskReturn 3 |> FailWhen ((=) 3) "err" |> Action.Ignore
                     printfn "This wont run"
                 })
         ]
     }
 
     Assert.AreEqual(1, !excCount)
 
+[<Test>]
+let ``try/with for the whole script body``() =
+    let excCount = ref 0
+    do xake DebugOptions {
+        rules [
+            "main" =>
+            action {
+                try
+                    printfn "Some useful job"
+                    do 3/0 |> ignore
+                    printfn "This wont run"
+                with _ ->
+                    excCount := 1
+            }
+        ]
+    }
+
+    Assert.AreEqual(1, !excCount)
+
 // TODO use!, try with exception within action
 

XakeLibTests/MiscTests.fs

@@ -85,7 +85,7 @@ let ``resource set instantiation``() =
 let ``script exits with errorlevel on script failure``() =
 
     let errorCode = ref 0
-    System.IO.Directory.CreateDirectory("1")
+    System.IO.Directory.CreateDirectory("1") |> ignore
 
     do xake {xakeOptions with Threads = 1; FileLog="exits-with-errorlevel.log"; FileLogLevel = Verbosity.Diag; Targets = ["one"] } {
         rules [
@@ -125,7 +125,7 @@ let ``failif is a short circuit for task result``() =
     do xake {xakeOptions with Threads = 1; FileLog="failf.log"} {
         rules [
             "main" => (action {
-                do! taskReturn 3 |> FailWhen ((=) 3) "err"
+                do! taskReturn 3 |> FailWhen ((=) 3) "err" |> Action.Ignore
             } |> WhenError (fun _ -> excCount := 1))
         ]
     }
@@ -136,13 +136,28 @@ let ``failif is a short circuit for task result``() =
 let ``WhenError handler intercepts the error``() =
 
     let ex = ref 0
-    do xake {xakeOptions with Threads = 1; FileLog="failf.log"} {
 
+    // pipe result, and provide fallback value in case of error
+    do xake {xakeOptions with Threads = 1; FileLog="failf.log"} {
+        rules [
+            "main" => action {
+                do! taskReturn 3
+                    |> FailWhen ((=) 3) "fail"
+                    |> WhenError (fun _ -> ex := 1; 0)
+                    |> Action.Ignore
+            }
+        ]
+    }
+    // intercept error for resultless action
+    do xake {xakeOptions with Threads = 1; FileLog="failf.log"} {
         rules [
             "main" => action {
-                do! taskReturn 3 |> FailWhen ((=) 3) "fail" |> WhenError (fun _ -> ex := 1)
+                do! taskReturn 3
+                    |> FailWhen ((=) 3) "fail"
+                    |> Action.Ignore
+                    |> WhenError (fun _ -> ex := !ex + 1)
             }
         ]
     }
 
-    Assert.AreEqual(1, !ex)
+    Assert.AreEqual(2, !ex)

core/ActionFunctions.fs

@@ -39,12 +39,12 @@ module ActionFuncs =
     /// </summary>
     /// <param name="cond"></param>
     /// <param name="act"></param>
-    let FailWhen cond err act = Action (fun (r,c) -> 
-        async {
-            let! (r',c') = A.runAction act (r,c)
-            if cond c' then failwith err
-            return (r',())
-        })
+    let FailWhen cond err (act: Action<_,_>) =
+        action {
+            let! b = act
+            if cond b then failwith err
+            return b
+        }
 
     /// <summary>
     /// Supplemental for FailWhen to verify errorlevel set by system command.
@@ -61,13 +61,10 @@ module ActionFuncs =
     /// Wraps action so that exceptions occured while executing action are ignored.
     /// </summary>
     /// <param name="act"></param>
-    let WhenError h (act:Action<'a,unit>) = 
-        Action (fun (r,a) -> async {
+    let WhenError handler (act:Action<_,_>) = 
+        action {
             try
-                let! (r',_) = A.runAction act (r,a)
-                return (r',())
-            with
-                e ->
-                    do h e 
-                    return (r,())
-        })
+                let! r = act
+                return r
+            with e -> return handler e 
+        }

docs/implnotes.md

@@ -29,26 +29,31 @@ Error handling assumes the following system behavior:
   * idea: dump the whole trace to the target
   * setting error-code for the fsi sessions
 
-### Ideas in progress
-Idea #1: WhenError function which intercepts any failures and lets define a custom handler
+### Implemented ideas
+
+#### WhenError function
+Intercepts errors (exceptions) and allows to define a custom handler.
 ```
   phony "main" (action {
     do! trace Message "The exception thrown below will be silently ignored"
     failwith "some error"
     } |> WhenError ignore)
 ```
 
-Idea #2 (orthogonal): special directive to fail next command on non-zero result
+#### FailWhen
+Raises the exception if action's result meet specified condition.
+E.g. the following code raises error in case errorlevel (result of shell command execution) gets non-zero value.
 ```
-fail_if ((<>) 0) _system [shellcmd] "dir"
-fail_on_errorlevel _system [shellcmd] "dir"
-// where shellcmd and fail_on_error are functions
-
-// or just function:
 do! _system [shellcmd] "dir" |> FailWhen ((<>) 0) "Failed to list files in folder"
 // or just
 do! _system [shellcmd] "dir" |> CheckErrorLevel
+```
+
+#### try/with/finally exception handling
+`action` computation expression supports try/with and try/finally blocks. In most cases these constructs are more
+elegant than using WhenError.
 
+### Other ideas
 
 // or even that:
 _system [fail_on_error; shellcmd] "dir"
@@ -61,6 +66,7 @@ do! _system [fail_on_error; shellcmd; startin "./bin"] "dir"
 // where shellcmd and fail_on_error are functions
 ```
 
+Let action be provided as finally argument.
 
 ### Ideas
 Implemented IgnoreErrors.

docs/overview.md

@@ -294,6 +294,45 @@ If the task (action) returns a value which you do not need use Action.Ignore:
   }
 ```
 
+### Exception handling
+`action` block allows to handle exceptions with idiomatic try/with and try/finally blocks.
+```fsharp
+    phony "main" (action {
+      do! trace Level.Info "before try" // trace is standard action reporting to file/screen log
+      try
+        try
+            do! trace Level.Info "try"
+            failwith "Ouch"
+        with e ->
+            printfn "Error '%s' occured" e.Message
+      finally
+          printfn "Finally executed"
+        
+      printfn "execution continues after try blocks"
+    })
+```
+Notice `trace` function just like any other actions cannot be used inside `with` and `finally` blocks due to language limitations.
+
+`WhenError` function is another option to handle errors.
+```fsharp
+action {
+    printfn "Some useful job"
+    do! action {failwith "err"} |> WhenError (fun _ -> printfn "caught the error")
+}
+```
+or this way
+```fsharp
+rules [
+    "main" => (
+        WhenError ignore <| // ignore is a standard f# function accepting one argument
+        action {
+            printfn "Some useful job"
+            failwith "File IO error!"
+            printfn "This wont run"
+        })
+]
+```
+
 ### need
 
 `need` function is widely used internally and it is a key element for dependency tracking. Calling `need` ensures the requested files are built according to rules.