Programming with ooc/Interfaces

Introduction
One of the strong points of ooc is the descriptive way C libraries can be interfaced with. These interfaces can be as low-level as a list of extern functions or 'high-level' by wrapping function calls and data within ooc classes or complex covers.

Building an interface
In the discussion that follows we are going to build up a basic interface to the libYAML (http://pyyaml.org/wiki/LibYAML) library. There is an existing interface by nddrylliog here which we will use as a reference too.

Most of our work will involve reading the library header file (http://svn.pyyaml.org/libyaml/branches/stable/include/yaml.h) and deciding how we intend to use the contents therein. To interface with the C library we will need it to be present on our system. We will also want to create a file hierarchy for our new interface.

Setup
In this section we will make the C library accessible to our new ooc interface and create the file hierarchy for that interface.

System-wide install
Installing (making available) the C library is system dependent. The following steps will work for users of Ubuntu:

sudo apt-get install libyaml-dev

Local install
Another option (that is really beyond the scope of this book) is to keep libraries within a user account and control the paths where the C compiler searches for libraries and headers. An example setup that uses ~/local as a prefix could be:

To make use of this kind of setup you will need to set the relevant environment variables in the relevant user rc file:

ooc
To make use of libraries in ooc the convention is to set the environment variable OOC_LIBS. Inkeeping with the local setup discussed above this can be a path accessible only to this user:

export OOC_LIBS=$HOME/local/ooc_libs

Since we are building an ooc library ourselves the file hierarchy belongs inside OOC_LIBS. More details on the structure of a library and the associated use file are available in the ooc documentation. For our purposes we will have something like :

ooc-yaml yaml.use source YAML.ooc samples 01-test.occ

Interfacing
The first step is to create a use file that describes how our ooc library is laid out and what setting it needs to compile to ooc programs that want to use it. A basic setup is the following :

Name: libYAML Version: 0.1.4 Description: Interface to libYAML Includes: yaml.h SourcePath: source

For the purposes of this discussion we are going to do all of the interface creation inside source/YAML.ooc in our file hierarchy above. Because we want this file to include the settings we established above we include the line

use yaml

at the top of this file.

Constants
Wonder of wonders libYAML does not seem to define any constants! But just-in-case the library you are interfacing with does include constants your interfaces should look something like this (C code above in bold, ooc below):

#define A_FLOATING_POINT_CONSTANT 12.0 OOC_NAME_FOR_FLOATING_POINT_CONSTANT: extern( A_FLOATING_POINT_CONSTANT ) Float

#define A_STRING_CONSTANT "Twelve" OOC_NAME_FOR_STRING_CONSTANT: extern( A_STRING_CONSTANT ) CString

Functions
Interfacing with C header means coming into contact with many of the quirky parts of the C pre-processor and the tricks developers use to cross platforms and programming paradigms. libYAML uses the macro YAML_DECLARE to provide interoperability with WIN32. For our purposes we will simply expand:     which makes the following declarations equivalent:

YAML_DECLARE(const char *) yaml_get_version_string(void);

const char * yaml_get_version_string(void); YAMLGetVersionString: extern( yaml_get_version_string ) func -> CString