Return triple in decode() and add decode_and_validate()

Author: Josef Erben

CHANGES.md

@@ -1,3 +1,10 @@
+## 0.3.0 - 2021-03-26
+### Changed
+- `decode` returns a triple containing `(field_name, input, error_msg)` instead of a concatenated string. This makes it easier to extract information.
+
+### Added
+- `decode_and_validate` combines `decode` and `validate` where the returned value is either the decoded value or a list of errors. When using `decode_and_validate`, one can forget about the difference between `decode` and `validate` and simply forward the list of errors. This covers a common use case.
+
 ## 0.2.1 - 2021-03-16
 ### Changed
 - Replace `ppx_deriving` with `sexplib`

src/conformist.ml

@@ -202,7 +202,9 @@ let validate schema input =
 
 let rec decode
     : type meta ctor ty.
-      (meta, ctor, ty) t -> (string * string list) list -> (ty, string) Result.t
+      (meta, ctor, ty) t
+      -> (string * string list) list
+      -> (ty, string * string option * string) Result.t
   =
  fun { fields; ctor } fields_assoc ->
   let open! Field in
@@ -215,59 +217,47 @@ let rec decode
       | Ok value ->
         (match ctor value with
         | ctor -> decode { fields; ctor } fields_assoc
-        | exception _ ->
-          Error
-            (Printf.sprintf
-               "Failed to decode value '%s' of field '%s'"
-               value_string
-               field.name))
-      | Error msg ->
-        Error
-          (Printf.sprintf
-             "Failed to decode value '%s' of field '%s': %s"
-             field.name
-             value_string
-             msg))
+        | exception exn ->
+          let msg = Printexc.to_string exn in
+          Error (field.name, Some value_string, msg))
+      | Error msg -> Error (field.name, Some value_string, msg))
     | [] ->
       (match field.default with
       | Some value ->
         (match ctor value with
         | ctor -> decode { fields; ctor } fields_assoc
-        | exception _ ->
-          Error (Printf.sprintf "Failed to construct field '%s'" field.name))
+        | exception exn ->
+          let msg = Printexc.to_string exn in
+          Error (field.name, Some "", msg))
       | None ->
         (match field.decoder "" with
         | Ok value ->
           (match ctor value with
           | ctor -> decode { fields; ctor } fields_assoc
-          | exception _ ->
-            Error
-              (Printf.sprintf
-                 "Failed to decode value '%s' of field '%s'"
-                 ""
-                 field.name))
-        | Error msg ->
-          Error
-            (Printf.sprintf
-               "Failed to decode value '%s' of field '%s': %s"
-               field.name
-               ""
-               msg)))
-    | _ ->
-      Error
-        (Printf.sprintf
-           "Failed to decode field '%s': Multiple values provided"
-           field.name)
+          | exception exn ->
+            let msg = Printexc.to_string exn in
+            Error (field.name, Some "", msg))
+        | Error msg -> Error (field.name, Some "", msg)))
+    | _ -> Error (field.name, None, "Multiple values provided")
     | exception Not_found ->
       (match field.default with
       | Some value ->
         (match ctor value with
         | ctor -> decode { fields; ctor } fields_assoc
-        | exception _ ->
-          Error (Printf.sprintf "Failed to construct field '%s'" field.name))
-      | None ->
-        Error
-          (Printf.sprintf
-             "Failed to decode field '%s': No value provided"
-             field.name)))
+        | exception exn ->
+          let msg = Printexc.to_string exn in
+          Error (field.name, None, msg))
+      | None -> Error (field.name, None, "No value provided")))
+;;
+
+let decode_and_validate schema input =
+  let validation_errors = validate schema input in
+  match decode schema input, validation_errors with
+  | Ok value, [] -> Ok value
+  | Ok _, validation_errors -> Error validation_errors
+  | Error (field_name, _, msg), validation_errors ->
+    validation_errors
+    |> List.filter (fun (name, _) -> not (String.equal name field_name))
+    |> List.cons (field_name, msg)
+    |> Result.error
 ;;

src/conformist.mli

@@ -309,12 +309,41 @@ type validation_error = (string * string) list
     This is typically some user input. *)
 type input = (string * string list) list
 
-(** [decode schema input] tries to create a value of the static type ['ty]. Note
-    that a successfully decoded value means that the strings contain the
-    expected types, but no validation logic was executed. *)
-val decode : ('meta, 'ctor, 'ty) t -> input -> ('ty, string) result
-
-(** [validate schema input] runs the field validators on decoded data. Note that
-    a field that fails to decode will also fail validation, but a decoded field
-    might still fail validation. *)
+(** [decode schema input] returns the decoded value of type ['ty] by decoding
+    the [input] using the [schema].
+
+    The returned error value is a triple [(field_name, input_value, error_msg)].
+    [field_name] is the field name of the input that failed to decode,
+    [input_value] is the input value if one was provided and [error_msg] is the
+    error message.
+
+    No validation logic is executed in this step. *)
+val decode
+  :  ('meta, 'ctor, 'ty) t
+  -> input
+  -> ('ty, string * string option * string) result
+
+(** [validate schema input] returns a list of validation errors by running the
+    validators defined in [schema] on the [input] data. An empty list implies
+    that there are no validation errors and that the input is valid according to
+    the schema.
+
+    Note that [input] that has no validation errors might still fail to decode,
+    depending on the validation functions specified in [schema]. *)
 val validate : ('meta, 'ctor, 'ty) t -> input -> validation_error
+
+(** [decode_and_validate schema input] returns the decoded and validated value
+    of type ['ty] by decoding the [input] using the [schema] and running its
+    validators.
+
+    The returned error is a {!type:validation_error}. If a field fails to
+    decode, the error of that field is the decode error. If a field decodes but
+    fails to validate, then the error is the validation error.
+
+    Use [decode_and_validate] to combine the functions [decode] and [validate]
+    and to either end up with the decoded value or all errors that happened
+    during the decoding and validation steps. *)
+val decode_and_validate
+  :  ('meta, 'ctor, 'ty) t
+  -> input
+  -> ('ty, validation_error) Result.t