### List Output Files and Dependencies

Source: https://context7.com/ashima/atdgen/llms.txt

Utility commands to list generated files or create Make-compatible dependency lists.

```bash
# List all files that would be generated
atdgen -list example.atd
# Output: example_t.mli example_t.ml example_b.mli example_b.ml example_j.mli example_j.ml example_v.mli example_v.ml

# Generate Make dependencies
atdgen -dep example.atd
# Output:
# example_t.mli: example.atd
# example_t.ml: example.atd
# example_b.mli: example.atd
# example_b.ml: example.atd
# ...
```

--------------------------------

### Serialize and Deserialize Data with Atdgen

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates JSON and Biniou serialization/deserialization, along with direct file I/O using generated modules.

```ocaml
(* Assuming we have profile.atd:
   type profile = {
     id : string;
     email : string;
     ~email_validated : bool;
     name : string;
     ?real_name : string option;
   }
*)

(* Create a profile value *)
let my_profile : Profile_t.profile = {
  id = "user123";
  email = "user@example.com";
  email_validated = true;
  name = "John Doe";
  real_name = Some "Jonathan Doe";
}

(* JSON serialization *)
let json_str = Profile_j.string_of_profile my_profile
(* Result: {"id":"user123","email":"user@example.com","email_validated":true,"name":"John Doe","real_name":"Jonathan Doe"} *)

(* JSON deserialization *)
let parsed_profile = Profile_j.profile_of_string json_str

(* Biniou serialization *)
let bin_str = Profile_b.string_of_profile my_profile

(* Biniou deserialization *)
let parsed_profile = Profile_b.profile_of_string bin_str

(* Direct file I/O *)
let () = Ag_util.Json.to_file Profile_j.write_profile "profile.json" my_profile
let loaded = Ag_util.Json.from_file Profile_j.read_profile "profile.json"
```

--------------------------------

### Biniou I/O Functions: Reading and Writing Files

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading and writing biniou-encoded data from/to files using Ag_util.Biniou functions.

```ocaml
(* Reading biniou data from file *)
let profile = Ag_util.Biniou.from_file Profile_b.read_profile "data.bin"
```

```ocaml
(* Writing biniou data to file *)
let () = Ag_util.Biniou.to_file Profile_b.write_profile "output.bin" profile
```

--------------------------------

### Biniou I/O Functions: Reading and Writing Channels

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading and writing biniou-encoded data from/to channels using Ag_util.Biniou functions.

```ocaml
(* Reading from channel *)
let ic = open_in_bin "data.bin" in
let profile = Ag_util.Biniou.from_channel Profile_b.read_profile ic in
close_in ic
```

```ocaml
(* Writing to channel *)
let oc = open_out_bin "output.bin" in
Ag_util.Biniou.to_channel Profile_b.write_profile oc profile;
close_out oc
```

--------------------------------

### Migrate Data Formats

Source: https://context7.com/ashima/atdgen/llms.txt

Shows how to handle backward-compatible data evolution by converting between different ATD-defined versions.

```ocaml
(* Old format (format_v1.atd):
   type t = {
     a : int option;
     b : bool;
     ?c : int option;
     ~d : float;
   }
*)

(* New format (format_v2.atd):
   type t = {
     a : int option;
     ?c : int option;
     ~d : float;
     ~e : string list;  (* new optional field *)
   }
*)

(* Create old format data *)
let old_data = {
  Format_v1.a = Some 1;
  b = true;
  c = Some 3;
  d = 4.0;
}

(* Convert old to new format via binary serialization *)
let convert x =
  Format_v2.t_of_string (Format_v1.string_of_t ~len:100 x)

let new_data = convert old_data
(* new_data.e defaults to [] since it wasn't in old format *)

(* Write old format to stdout *)
let print_data () =
  let ob = Bi_outbuf.create_channel_writer stdout in
  Format_v1.write_t ob old_data;
  Bi_outbuf.flush_channel_writer ob

(* Read new format and upgrade *)
let upgrade () =
  let ib = Bi_inbuf.from_channel stdin in
  let x = Format_v2.read_t ib in
  let ob = Bi_outbuf.create_channel_writer stdout in
  Format_v2.write_t ob x;
  Bi_outbuf.flush_channel_writer ob
```

--------------------------------

### JSON I/O Functions: Reading and Writing Files

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading and writing JSON data from/to files using Ag_util.Json functions.

