```ocaml
# (* preparation *);;
# open Kxclib;;
# open Doctests_utils.Test_utils;;
```

## Basic OCaml Datatype Declaration Generation

`Bindoj.Type_desc.type_decl` is a type meaning type declaration and there are
record type and variant type as type kinds. The following are datatype
declaration generation examples: `student` of record type and `person` of
variant type. `Bindoj.Type_desc.type_declaration_of_type_decl` is a function
converting `Bindoj.Type_desc.type_decl` to `type_declaration`.

### simple record type : student
```ocaml
# open Bindoj.Type_desc;;
# #show_type type_decl;;
type nonrec type_decl =
  type_decl = {
  td_name : string;
  td_configs : [ `type_decl ] configs;
  td_kind : type_decl_kind;
  td_doc : Bindoj_base.Runtime.doc;
}
# let student_desc =
    record_decl "student" [
      record_field "admission_year" (Coretype.mk_prim `int);
      record_field "full_name" (Coretype.mk_prim `string);
    ];;
val student_desc : type_decl =
  {td_name = "student"; td_configs = Bindoj.Type_desc.Configs.[];
   td_kind =
    Record_decl
     [{rf_name = "admission_year";
       rf_type =
        `direct
          {Bindoj.Type_desc.Coretype.ct_desc =
            Bindoj.Type_desc.Coretype.Prim `int;
           ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
       rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
      {rf_name = "full_name";
       rf_type =
        `direct
          {Bindoj.Type_desc.Coretype.ct_desc =
            Bindoj.Type_desc.Coretype.Prim `string;
           ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
       rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
   td_doc = `nodoc}
```

### simple variant type : person
```ocaml
# open Bindoj_gen.Json_codec;;
# #show_type type_decl;;
type nonrec type_decl =
  type_decl = {
  td_name : string;
  td_configs : [ `type_decl ] configs;
  td_kind : type_decl_kind;
  td_doc : Bindoj_runtime.doc;
}
# let person_desc =
    variant_decl "person" [
      variant_constructor "Anonymous" `no_param;
      variant_constructor "With_id" (`tuple_like [variant_argument @@ Coretype.mk_prim `int]);
      variant_constructor "Student" (`inline_record [
        record_field "student_id" (Coretype.mk_prim `int);
        record_field "name" (Coretype.mk_prim `string);
      ]);
      variant_constructor "Teacher" (`inline_record [
        record_field "faculty_id" (Coretype.mk_prim `int);
        record_field "name" (Coretype.mk_prim `string);
        record_field "department" (Coretype.mk_prim `string);
      ])
    ];;
