package frama-c

  1. Overview
  2. Docs
package frama-c
Legend:
Library
Module
Module type
Parameter
Class
Class type

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

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
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct