Module Server.Data

module Data: sig .. end

Data Encoding.

Datatypes

This module is responsible for marshaling and demarshaling data to handle communications between the server and the client in both directions.

Each datatype must be equipped with functions to encode and decode values to/from JSON format. Moreover, data types shall be also properly documented and registered in the generated documentation of the Frama-C server.

Generally speaking, we will have a module with signature Data.D for every datatype to be exchanged with the server. For simple values, predefined modules are already provided. More complex datatypes can be built with some functors, typically for options, lists or arrays.

Records and enumerated types are typical in JSON formatting, but difficult to build from OCaml records and abstract datatypes. For those kinds of data, we provide an API based on the following general scheme:

• First create an empty container with its name, documentation and such;
• Then add each field or constructor to the container;
• Finally pack the container, which actually registers its complete documentation and returns an OCaml value containing the resulting datatype module.

Hence, in addition to module signature Data.S for values, there is also a polymorphic type 'a Data.data for module values carrying a data module with type t = 'a.

The same mechanism is used throughout modules States and Request each time a JSON record or tag is needed.

type json = Json.t 

val pretty : Stdlib.Format.formatter -> json -> unit

module type S = sig .. end

Atomic Data

module Junit: S  with type t = unit

module Jany: S  with type t = json

module Jbool: S  with type t = bool

module Jint: S  with type t = int

module Jfloat: S  with type t = float

module Jstring: S  with type t = string

module Jalpha: S  with type t = string

module Jtext: S  with type t = json

module Jmarkdown: S  with type t = Markdown.text

val jpretty : ?indent:int ->
       ?margin:int ->
       (Stdlib.Format.formatter -> 'a -> unit) -> 'a -> Jtext.t

Constructors

module Joption: 
functor (A : S) -> S  with type t = A.t option

module Jpair: 
functor (A : S) -> 
functor (B : S) -> S  with type t = A.t * B.t

module Jtriple: 
functor (A : S) -> 
functor (B : S) -> 
functor (C : S) -> S  with type t = A.t * B.t * C.t

module Jlist: 
functor (A : S) -> S  with type t = A.t list

module Jalist: 
functor (A : S) -> S  with type t = A.t list

module Jarray: 
functor (A : S) -> S  with type t = A.t array

Functional API

type 'a data = (module Server.Data.S with type t = 'a) 

val junit : unit data

val jany : json data

val jbool : bool data

val jint : int data

val jfloat : float data

val jstring : string data

val jalpha : string data

val jindex : kind:string -> int data

val jkey : kind:string -> string data

val jlist : 'a data -> 'a list data

val jalist : 'a data -> 'a list data

val jarray : 'a data -> 'a array data

val joption : 'a data -> 'a option data

val derived : package:Server.Package.package ->
       id:Server.Package.ident -> Server.Package.jtype -> unit

val declare : package:Server.Package.package ->
       name:string ->
       ?descr:Markdown.text -> Server.Package.jtype -> Server.Package.jtype

Records

module Record: sig .. end

Enums

module Tag: S  with type t = tagInfo

module Enum: sig .. end

Indexed Values

These datatypes automatically index complex values with unique identifiers. This avoids to encode the internal OCaml representation of each value, by only providing to the server a unique identifier for each value.

These datatype functors come into three flavors:

• Index() for projectified datatypes,
• Static() for project independant datatypes,
• Identified() for projectified values already identified by integers.

module type Info = sig .. end

module type Map = sig .. end

module type Index = sig .. end

module Static: 
functor (M : Map) -> 
functor (I : Info) -> Index  with type t = M.key

module Index: 
functor (M : Map) -> 
functor (I : Info) -> Index  with type t = M.key

module type IdentifiedType = sig .. end

module Identified: 
functor (A : IdentifiedType) -> 
functor (I : Info) -> Index  with type t = A.t

Error handling

These utilities shall be used when writing your own encoding and decoding values to JSON format.

exception InputError of string

val failure : ?json:json ->
       ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

val failure_from_type_error : string -> json -> 'a