C/VLisp Binding

This binding allows to use C functions, constants, and enumerations directly from VLisp. Since LISP is a typed language usually new LISP node types are created for different C types. This allows much more complex bindings and automatic parameter checking in calls from VLisp to C. All input parameters are converted from LISP to C and checked for correct parameter type, e.g., a STRING is not accepted where a FIXNUM is required and a LISP error is generated. Whenever a conversion is possible, e.g., from integer to floating point type it is performed automatically. Array parameters may be passed either as a list or a vector of LISP values. In this case all elements of the list/vector must be of the right type. The size of the array is no parameter to the LISP function since it can be calculated from the list/vector size if the der key is used with the name of the array parameter in the documentation. For input parameters with check expressions, these are checked prior to the C function call and on failure a LISP error is generated. For enumeration and bit mask values, the binding code checks that the value is valid. Since for enumerations it is possible that not all constants are used for the language binding, only the values bound by TAC are accepted. For bit masks values combined by the element key in the constant documentation to a group are checked whether only defined bits are used if the key set is used in the parameter documentation.

The VLisp to C binding of TAC takes into account the parameter documentation key in Section 6.2.1. The return value of a C functions is handled special:

1. If the value matches the expression of the key not-ok, NIL is returned for function failure. Otherwise the return value is the first output value.
2. If the value does not match the expression of the key ok, NIL is returned for function failure. If there no more output parameters, t is returned for function success, else the return value is ignored for VLisp.
3. Otherwise the return value is the first output value.

If there is no output value to VLisp, the binding returns t. For one output value this value is just converted, for multiple output values a LISP list is created with the respective values from left to right of the function parameter definition. Output arrays are converted into LISP lists. In case of an input and output value, this value is a newly constructed list and is different from the input. An example from the project ViennaWidgetSet[Hal95b] is shown in Figure 6.15.

  
Abbildung 6.12: Documented C functions for VLisp binding

Both C functions are accessible from VLisp.

Names in VLisp are automatically generated from the C names by the following set of rules:

1. Everything up to the first upper case letter is a prefix. This prefix will be used with two `:' character as VLisp name space prefix.
2. In front of any single upper case letter a `-' character is inserted into the VLisp name and the case of the letter is changed to lower.
3. In front of multiple upper case letters a `-' is inserted and all upper case letter retain their case. After the upper case letters a `-' is inserted again.
4. A digit in front of an upper case letter is handled as an upper case letter and forms a multiple upper case letter sequence.
5. A `_' character is converted to a `-'. This character does not break a multiple upper case letter sequence.

In this case the two VLisp functions xvw::set-list-list and xvw::get-list-list are created. The first function has three input parameters in C, where the last one numitems is the size of the string array items. This means that only two parameters are required in VLisp since the number of strings can be calculated from the length of the list parameter used for numitems. The first parameter is the new VLisp widget type as shown later in Listing 6.3. The second function has one input widget parameter and two output parameters. In this case the two output parameters have a connection because they are array and its derived size respectively. Since the function has no return value, a list will be constructed from the array of strings is returned to VLisp. Assuming the variable lw holds a widget of the correct type, the following code will work:

The returned list of strings from xvw::get-list-list is different to the parameter list of xvw::set-list-list. For every call a new output value list is allocated and returned. These lists are not identical but equal in manner of the LISP compare function equal. This is important because the default compare function for many functions in LISP is eql.

C constants and enumeration names are handled similar to C functions with the same algorithm for name conversion as described above. An example is shown in Figure 6.16.

  
Abbildung 6.13: Documented C constant and enumeration for VLisp binding

In this example the enumeration xvwCursor is used for binding. Since the full enumeration is documented for TAC the new C type xvwCursor is automatically known for language binding and compatible to an integer value without additional definitions from the developer. To bind a value from an enumeration to VLisp the documentation following the name has to start with a /*** comment instead of a single /*. All other constants known by C will be not available in VLisp. The shown example for a constant is more complex, since an evaluation is used. In this case the type must be specified explicitly by the programmer with the documentation key type. This constant forms in combination with others a bit mask associated to the name selectionMode. All values are accessible by the following VLisp symbols:

The symbols are constant in VLisp and cannot be modified. This is important because the functions insist on the correct definition of these constants.