```ocaml
(* Reading JSON from file *)
let profile = Ag_util.Json.from_file Profile_j.read_profile "data.json"
```

```ocaml
(* Writing JSON to file *)
let () = Ag_util.Json.to_file Profile_j.write_profile "output.json" profile
```

--------------------------------

### JSON I/O Functions: Reading and Writing Strings

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading and writing JSON data to/from strings using Ag_util.Json functions.

```ocaml
(* Reading JSON from string *)
let profile = Ag_util.Json.from_string Profile_j.read_profile json_string
```

```ocaml
(* Writing JSON to string *)
let json_string = Ag_util.Json.to_string Profile_j.write_profile profile
```

--------------------------------

### Generate Biniou Serializers

Source: https://context7.com/ashima/atdgen/llms.txt

Generates OCaml code for the Biniou binary format, including read and write functions.

```bash
# Generate biniou serialization code
atdgen -t example.atd
atdgen -b example.atd

# This produces:
# - example_b.mli (biniou interface)
# - example_b.ml (biniou implementation)

# Generated functions include:
# val write_profile : Bi_outbuf.t -> profile -> unit
# val read_profile : Bi_inbuf.t -> profile
# val string_of_profile : ?len:int -> profile -> string
# val profile_of_string : ?pos:int -> string -> profile
```

--------------------------------

### Generate Biniou Serializers (-b)

Source: https://context7.com/ashima/atdgen/llms.txt

Produces OCaml serializers and deserializers for the biniou binary format.

```APIDOC
## CLI Command: atdgen -b

### Description
Generates biniou serialization code (`*_b.mli` and `*_b.ml`). Includes functions for reading and writing data in the biniou format.

### Usage
`atdgen -b <file.atd>`
```

--------------------------------

### Biniou Annotations for Integer and Array Representations

Source: https://context7.com/ashima/atdgen/llms.txt

Controls binary format representation for integers (e.g., uvint, int8) and specifies table format for arrays of records.

```atd
(* Integer representations *)
type t = {
  id : int <ocaml repr="int64"> <biniou repr="int64">;
  count : int <biniou repr="uvint">;
  small : int <biniou repr="int8">;
  medium : int <biniou repr="int16">;
}
```

```atd
(* Table format for arrays of records *)
type item = {
  id : int;
  data : string list;
}
type items = item list <biniou repr="table">
```

--------------------------------

### JSON I/O Functions: Stream and List Processing

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading a stream of JSON values from a file and writing a list of JSON values to a file.

```ocaml
(* Reading stream of JSON values from file *)
let stream = Ag_util.Json.stream_from_file Profile_j.read_profile "items.json" in
Stream.iter process_item stream
```

```ocaml
(* Writing list of values to file *)
let () = Ag_util.Json.list_to_file Profile_j.write_profile "items.json" profiles
```

--------------------------------

### JSON I/O Functions: Channel List Processing

Source: https://context7.com/ashima/atdgen/llms.txt

Demonstrates reading a list of JSON values from a channel, including custom channel closing logic.

```ocaml
(* Reading list of JSON values from channel *)
let ic = open_in "items.json" in
let profiles = Ag_util.Json.list_from_channel
  ~fin:(fun () -> close_in_noerr ic)
  Profile_j.read_profile ic
```

--------------------------------

### Generate OCaml Type Definitions

Source: https://context7.com/ashima/atdgen/llms.txt

Produces OCaml type definitions from an ATD file without serialization logic.

```bash
# Generate type definitions only
atdgen -t example.atd

# This produces:
# - example_t.mli (OCaml interface)
# - example_t.ml (OCaml implementation)

# Input: example.atd
# type profile = {
#   id : string;
#   email : string;
#   ~email_validated : bool;
#   name : string;
#   ?real_name : string option;
#   ~about_me : string list;
# }
```

--------------------------------

### Generate JSON Serializers (-j)

Source: https://context7.com/ashima/atdgen/llms.txt

Produces OCaml serializers and deserializers for JSON format compatible with yojson.

```APIDOC
## CLI Command: atdgen -j

### Description
Generates JSON serialization code (`*_j.mli` and `*_j.ml`). Supports various flags for standard JSON, default values, and strict field handling.

### Options
- `-j-std`: Standard JSON output (no yojson extensions)
- `-j-defaults`: Force output of default values
- `-j-strict-fields`: Handle unknown JSON fields strictly
- `-j-custom-fields`: Provide a custom handler for unknown fields
```

