Frama-C:
Plug-ins:
Libraries:

Frama-C API - Json

Json Library

Remarks:

  • UTF-8 escaping is not supported;
  • Parsers are less strict than Json format;
  • Printers are supposed to strictly conforms to Json format;
  • Number can be used to encode non OCaml-primitive numbers, for instance Zarith.
type json = [
  1. | `Assoc of (string * json) list
  2. | `Bool of bool
  3. | `Float of float
  4. | `Int of int
  5. | `List of json list
  6. | `Null
  7. | `String of string
]

Json Objects

Same type than Yojson.Basic.json

type t = json
val equal : t -> t -> bool

Stdlib

val compare : t -> t -> int

Stdlib

val pp : Stdlib.Format.formatter -> t -> unit
val pp_dump : Stdlib.Format.formatter -> t -> unit

without formatting

exception Error of Filepath.Normalized.t * int * string

file, line, message

Constructors

val of_bool : bool -> t
val of_int : int -> t
val of_string : string -> t
val of_float : float -> t
val of_list : t list -> t
val of_array : t array -> t
val of_fields : (string * t) list -> t

Filers out null fields

val of_option : ('a -> t) -> 'a option -> t

Filers out null fields

Maps none to null

Parsers

Parsing raise Error in case of error.

val load_lexbuf : Stdlib.Lexing.lexbuf -> t

Consumes the entire buffer.

val load_channel : ?file:string -> Stdlib.in_channel -> t

Parses the stream until EOF.

val load_string : string -> t

Parses the Json in the string.

val load_file : Filepath.Normalized.t -> t

May also raise system exception.

Printers

Printers use formatting unless ~pretty:false.

val save_string : ?pretty:bool -> t -> string
val save_buffer : ?pretty:bool -> Stdlib.Buffer.t -> t -> unit
val save_channel : ?pretty:bool -> Stdlib.out_channel -> t -> unit
val save_formatter : ?pretty:bool -> Stdlib.Format.formatter -> t -> unit
val save_file : ?pretty:bool -> Filepath.Normalized.t -> t -> unit

Accessors

Accessors raise exception Invalid_argument in case of wrong format.

val bool : t -> bool

Extract True and False only.

  • raises Invalid_argument

    when the conversion fails.

val int : t -> int

Convert Null, Int, Float, Number and String to an int. Floats are truncated with int_of_float and Null to 0.

  • raises Invalid_argument

    when the conversion fails.

val string : t -> string

Convert Null, Int, Float, Number and String to a string. Floats are truncated with string_of_float and Null to "".

  • raises Invalid_argument

    when the conversion fails.

val float : t -> float

Convert Null, Int, Float, Number and String to float and Null to 0.0.

  • raises Invalid_argument

    when the conversion fails.

val array : t -> t array

Extract the array of an Array object. Null is considered an empty array.

  • raises Invalid_argument

    if the object is not an array.

val list : t -> t list

Extract the list of an Array object. Null is considered an empty list.

  • raises Invalid_argument

    if the object is not a list.

val assoc : t -> (string * t) list

Extract the list of an Assoc object. Null is considered an empty assoc.

  • raises Invalid_argument

    if the object is not a list.

val fold : (string -> t -> 'a -> 'a) -> t -> 'a -> 'a

Fold over all fields of the object. Null is considered an empty object. Typical usage is fold M.add t M.empty where M=Map.Make(String).

  • raises Invalid_argument

    if the object is not an Assoc or Null object.

val field : string -> t -> t

Lookup a field in an object. Null is considered an empty object.

  • raises Not_found

    if the field is absent from the object.

  • raises Invalid_argument

    if the object is not an Assoc or Null object.

The functions below read and write to JSON files asynchronously; they are intended to be called at different times during execution. To avoid reopening, re-reading and rewriting the same file several times, they instead operate as following:

  • Read the file on first use, and store it in memory;
  • Perform merge operations using the in-memory representations;
  • Flush the final form to disk before quitting Frama-C. The latter is done via function json_flush_cache below, which is setup to run with an at_exit trigger.

Note: no other functions should modify the contents of path; any modifications will be overwritten when the cache is flushed.

  • since 23.0-Vanadium
exception CannotMerge of string

Exception raised by the functions below when incompatible types are merged.

val merge_object : Filepath.Normalized.t -> t -> unit

merge_object path json_obj recursively merges the object json_obj into the JSON file path. If path does not exist, it is created. Merge consists in combining values with the same key, e.g. if path already contains an object {"kernel": {"options": ["a"]}}, and json_obj is {"kernel": {"options": ["b"]}}, the result will be {"kernel": {"options": ["a", "b"]}}. Cannot merge heterogeneous objects, i.e. in the previous example, if "options" were associated with a string in path, trying to merge an array into it would raise CannotMerge. The merged object is updated in the memory cache.

  • raises CannotMerge

    if the objects have conflicting types for the same keys, or if the root JSON element is not an object.

  • since 23.0-Vanadium
val merge_array : Filepath.Normalized.t -> t -> unit

merge_list path json_array merges the array json_array into the JSON file path. See merge_object for more details. Unlike objects, arrays are merged by simply concatenating their list of elements.

  • raises CannotMerge

    if the root JSON element is not an array.

  • since 23.0-Vanadium
val from_file : Filepath.Normalized.t -> t

from_file path opens path and stores its JSON object in a memory cache, to be used by the other related functions.

  • raises Yojson.Json_error

    if path is a malformed JSON file.

  • since 23.0-Vanadium
val flush_cache : unit -> Filepath.Normalized.t list

Flushes the JSON objects in the cache. Returns the names of the written files.

  • since 23.0-Vanadium