Data types (O'Caml)

[UP]
Data types

Data types (O'Caml)

The representation of the data types in O'Caml

In the O'Caml environment, the dialog data types are represented as follows:

type var_value =
    String_value   of string
  | Enum_value     of string list
  | Dialog_value   of dialog_type option
  | Dyn_enum_value of (string * string) list
  | Alist_value    of (string * var_value) list

(You can find this in the module Wd_types.) This leads to the following value literals:

Strings: A string with value s is written as
```
String_value s
```
Declared enumerators: An enumerator value that contains the internal items x1, x2, ... is written as
```
Enum_value [x1; x2; ...]
```
The items may be in any order; when an enumerator value is displayed by an interactor, the items are rearranged according to the declared order (as found in the ui:enumeration element). The enumerator value is checked for compatibility with the declaration when an instance variable is set to the value by the set_variable method (i.e. it is checked whether only declared items occur in the passed list of items, and whether they occur only once).
Dynamic enumerators: A dynamic enumerator value that contains the internal items x1, x2, ... and the corresponding external items y1, y2, ... is written as
```
Dyn_enum_value [ (x1,y1); (x2,y2); ... ]
```
The order of the items specify the order of the enumerator. When an instance variable is set to such a value it is checked whether every internal item occurs only once.
Dialogs: A dialog dlg is written as variable value in the following way:
```
Dialog_value (Some dlg)
```
Note that there is also the non-existing dialog which is written as
```
Dialog_value None
```
(The system uses this value as default values for variables of type dialog; there is simply no other reasonable default.)
Associative values: An associative list with the keys k1, k2, ... and the corresponding values v1, v2, ... is written as
```
Alist_value [ (k1,v1); (k2,v2); ... ]
```
The order of the pairs specify the order of the list. When an instance variable is set to such a value it is checked whether every key occurs only once.

Getting values of variables

Let dlg be the current dialog object in the following examples. In order to get a variable of arbitrary type one can invoke the variable method:

let v = dlg # variable "name" in ...

After that, v is a var_value (i.e. something like String_value, Enum_value etc.). - If you already know that the variable is a string, you can also call:

let s = dlg # string_variable "name" in ...

Now s is directly an O'Caml string (and not a String_value). - For the other types, there are direct accessor methods, too:

let enum     = dlg # enum_variable "name1" in ...
let dyn_enum = dlg # dyn_enum_variable "name2" in ...
let dlg'     = dlg # dialog_variable "name3" in ...

For associative lists, there are several possibilities to get values in a more convenient way. First, one can directly get the defining list:

let alist = dlg # alist_variable "name" in ...

Furthermore, it is possible to look up a component "key" of the list by one of the following invocations (depending on the base type):

let s        = dlg # lookup_string_variable "name" "key1" in ...
let enum     = dlg # lookup_enum_variable "name" "key2" in ...
let dyn_enum = dlg # lookup_dyn_enum_variable "name" "key3" in ...
let dlg'     = dlg # lookup_dialog_variable "name" "key4" in ...

Setting values of variables

There is only one method to set a variable to a value v:

dlg # set_variable "name" v

Constructing a var_value from a base value is already very simple, such that there is no need for methods setting the base value directly. For example, if a variable must be set to a string s, the following elegant notation is possible:

dlg # set_variable "name" (String_value s)

Resetting values of variables

There is another method that resets a variable to its initial value:

dlg # unset_variable "name"

The dot notation

As a more convenient method to access variables of inner dialogs, it is possible to refer to variables by the dot notation. For example, if there is a dialog-type variable d, and the string variable s is defined within the dialog that is currently the value of d, you can get the string contents of s by this expression:

let s = dlg # string_variable "d.s"

This is a shorthand notation for:

let s =
  match dlg # dialog_variable "d" with
    None -> failwith "Dialog variable is empty!"
  | Some d -> d # string_variable "s"

See the section about Dot notation (v1.v2) for a broader discussion of this topic.