--------------------------------

### Generate JSON Serializers

Source: https://context7.com/ashima/atdgen/llms.txt

Generates JSON serialization code compatible with the Yojson library, with options for standard output, defaults, and field handling.

```bash
# Generate JSON serialization code
atdgen -t example.atd
atdgen -j example.atd

# For standard JSON output (no yojson extensions)
atdgen -j -j-std example.atd

# Force output of default values in JSON
atdgen -j -j-defaults example.atd

# Handle unknown JSON fields strictly
atdgen -j -j-strict-fields example.atd

# Custom handler for unknown fields
atdgen -j -j-custom-fields 'fun loc s -> Printf.printf "Unknown: %s\n" s' example.atd
```

--------------------------------

### JSON I/O Functions: Custom Error Handling

Source: https://context7.com/ashima/atdgen/llms.txt

Configures a custom handler for unknown fields encountered during JSON parsing, printing a warning to stderr.

```ocaml
(* Custom error handling for unknown fields *)
let () = Ag_util.Json.unknown_field_handler :=
  fun loc field -> Printf.eprintf "Warning: unknown field %s at %s\n" field loc
```

--------------------------------

### Define Record Types

Source: https://context7.com/ashima/atdgen/llms.txt

ATD syntax for defining records with required, optional, and default-valued fields.

```text
(* ATD definition *)
type profile = {
  id : string;                      (* required field *)
  email : string;                   (* required field *)
  ~email_validated : bool;          (* optional with default false *)
  name : string;                    (* required field *)
  ?real_name : string option;       (* optional field *)
  ~about_me : string list;          (* optional with default [] *)
  ?gender : gender option;          (* optional field *)
  ?date_of_birth : date option;     (* optional field *)
}

type gender = [ Female | Male ]

type date = {
  year : int;
  month : int;
  day : int;
}
```

--------------------------------

### Generate Validators

Source: https://context7.com/ashima/atdgen/llms.txt

Produces validator functions based on ocaml validator annotations in the ATD file.

```bash
# Generate validator code
atdgen -t example.atd
atdgen -v example.atd

# Input ATD with validators:
# type month = int <ocaml validator="fun x -> x >= 1 && x <= 12">
# type day = int <ocaml validator="fun x -> x >= 1 && x <= 31">
# type date = {
#   year : int;
#   month : month;
#   day : day;
# } <ocaml validator="Date_util.validate_date">

# Generated:
# val validate_month : month -> bool
# val validate_day : day -> bool
# val validate_date : date -> bool
```

--------------------------------

### JSON Annotations for Field Naming and Variants

Source: https://context7.com/ashima/atdgen/llms.txt

Controls JSON field naming, variant representation, and how association lists are serialized as JSON objects.

```atd
(* Custom JSON field names *)
type profile = {
  id <json name="ID"> : int;
  username : string;
  background_color : color;
}
```

```atd
(* JSON variant names *)
type color = [
    Black <json name="black">
  | White <json name="white">
  | Grey <json name="grey">
]
```

```atd
(* Association lists as JSON objects *)
type counts = (string * int) list <json repr="object">
(* JSON: {"bob": 3, "john": 1408} instead of [["bob", 3], ["john", 1408]] *)
```

--------------------------------

### Define Tuple Types in ATD

Source: https://context7.com/ashima/atdgen/llms.txt

Defines fixed-length heterogeneous collections using tuple syntax. Supports basic tuples and tuples with default values.

```atd
(* Basic tuple *)
type point = (int * int)
```

```atd
(* Tuple with defaults *)
type extended_tuple = (
  int
  * float
  * <ocaml default="true"> : bool
  * <ocaml default="None"> : int option
  * string
  * <ocaml default="[]"> : string list
)
```

--------------------------------

### OCaml Annotations for Field Naming and Mutability

Source: https://context7.com/ashima/atdgen/llms.txt

Controls OCaml type mappings, including custom field names, mutable fields, and default values.

```atd
(* Custom OCaml field names *)
type profile = {
  id <ocaml name="profile_id"> : int;
  username : string;
}
```

```atd
(* Mutable fields *)
type counter = {
  total <ocaml mutable> : int;
  errors <ocaml mutable> : int;
}
```

