• en

Module OpamJson

type lexeme = TODO: a
The type for JSON lexemes. `As and `Ae start and end arrays and `Os and `Oe start and end objects. `Name is for the member names of objects.
A well-formed sequence of lexemes belongs to the language of the json grammar: 
  json = object / array
object = `Os *member `Oe
member = (`Name s) value
 array = `As *value `Ae
 value = `Null / `Bool b / `Float f / `String s / object / array
A TODO: ref:decode returns only well-formed sequences of lexemes or `Errors are returned. The UTF-8, UTF-16, UTF-16LE and UTF-16BE encoding schemes are supported. The strings of decoded `Name and `String lexemes are however always UTF-8 encoded. In these strings, characters originally escaped in the input are in their unescaped representation.
An TODO: ref:encode accepts only well-formed sequences of lexemes or Invalid_argument is raised. Only the UTF-8 encoding scheme is supported. The strings of encoded `Name and `String lexemes are assumed to be immutable and must be UTF-8 encoded, this is not checked by the module. In these strings, the delimiter characters U+0022 and U+005C ('"', '\') aswell as the control characters U+0000-U+001F are automatically escaped by the encoders, as mandated by the standard.
val pp_lexeme : Format.formatter -> TODO: a -> unit
pp_lexeme ppf l prints a unspecified non-JSON representation of l on ppf.
type error = TODO: a
val pp_error : Format.formatter -> TODO: a -> unit
pp_error e prints an unspecified UTF-8 representation of e on ppf.
type encoding = TODO: a
The type for Unicode encoding schemes.
type src = TODO: a
The type for input sources. With a `Manual source the client must provide input with Manual.src.
type decoder
The type for JSON decoders.
val decoder : ?encoding:TODO: a -> TODO: b -> decoder
decoder encoding src is a JSON decoder that inputs from src. encoding specifies the character encoding of the data. If unspecified the encoding is guessed as suggested by the standard.
val decode : decoder -> TODO: a
decode d is:
  • `Await if d has a `Manual source and awaits for more input. The client must use Manual.src to provide it.
  • `Lexeme l if a lexeme l was decoded.
  • `End if the end of input was reached.
  • `Error e if a decoding error occured. If the client is interested in a best-effort decoding it can still continue to decode after an error (see errorrecovery) although the resulting sequence of `Lexemes is undefined and may not be well-formed.

The Uncut.pp_decode function can be used to inspect decode results.
Note. Repeated invocation always eventually returns `End, even in case of errors.
val decoded_range : decoder -> ((int * int) * (int * int))
decoded_range d is the range of characters spanning the last `Lexeme or `Error (or `White or `Comment for an Uncut.decode) decoded by d. A pair of line and column numbers respectively one and zero based.
val decoder_encoding : decoder -> encoding
decoder_encoding d is d's encoding.
Warning. If the decoder guesses the encoding, rely on this value only after the first `Lexeme was decoded.
val decoder_src : decoder -> src
decoder_src d is d's input source.
type dst = TODO: a
The type for output destinations. With a `Manual destination the client must provide output storage with Manual.dst.
type encoder
The type for JSON encoders.
val encoder : ?minify:bool -> TODO: a -> encoder
encoder minify dst is an encoder that outputs to dst. If minify is true (default) the output is made as compact as possible, otherwise the output is indented. If you want better control on whitespace use minify = true and Uncut.encode.
val encode : encoder -> TODO: a -> TODO: b
encode e v is:
  • `Partial iff e has a `Manual destination and needs more output storage. The client must use Manual.dst to provide a new buffer and then call encode with `Await until `Ok is returned.
  • `Ok when the encoder is ready to encode a new `Lexeme or `End.
For `Manual destinations, encoding `End always returns `Partial, the client should as usual use Manual.dst and continue with `Await until `Ok is returned at which point Manual.dst_rem e is guaranteed to be the size of the last provided buffer (i.e. nothing was written).
Raises. Invalid_argument if a non well-formed sequence of lexemes is encoded or if `Lexeme or `End is encoded after a `Partial encode.
val encoder_dst : encoder -> dst
encoder_dst e is e's output destination.
val encoder_minify : encoder -> bool
encoder_minify e is true if e's output is minified.
module Manual : sig
Manual input sources and output destinations.
Warning. Use only with `Manual decoders and encoders.
val src : decoder -> string -> int -> int -> unit
src d s j l provides d with l bytes to read, starting at j in s. This byte range is read by calls to decode until `Await is returned. To signal the end of input call the function with l = 0.
val dst : encoder -> string -> int -> int -> unit
dst e s j l provides e with l bytes to write, starting at j in s. This byte rang is written by calls to encode with e until `Partial is returned. Use dst_rem to know the remaining number of non-written free bytes in s.
val dst_rem : encoder -> int
dst_rem e is the remaining number of non-written, free bytes in the last buffer provided with dst.
end
module Uncut : sig
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.
val decode : decoder -> TODO: a
decode d is like Jsonm.decode but for the uncut data model.
val pp_decode : Format.formatter -> TODO: a -> unit
pp_decode ppf v prints an unspecified representation of v on ppf.
val encode : encoder -> TODO: a -> TODO: b
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.
end
type t = TODO: a
val to_string : t -> string
val add : t -> unit
val output : unit -> unit
val set_output : string -> unit -> unit
val verbose : unit -> bool