Module OBus_introspect_ext

module OBus_introspect_ext: sig .. end

OBus extended introspection

By default, introspection document do not convey semantical informations, such as enumeration or flags. However it is possible to attach information to interfaces and members.

This module implement an extended introspection format, which can be encoded into standard introspection documents by using annotations.

Annotations

The following annotations are used to encode additionnal informations into D-Bus introspection documents

val obus_enum : string

The org.ocamlcore.forge.obus.Enum annotation

val obus_flag : string

The org.ocamlcore.forge.obus.Flag annotation

val obus_type : string

The org.ocamlcore.forge.obus.Type annotation

val obus_itype : string

The org.ocamlcore.forge.obus.IType annotation

val obus_otype : string

The org.ocamlcore.forge.obus.OType annotation

Extended types

type basic = private

`\|`	`Byte`
`\|`	`Boolean`
`\|`	`Int16`
`\|`	`Int32`
`\|`	`Int64`
`\|`	`Uint16`
`\|`	`Uint32`
`\|`	`Uint64`
`\|`	`Double`
`\|`	`String`
`\|`	`Signature`
`\|`	`Object_path`
`\|`	`Unix_fd`
`\|`	`Enum of OBus_value.T.basic * (OBus_value.V.basic * string) list`	`(*`	An enumeration. The first argument is the real D-Bus type and the second is a list of `(constant, keyword)`. For example: `Enum(OBus_value.T.Uint32, [(OBus_value.V.Uint32 1l, "ok"); (OBus_value.V.Uint32 2l, "fail")])` Note that the real D-Bus type must be `OBus_value.T.Byte` or an integer type.	`*)`
`\|`	`Flag of OBus_value.T.basic * (OBus_value.V.basic * string) list`	`(*`	A flag. The first argument is the real type and the second is a list of `(bits, keyword)`. For example: `Flag(OBus_value.T.Uint32, [(OBus_value.V.Uint32 0x01l, "flag1"); (OBus_value.V.Uint32 0x02l, "flag2"); (OBus_value.V.Uint32 0x04l, "flag3")])` Note that the real D-Bus type must be `OBus_value.T.Byte` or an integer type.	`*)`

type single =

`\|`	`Basic of basic`
`\|`	`Structure of single list`
`\|`	`Array of single`
`\|`	`Dict of basic * single`
`\|`	`Variant`

type sequence = single list

Constructors

val byte : basic

val boolean : basic

val int16 : basic

val int32 : basic

val int64 : basic

val uint16 : basic

val uint32 : basic

val uint64 : basic

val double : basic

val string : basic

val signature : basic

val object_path : basic

val unix_fd : basic

val enum : OBus_value.T.basic ->
       (OBus_value.V.basic * string) list -> basic

val flag : OBus_value.T.basic ->
       (OBus_value.V.basic * string) list -> basic

val basic : basic -> single

val structure : single list -> single

val array : single -> single

val dict : basic ->
       single -> single

val variant : single

Terms

type term = private

`\|`	`Term of string * term list`	`(*`	A term. Arguments are the symbol name, which is either the name of a D-Bus type or a user defined type the arguments taken by the function associated to the symbol	`*)`
`\|`	`Tuple of term list`	`(*`	A list of terms, packed into a tuple. Tuple are always mapped to D-Bus structure. Moreover it is ensured that there is never type of the form `Tuple[t]`.	`*)`

A term represent a type, where symbols have not been resolved.

val term : string -> term list -> term

Construct a term

val tuple : term list -> term

Construct a tuple. If the list is of length 1, the type itself is returned.

Symbols

type symbol = private

`\|`	`Sym_enum of OBus_value.T.basic * (OBus_value.V.basic * string) list`
`\|`	`Sym_flag of OBus_value.T.basic * (OBus_value.V.basic * string) list`

Type of user-definable symbols

val sym_enum : OBus_value.T.basic ->
       (OBus_value.V.basic * string) list -> symbol

Create an enumeration

val sym_flag : OBus_value.T.basic ->
       (OBus_value.V.basic * string) list -> symbol

Create a flag type

Conversions

Stripping

The following functions remove extension from types.

val strip_basic : basic -> OBus_value.T.basic

val strip_single : single -> OBus_value.T.single

val strip_sequence : sequence -> OBus_value.T.sequence

Projections

The following functions project standard D-Bus types into extended D-Bus types

val project_basic : OBus_value.T.basic -> basic

val project_single : OBus_value.T.single -> single

val project_sequence : OBus_value.T.sequence -> sequence

Types to terms conversions

The following functions returns the term associated to a standard D-Bus type

val term_of_basic : OBus_value.T.basic -> term

val term_of_single : OBus_value.T.single -> term

val term_of_sequence : OBus_value.T.sequence -> term

Symbols resolution

type env = (string * symbol) list

An environment, mapping names to symbol

exception Resolve_error of string

Exception raised when the resolution of symbols of a type fails.

val resolve : env ->
       term -> single

resolve env term resolves symbols of term using env, and returns the extended type it denotes. It raises OBus_introspect_ext.Resolve_error if a symbol of term is not found in env.

Extended introspection ast

type name = string

type annotation = name * string

type argument = name option * term

type access = OBus_introspect.access =

`\|`	`Read`
`\|`	`Write`
`\|`	`Read_write`

type member =

`\|`	`Method of name * argument list * argument list * annotation list`
`\|`	`Signal of name * argument list * annotation list`
`\|`	`Property of name * term * access * annotation list`

type interface = name * member list *
       (string * symbol) list *
       annotation list

Encoding/decoding

val encode : interface -> OBus_introspect.interface

Encode the given interface into a standard one by using annotations

val decode : OBus_introspect.interface -> interface

Decode the given standard interface into an extended one by decoding annotations