Transformation of explanations to JSON.

explanations.pl

@@ -30,6 +30,7 @@
 %
 % @throws fails(Atom) if Atom cannot be proven
 explain(Atom, Message, Details, References) :-
+  ( call(Atom) -> true; throw(fails(Atom))),
   clause(Atom,Body), call(Body),
   explain_message((Atom :- Body), Message, 0, No1, [], References1),
   explain_details((Atom :- Body), Details, No1, _No2, References1, References).
@@ -41,7 +42,7 @@ explain(Atom, Message, Details, References) :-
 % clause was proven to hold. A list of entity references References (see 
 % explain/4) is generated for and used within the message.
 explain_message(_Clause, 
-  "Some message I have no idea how to generate", 
+  ["Some message I have no idea how to generate"], 
   No, No, [], []).
 
 % explain_details(+Clause, -Details, +NoIn, -NoOut, +ReferencesIn, -ReferencesOut)

web_api.pl

@@ -86,25 +86,79 @@ server_opts(Opts) :-
 :- http_handler(root(query), handle_query, []).
 
 /* Closures for handlers */
+%! handle_explain(++Request) is det
+%
+%  Handles HTTP request to explain the irrelevance of a single absolute path.
+%
+% @throws bad_request(not_irrelevant(AbsPath)) If the absolut path provided in 
+%                                              the request's payload denotes a
+%                                              file which is not irrelevant. 
+%                                              Then, by definition, no 
+%                                              explanation may be created.
+% @throws bad_request(missing_key(Key)) If a required parameter was missing
+%                                       in the JSON payload.
+% @throws bad_request(wrong_type(KeyName, Type))) If the value associated with
+%                                                 the key KeyName is not of the
+%                                                 correct type.
+% @throws bad_request(unknown_key(KeyName)) The unknown key KeyName was supplied
+%                                           in the request's payload.
+% @throw server_error(E,Context) if an exception occured which is not the user's
+%                                error, but our own.
 handle_explain(Req) :- 
-    http_read_json(Req, json(Content),[value_string_as(string)]),
-    
-    %% Limit as int, Path as string
-    % TODO: improve error handling on required parameter
-    ( member(abs_path=Path, Content) -> true ; throw("abs_path is required!")),
-    ( member(limit=Limit, Content) -> true; Limit=5 ),
-    
-    % TODO: improve error handling
-    ( bagof([abs_path=Path, reasoning=Message, reasoning_details=Details, references=References],
-        explain(irrelevant(Path),Message,Details,References),
-        AllExplanations )
-      -> true
-      ; throw("No explanation found!")
-    ),    
-    Exceeded = true,
-        
-    reply_json(json([explanations=AllExplanations,'answers-exceeded'=Exceeded])).
+    http_read_json(Req, Parameters, [json_object(dict), value_string_as(atom)]),
+    catch(do_handle_explain(Parameters, Explanations, More),
+          E,
+          (
+            explain_exception_to_handler_exception(E, HandlerException),
+            throw(HandlerException)
+          )
+    ),
+    catch(maplist(explain_explanation_to_json, Explanations, ExplanationsJSON),
+          error(Err,Context),
+          throw(server_error(Err,Context))),
+    reply_json_dict(reply{explanations: ExplanationsJSON,
+                          further_explanations: @(More)},
+                    [true(@(true)), false(@(false))]).  % in only default for
+                                                        % reply_json/1 and
+                                                        % reply_json/2.
+
+
+              
+%! explain_exception_to_handler_exception(+ExplainException, --HandlerException)
+%
+% Translates exceptions from do_handle_explain/3 to bad_request/1 and
+% server_error/2 terms thrown by handle_explain/1.
+%
+% @see do_handle_explain/3 for the actual errors thrown
+% @see handle_explain/1 for the resulting handler errors
+explain_exception_to_handler_exception(not_irrelevant(AbsPath),
+    bad_request(not_irrelevant(AbsPath))).
+explain_exception_to_handler_exception(
+    error(existence_error(key, Key, _Parameters),_),
+    bad_request(missing_key(Key))).
+explain_exception_to_handler_exception(
+    error(type_error(dict, Dict), Context),
+    server_error(type_error(dict, Dict), Context)) :- is_dict(Dict).
+explain_exception_to_handler_exception(
+    error(type_error(Type, KeyName),_),
+    bad_request(wrong_type(KeyName, Type))).
+explain_exception_to_handler_exception(
+    error(unknown_key(KeyName, _Parameters),_),
+    bad_request(unknown_key(KeyName))).
+explain_exception_to_handler_exception(   
+    error(instantiation_error,Context),
+    server_error(instantiation_error,Context)).
+explain_exception_to_handler_exception(   
+    error(uninstantiation_error(Argument),Context),
+    server_error(uninstantiation_error(Argument),Context)).
+explain_exception_to_handler_exception(   
+    error(implementation_error(Cause),Context),
+    server_error(implementation_error(Cause),Context)).
+explain_exception_to_handler_exception(   
+    error(E,Context),
+    server_error(unexpected_error(E),Context)).
 
+        
 %! explain_explanation_to_json(++Explanation, --JSON) is det
 %
 % Transforms an explanation to a term suitable to be transformed into a JSON
@@ -305,8 +359,8 @@ do_handle_explain_(AbsPath, Limit, Result, More) :-
               explanation(AbsPath,Message, Details, References),
               explanations:explain(irrelevant(AbsPath), Message, Details, References),
               Result),
-    deterministic(OpenChoicePoints),
-    (   OpenChoicePoints==true  % other responses are not explicitly documented
+    deterministic(LastAnswer),
+    (   LastAnswer==true  % other responses are not explicitly documented
     ->  More=false
     ;   More=true
     ), !.