INI parser and encoder using bytesrw.

This module provides functions to parse and encode INI files using the bytesrw streaming I/O library. It implements Python's configparser semantics for maximum compatibility.

Basic Usage

(* Define your configuration type and codec *)
let config_codec = Init.Document.(
  obj (fun server -> server)
  |> section "server" server_codec ~enc:Fun.id
  |> finish
)

(* Decode from a string *)
match Init_bytesrw.decode_string config_codec ini_text with
| Ok config -> (* use config *)
| Error msg -> (* handle error *)

(* Encode back to a string *)
match Init_bytesrw.encode_string config_codec config with
| Ok text -> (* write text *)
| Error msg -> (* handle error *)

Python Compatibility

This parser implements the same semantics as Python's configparser module. Configuration files that work with Python will work here, and vice versa.

Supported Syntax

# Comments start with # or ;
; This is also a comment

[section]
key = value
key2 : value2              ; Both = and : are delimiters
key3=no spaces needed

[multiline]
long_value = This is a long value
    that continues on indented lines
    for as long as needed

[types]
integer = 42
float = 3.14
boolean = yes              ; Also: true, on, 1, no, false, off, 0
list = a, b, c, d

Edge Cases and Gotchas

• Section names are case-sensitive: [Server] and [server] are different.
• Option names are case-insensitive: Port and port are the same.
• Whitespace is trimmed from keys and values automatically.
• Empty values are allowed: key = gives an empty string.
• Comments are NOT preserved during round-trips (matching Python).
• Inline comments are disabled by default: key = value ; comment gives the value "value ; comment" unless you configure inline_comment_prefixes.

Parser Configuration

Configure the parser to match different INI dialects. The default configuration matches Python's ConfigParser.

Decoding

Parse INI data into OCaml values. All decode functions return Result.t - they never raise exceptions for parse errors.

let ini_text = {|
  [server]
  host = localhost
  port = 8080
|} in
Init_bytesrw.decode_string config_codec ini_text

Encoding

Serialize OCaml values to INI format.

let config = { server = { host = "localhost"; port = 8080 } } in
match Init_bytesrw.encode_string config_codec config with
| Ok text -> print_endline text
| Error msg -> failwith msg

[server]
host = localhost
port = 8080

Layout Preservation

When decoding with ~layout:true, whitespace and comment positions are preserved in the Init.Meta.t values attached to each element. When re-encoding, this information is used to reproduce the original formatting as closely as possible.

Limitations:

• Comments are NOT preserved (matching Python's behavior).
• Whitespace within values may be normalized.
• The output may differ slightly from the input in edge cases.

Performance tip: For maximum performance when you don't need layout preservation, use ~layout:false ~locs:false (the default). Enabling ~locs:true improves error messages at a small cost.

Examples

Simple Configuration

type config = { debug : bool; port : int }

let codec = Init.Document.(
  let section = Init.Section.(
    obj (fun debug port -> { debug; port })
    |> mem "debug" Init.bool ~dec_absent:false ~enc:(fun c -> c.debug)
    |> mem "port" Init.int ~dec_absent:8080 ~enc:(fun c -> c.port)
    |> finish
  ) in
  obj Fun.id
  |> section "server" section ~enc:Fun.id
  |> finish
)

let config = Init_bytesrw.decode_string codec "[server]\nport = 9000"
(* Ok { debug = false; port = 9000 } *)

Multiple Sections

type db = { host : string; port : int }
type cache = { enabled : bool; ttl : int }
type config = { db : db; cache : cache option }

let db_codec = Init.Section.(
  obj (fun host port -> { host; port })
  |> mem "host" Init.string ~enc:(fun d -> d.host)
  |> mem "port" Init.int ~dec_absent:5432 ~enc:(fun d -> d.port)
  |> finish
)

let cache_codec = Init.Section.(
  obj (fun enabled ttl -> { enabled; ttl })
  |> mem "enabled" Init.bool ~enc:(fun c -> c.enabled)
  |> mem "ttl" Init.int ~dec_absent:3600 ~enc:(fun c -> c.ttl)
  |> finish
)

let config_codec = Init.Document.(
  obj (fun db cache -> { db; cache })
  |> section "database" db_codec ~enc:(fun c -> c.db)
  |> opt_section "cache" cache_codec ~enc:(fun c -> c.cache)
  |> finish
)

Interpolation

let paths_codec = Init.Section.(
  obj (fun base data logs -> (base, data, logs))
  |> mem "base" Init.string ~enc:(fun (b,_,_) -> b)
  |> mem "data" Init.string ~enc:(fun (_,d,_) -> d)
  |> mem "logs" Init.string ~enc:(fun (_,_,l) -> l)
  |> finish
)

let doc_codec = Init.Document.(
  obj Fun.id
  |> section "paths" paths_codec ~enc:Fun.id
  |> finish
)

(* Basic interpolation expands %(base)s *)
let ini = {|
  [paths]
  base = /opt/app
  data = %(base)s/data
  logs = %(base)s/logs
|}

match Init_bytesrw.decode_string doc_codec ini with
| Ok (_, data, logs) ->
    assert (data = "/opt/app/data");
    assert (logs = "/opt/app/logs")
| Error _ -> assert false

Disabling Interpolation

(* Use raw_config for files with literal % characters *)
let config = Init_bytesrw.raw_config

let result = Init_bytesrw.decode_string ~config codec {|
  [display]
  format = 100%% complete  ; Would fail with basic interpolation
|}