```atd
(* Default values *)
type ford_t = {
  year : int;
  ~color <ocaml default="`Black"> : color;
}
```

```atd
(* Array representation for lists *)
type data = {
  items : string list <ocaml repr="array">;
}
```

```atd
(* Predefined types from other modules *)
type message <ocaml predef> = {
  from : string;
  subject : string;
  body : string;
}
```

```atd
(* Abstract types from other modules *)
type point <ocaml from="Part1"> = abstract
```

```atd
(* Validators *)
type positive = int <ocaml validator="fun x -> x > 0">
```

--------------------------------

### Documentation Annotations in ATD

Source: https://context7.com/ashima/atdgen/llms.txt

Embeds documentation strings within ATD files, which are used to generate ocamldoc comments for types and fields.

```atd
<doc text="Type definitions for family trees">

type person_id
  <doc text="Unique identifier for a person in the tree"> = int

type gender = [
  | F <doc text="female">
  | M <doc text="male">
] <doc text="Gender classification">

type person = {
  person_id : person_id;
  name : string;
  ?biological_gender <doc text="Biological gender used for procreating"> : gender option;
}
```

--------------------------------

### Generate OCaml Type Definitions (-t)

Source: https://context7.com/ashima/atdgen/llms.txt

Produces OCaml type definitions from an ATD file without serialization code.

```APIDOC
## CLI Command: atdgen -t

### Description
Generates OCaml type definitions (`*_t.mli` and `*_t.ml`) from an ATD file. This is the base step for other generation tasks.

### Usage
`atdgen -t <file.atd>`
```

--------------------------------

### Generate Validators (-v)

Source: https://context7.com/ashima/atdgen/llms.txt

Produces OCaml validator functions based on ATD annotations.

```APIDOC
## CLI Command: atdgen -v

### Description
Generates validator functions (`*_v.mli` and `*_v.ml`) based on `<ocaml validator="...">` annotations within the ATD file.

### Usage
`atdgen -v <file.atd>`
```

--------------------------------

### Define Variant Types

Source: https://context7.com/ashima/atdgen/llms.txt

ATD syntax for defining sum types, including polymorphic variants, classic variants, and variants with arguments.

```text
(* Polymorphic variants (default) *)
type color = [ Black | White | Grey ]

(* Classic OCaml variants *)
type fruit = [ Apple | Orange ] <ocaml repr="classic">

(* Variants with arguments *)
type test_variant =
  [ Case1
  | Case2 of int
  | Case3 of string
  | Case4 of test_variant list
  ]
```

--------------------------------

### Define Type Aliases and Generics in ATD

Source: https://context7.com/ashima/atdgen/llms.txt

Defines type aliases for simpler type names and parametric (generic) types for reusable type structures.

```atd
(* Simple alias *)
type intopt = int option
```

```atd
(* Parametric types *)
type 'a abs1 = 'a list
```

```atd
type ('x, 'y) poly = {
  fst : 'x list;
  snd : ('x, 'y) poly option;
}
```

```atd
(* Specialized integer types *)
type int8 = int <biniou repr="int8">
```

```atd
type char = int <ocaml repr="char"> <biniou repr="int8">
```

```atd
type int32 = int <ocaml repr="int32"> <biniou repr="int32">
```

```atd
type int64 = int <ocaml repr="int64"> <biniou repr="int64">
```

--------------------------------

### Validate Data with Generated Functions

Source: https://context7.com/ashima/atdgen/llms.txt

Utilizes generated validator functions and creation helpers to ensure data integrity.

```ocaml
(* ATD definition with validators:
   type month = int <ocaml validator="fun x -> x >= 1 && x <= 12">
   type day = int <ocaml validator="fun x -> x >= 1 && x <= 31">
   type date = {
     year : int;
     month : month;
     day : day;
   } <ocaml validator="Date_util.validate_date">
*)

(* Using the generated validators *)
let valid_date : Date_t.date = {
  year = 2023;
  month = 12;
  day = 25;
}

let invalid_date : Date_t.date = {
  year = 2023;
  month = 13;  (* Invalid: month > 12 *)
  day = 25;
}

(* Validate data *)
let () =
  if Date_v.validate_date valid_date then
    print_endline "Valid date"
  else
    print_endline "Invalid date"

let () =
  if Date_v.validate_date invalid_date then
    print_endline "Valid date"
  else
    print_endline "Invalid date"  (* This will print *)

(* Create records with defaults using generated create functions *)
let date = Date_v.create_date ~year:2023 ~month:6 ~day:15 ()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.