val person_desc : type_decl =
  {td_name = "person"; td_configs = Bindoj.Type_desc.Configs.[];
   td_kind =
    Variant_decl
     [{vc_name = "Anonymous"; vc_param = `no_param;
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "With_id";
       vc_param =
        `tuple_like
          [{va_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            va_configs = Bindoj.Type_desc.Configs.[]; va_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "Student";
       vc_param =
        `inline_record
          [{rf_name = "student_id";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "name";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "Teacher";
       vc_param =
        `inline_record
          [{rf_name = "faculty_id";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "name";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "department";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc}];
   td_doc = `nodoc}
```

### `Bindoj.Caml_gen`
```ocaml
# #show_module Bindoj.Caml_gen;;
module Caml_gen = Bindoj.Versioned.V0.Caml_gen
module Caml_gen :
  sig
    module Caml = Bindoj.Versioned.V0.Caml
    module Datatype = Bindoj_gen.Caml_datatype
    module Json_codec = Bindoj_gen.Json_codec
    module Type_module : sig ... end
  end
# #show_module Bindoj.Caml_gen.Datatype;;
module Datatype = Bindoj_gen.Caml_datatype
module Datatype = Bindoj_gen.Caml_datatype
module Datatype :
  sig
    val type_declaration_of_type_decl :
      ?type_name:string ->
      ?attrs:Ppxlib.attribute list ->
      type_decl -> Bindoj.Versioned.V0.Caml.type_declaration
    val gen_reflect :
      ?codec:Coretype.codec ->
      type_decl -> Bindoj.Versioned.V0.Caml.value_binding
    val gen_structure :
      ?type_name:string ->
      ?refl:bool ->
      ?attrs:Ppxlib.attribute list ->
      ?codec:Coretype.codec ->
      ?generators:(?codec:Coretype.codec -> type_decl -> Ppxlib.structure)
                  list ->
      ?type_decl:[ `expr of Ppxlib.expression | `path of string ] ->
      type_decl -> Ppxlib.structure
    val gen_reflect_signature :
      ?refl_type_abbr:string ->
      ?codec:Coretype.codec -> type_decl -> Ppxlib.value_description
    val gen_signature :
      ?type_name:string ->
      ?refl:bool ->
      ?attrs:Ppxlib.attribute list ->
      ?codec:Coretype.codec ->
      ?generators:(?codec:Coretype.codec ->
                   type_decl -> Bindoj.Versioned.V0.Caml.signature)
                  list ->
      ?type_decl:bool ->
      ?refl_type_abbr:string ->
      ?type_decl_type_abbr:string ->
      ?typed_type_decl_type_abbr:string ->
      type_decl -> Bindoj.Versioned.V0.Caml.signature
  end
# #show_module Bindoj.Caml;;
module Caml = Bindoj.Versioned.V0.Caml
module Caml :
  sig
    module Ppxlib = Ppxlib
    module Astlib = Astlib
    module Emitter = Bindoj_gen.Emitter
    module CommonTypes : sig ... end
    type signature_item = CommonTypes.signature_item
    type signature = CommonTypes.signature
    type structure_item = CommonTypes.structure_item
    type structure = structure_item list
    type value_binding = CommonTypes.value_binding
    type type_declaration = CommonTypes.type_declaration
    type core_type = CommonTypes.core_type
    module Structure : sig ... end
    module Signature : sig ... end
  end
```

```ocaml
# Bindoj.(
   let student_decl = Caml_gen.Datatype.type_declaration_of_type_decl student_desc in
   Caml.Structure.([declaration student_decl] |> printf "%a@?" pp_caml));;
type student = {
  admission_year: int ;
  full_name: string }
- : unit = ()
# Bindoj.(
   let person_decl = Caml_gen.Datatype.type_declaration_of_type_decl person_desc in
   Caml.Structure.([declaration person_decl] |> printf "%a@?" pp_caml));;
type person =
  | Anonymous
  | With_id of int
  | Student of {
  student_id: int ;
  name: string }
  | Teacher of {
  faculty_id: int ;
  name: string ;
  department: string }
- : unit = ()
```

```ocaml
# (* preparation *);;
# open Kxclib;;
# open Doctests_utils.Test_utils;;
```

### simple polymorphic variant type : int_or_string
```ocaml
# open Bindoj.Type_desc;;
# open Bindoj.Caml_gen;;
# open Bindoj.Caml_gen.Datatype;;

# let int_or_string_desc =
    variant_decl "int_or_string" [
      variant_constructor "int" (`tuple_like [variant_argument @@ Coretype.mk_prim `int]);
      variant_constructor "string" (`tuple_like [variant_argument @@ Coretype.mk_prim `string]);
    ] ~configs:[
      Caml_config.variant_type `polymorphic
    ];;
val int_or_string_desc : type_decl =
  {td_name = "int_or_string";
   td_configs =
    Bindoj.Type_desc.Configs.(::)
     (Bindoj_typedesc.Type_desc.Config_caml_variant_type `polymorphic,
      Bindoj.Type_desc.Configs.[]);
   td_kind =
    Variant_decl
     [{vc_name = "int";
       vc_param =
        `tuple_like
          [{va_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            va_configs = Bindoj.Type_desc.Configs.[]; va_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "string";
       vc_param =
        `tuple_like
          [{va_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            va_configs = Bindoj.Type_desc.Configs.[]; va_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc}];
   td_doc = `nodoc}

# Bindoj.(
   let int_or_string_decl = Caml_gen.Datatype.type_declaration_of_type_decl int_or_string_desc in
   Caml.Structure.([declaration int_or_string_decl] |> printf "%a@?" pp_caml));;
type int_or_string = [ `int of int  | `string of string ]
- : unit = ()
```

```ocaml
# (* preparation *);;
# open Kxclib;;
# open Doctests_utils.Test_utils;;
```

## Basic OCaml JSON Codec Generation

`Bindoj.Caml_gen.Json_codec.gen_encoder`/`Bindoj.Caml_gen.Json_codec.gen_decoder`
are functions generating JSON encoder/decoder from
`Bindoj.Type_desc.type_declaration`. The following are JSON encoder/decoder
generation examples: `student` of record type and `person` of variant type.

### simple record type : student
```ocaml
# open Bindoj.Type_desc;;
# #show_type type_decl;;
type nonrec type_decl =
  type_decl = {
  td_name : string;
  td_configs : [ `type_decl ] configs;
  td_kind : type_decl_kind;
  td_doc : Bindoj_base.Runtime.doc;
}
# let student_desc =
    record_decl "student" [
      record_field "admission_year" (Coretype.mk_prim `int);
      record_field "full_name" (Coretype.mk_prim `string);
    ];;
val student_desc : type_decl =
  {td_name = "student"; td_configs = Bindoj.Type_desc.Configs.[];
   td_kind =
    Record_decl
     [{rf_name = "admission_year";
       rf_type =
        `direct
          {Bindoj.Type_desc.Coretype.ct_desc =
            Bindoj.Type_desc.Coretype.Prim `int;
           ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
       rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
      {rf_name = "full_name";
       rf_type =
        `direct
          {Bindoj.Type_desc.Coretype.ct_desc =
            Bindoj.Type_desc.Coretype.Prim `string;
           ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
       rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
   td_doc = `nodoc}
```

### simple variant type : person
```ocaml
# open Bindoj.Caml_gen.Json_codec;;
# #show_type type_decl;;
type nonrec type_decl =
  type_decl = {
  td_name : string;
  td_configs : [ `type_decl ] configs;
  td_kind : type_decl_kind;
  td_doc : Bindoj_runtime.doc;
}
# let person_desc =
    variant_decl "person" [
      variant_constructor "Anonymous" `no_param;
      variant_constructor "With_id" (`tuple_like [variant_argument @@ Coretype.mk_prim `int]);
      variant_constructor "Student" (`inline_record [
        record_field "student_id" (Coretype.mk_prim `int);
        record_field "name" (Coretype.mk_prim `string);
      ]);
      variant_constructor "Teacher" (`inline_record [
        record_field "faculty_id" (Coretype.mk_prim `int);
        record_field "name" (Coretype.mk_prim `string);
        record_field "department" (Coretype.mk_prim `string);
      ])
    ];;
val person_desc : type_decl =
  {td_name = "person"; td_configs = Bindoj.Type_desc.Configs.[];
   td_kind =
    Variant_decl
     [{vc_name = "Anonymous"; vc_param = `no_param;
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "With_id";
       vc_param =
        `tuple_like
          [{va_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            va_configs = Bindoj.Type_desc.Configs.[]; va_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "Student";
       vc_param =
        `inline_record
          [{rf_name = "student_id";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "name";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc};
      {vc_name = "Teacher";
       vc_param =
        `inline_record
          [{rf_name = "faculty_id";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `int;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "name";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc};
           {rf_name = "department";
            rf_type =
             `direct
               {Bindoj.Type_desc.Coretype.ct_desc =
                 Bindoj.Type_desc.Coretype.Prim `string;
                ct_configs = Bindoj_typedesc.Type_desc.Configs.[]};
            rf_configs = Bindoj.Type_desc.Configs.[]; rf_doc = `nodoc}];
       vc_configs = Bindoj.Type_desc.Configs.[]; vc_doc = `nodoc}];
   td_doc = `nodoc}
```

### `Bindoj.Caml_gen.Json_codec`
```ocaml
# Bindoj.(
   let student_encoder = Caml_gen.Json_codec.gen_json_encoder student_desc in
   Caml.Structure.([binding student_encoder] |> printf "%a@?" pp_caml));;
let student_to_json =
  (fun { admission_year = x0; full_name = x1 } ->
     `obj
       [("admissionYear", (int_to_json x0));
       ("fullName", (string_to_json x1))] : student -> Kxclib.Json.jv)
  [@@warning "-39"]
- : unit = ()
# Bindoj.(
   let student_decoder = Caml_gen.Json_codec.gen_json_decoder_result student_desc in
   Caml.Structure.([binding student_decoder] |> printf "%a@?" pp_caml));;
let student_of_json' =
  (fun ?(path= []) ->
     fun x ->
       ((let rec of_json_impl path __bindoj_orig =
           match __bindoj_orig with
           | `obj param ->
               let (>>=) = Result.bind in
               (((List.assoc_opt "admissionYear" param) |>
                   (Option.to_result
                      ~none:("mandatory field 'admissionYear' does not exist",
                              path)))
                  >>= (int_of_json' ((`f "admissionYear") :: path)))
                 >>=
                 ((fun x0 ->
                     (((List.assoc_opt "fullName" param) |>
                         (Option.to_result
                            ~none:("mandatory field 'fullName' does not exist",
                                    path)))
                        >>= (string_of_json' ((`f "fullName") :: path)))
                       >>=
                       (fun x1 -> Ok { admission_year = x0; full_name = x1 })))
           | jv ->
               Error
                 ((Printf.sprintf
                     "an object is expected for a record value, but the given is of type '%s'"
                     (let open Kxclib.Json in
                        string_of_jv_kind (classify_jv jv))), path) in
         of_json_impl) path x) |>
         (Result.map_error
            (fun (msg, path) ->
               (msg, path,
                 (`with_warning
                    ("not considering any config if exists",
                      (`named
                         ("Student",
                           (`object_of
                              [`mandatory_field ("admissionYear", `integral);
                              `mandatory_field ("fullName", `string)])))))))) :
  student Bindoj_runtime.json_full_decoder)[@@warning "-39"]
- : unit = ()
# Bindoj.(
   let person_encoder = Caml_gen.Json_codec.gen_json_encoder person_desc in
   Caml.Structure.([binding person_encoder] |> printf "%a@?" pp_caml));;
let person_to_json =
  (function
   | Anonymous -> `obj [("kind", (`str "anonymous"))]
   | With_id x0 ->
       `obj [("kind", (`str "with-id")); ("value", (int_to_json x0))]
   | Student { student_id = x0; name = x1 } ->
       `obj
         [("kind", (`str "student"));
         ("studentId", (int_to_json x0));
         ("name", (string_to_json x1))]
   | Teacher { faculty_id = x0; name = x1; department = x2 } ->
       `obj
         [("kind", (`str "teacher"));
         ("facultyId", (int_to_json x0));
         ("name", (string_to_json x1));
         ("department", (string_to_json x2))] : person -> Kxclib.Json.jv)
  [@@warning "-39"]
- : unit = ()
# Bindoj.(
   let person_decoder = Caml_gen.Json_codec.gen_json_decoder_result person_desc in
   Caml.Structure.([binding person_decoder] |> printf "%a@?" pp_caml));;
let person_of_json' =
  (fun ?(path= []) ->
     fun x ->
       ((let rec of_json_impl path __bindoj_orig =
           match Kxclib.Jv.pump_field "kind" __bindoj_orig with
           | `obj (("kind", `str "anonymous")::_) -> Ok Anonymous
           | `obj (("kind", `str "with-id")::param) ->
               (match List.assoc_opt "value" param with
                | Some arg ->
                    let (>>=) = Result.bind in
                    (int_of_json' ((`f "value") :: path) arg) >>=
                      ((fun x0 -> Ok (With_id x0)))
                | None ->
                    Error ("mandatory field 'value' does not exist", path))
           | `obj (("kind", `str "student")::param) ->
               let (>>=) = Result.bind in
               (((List.assoc_opt "studentId" param) |>
                   (Option.to_result
                      ~none:("mandatory field 'studentId' does not exist",
                              path)))
                  >>= (int_of_json' ((`f "studentId") :: path)))
                 >>=
                 ((fun x0 ->
                     (((List.assoc_opt "name" param) |>
                         (Option.to_result
                            ~none:("mandatory field 'name' does not exist",
                                    path)))
                        >>= (string_of_json' ((`f "name") :: path)))
                       >>=
                       (fun x1 -> Ok (Student { student_id = x0; name = x1 }))))
           | `obj (("kind", `str "teacher")::param) ->
               let (>>=) = Result.bind in
               (((List.assoc_opt "facultyId" param) |>
                   (Option.to_result
                      ~none:("mandatory field 'facultyId' does not exist",
                              path)))
                  >>= (int_of_json' ((`f "facultyId") :: path)))
                 >>=
                 ((fun x0 ->
                     (((List.assoc_opt "name" param) |>
                         (Option.to_result
                            ~none:("mandatory field 'name' does not exist",
                                    path)))
                        >>= (string_of_json' ((`f "name") :: path)))
                       >>=
                       (fun x1 ->
                          (((List.assoc_opt "department" param) |>
                              (Option.to_result
                                 ~none:("mandatory field 'department' does not exist",
                                         path)))
                             >>=
                             (string_of_json' ((`f "department") :: path)))
                            >>=
                            (fun x2 ->
                               Ok
                                 (Teacher
                                    {
                                      faculty_id = x0;
                                      name = x1;
                                      department = x2
                                    })))))
           | `obj (("kind", `str discriminator_value)::_) ->
               Error
                 ((Printf.sprintf
                     "given discriminator field value '%s' is not one of [ 'anonymous', 'with-id', 'student', 'teacher' ]"
                     discriminator_value), ((`f "kind") :: path))
           | `obj (("kind", jv)::_) ->
               Error
                 ((Printf.sprintf
                     "a string is expected for a variant discriminator, but the given is of type '%s'"
                     (let open Kxclib.Json in
                        string_of_jv_kind (classify_jv jv))), ((`f "kind") ::
                   path))
           | `obj _ ->
               Error ("discriminator field 'kind' does not exist", path)
           | jv ->
               Error
                 ((Printf.sprintf
                     "an object is expected for a variant value, but the given is of type '%s'"
                     (let open Kxclib.Json in
                        string_of_jv_kind (classify_jv jv))), path) in
         of_json_impl) path x) |>
         (Result.map_error
            (fun (msg, path) ->
               (msg, path,
                 (`with_warning
                    ("not considering any config if exists",
                      (`named
                         ("Person",
                           (`anyone_of
                              [`object_of
                                 [`mandatory_field
                                    ("kind", (`exactly (`str "anonymous")))];
                              `object_of
                                [`mandatory_field
                                   ("kind", (`exactly (`str "with-id")));
                                `mandatory_field ("value", `integral)];
                              `object_of
                                [`mandatory_field
                                   ("kind", (`exactly (`str "student")));
                                `mandatory_field ("studentId", `integral);
                                `mandatory_field ("name", `string)];
                              `object_of
                                [`mandatory_field
                                   ("kind", (`exactly (`str "teacher")));
                                `mandatory_field ("facultyId", `integral);
                                `mandatory_field ("name", `string);
                                `mandatory_field ("department", `string)]])))))))) :
  person Bindoj_runtime.json_full_decoder)[@@warning "-39"]
- : unit = ()
```

Docs

ocaml_datatype_basic.md

ocaml_datatype_polymorphic-variant.md

ocaml_json_codec.md

dune build @doc

Coverage

Example

Dev Example (apidir openapi)