Jsonm.Uncut

# Module Jsonm.Uncut

    module Uncut: sig .. end

Codec with comments and whitespace.

The uncut codec also processes whitespace and JavaScript comments. The latter is non-standard JSON, fail on ``Comment` decoding if you want to process whitespace but stick to the standard.

The uncut codec preserves as much of the original input as possible. Perfect round-trip with `Jsonm` is however impossible for the following reasons:

- Escapes unescaped by the decoder may not be escaped or escaped differently by the encoder.
- The encoder automatically inserts name separator `':'` and value separators `","`. If you just reencode the sequence of decodes, whitespace and comments may (harmlessly, but significantly) commute with these separators.
- Internally the encoder uses `U+000A` (`'\n'`) for newlines.
- ``Float` lexemes may be rewritten differently by the encoder.

# Uncut data model

The uncut data model is the same as the regular data model, except that before or after any lexeme you may decode/encode one or more:

- ``White w`, representing JSON whitespace `w`. On input the sequence CR (`U+000D`) and CRLF (<`U+000A`, `U+000A`>) are normalized to `U+000A`. The string `w` must be a sequence of `U+0020`, `U+0009`, `U+000A` or `U+000D` characters (`' '`, `'\t'`, `'\n'`, `'\r'`).
- ``Comment (`S, c)`, representing a JavaScript single line comment `c`. `c` is the comment's content without the starting `//` and the ending newline. The string `c` must not contain any newline.
- ``Comment (`M, c)`, representing a JavaScript multi-line comment `c`. `c` is the comment's content without the starting `/*` and the ending `*/`. The string `c` must not contain the sequence `*/`.

Warning. `Jsonm.Uncut.encode` does not check the above constraints on `w` and `c`.

# Decode

    val decode : Jsonm.decoder ->
           [ `Await
           | `Comment of [ `M | `S ] * string
           | `End
           | `Error of Jsonm.error
           | `Lexeme of Jsonm.lexeme
           | `White of string ]

`decode d` is like `Jsonm.decode` but for the uncut data model.

    val pp_decode : Format.formatter ->
           [< `Await
            | `Comment of [ `M | `S ] * string
            | `End
            | `Error of Jsonm.error
            | `Lexeme of Jsonm.lexeme
            | `White of string ] ->
           unit

`pp_decode ppf v` prints an unspecified representation of `v` on `ppf`.

# Encode

    val encode : Jsonm.encoder ->
           [< `Await
            | `Comment of [ `M | `S ] * string
            | `End
            | `Lexeme of Jsonm.lexeme
            | `White of string ] ->
           [ `Ok | `Partial ]

`encode` is like `Jsonm.encode` but for the uncut data model.

IMPORTANT. Never encode ``Comment` for the web, it is non-standard and breaks interoperability.