# Ring/Lessons/Code Generator for wrapping C/C++ Libraries
## Code Generator for wrapping C/C++ Libraries

In this chapter we will learn how to use the code generator to wrap C/C++ Libraries to use it in our Ring applications.

## Using the tool

The code generator program is parsec.ring that can be executed as any ring code using the ring interpreter.
for example to read a configuration file called test.cf to generate the source code file test.c run parsec.ring as in the next command

## Configuration file

The configuration file (*.cf) is the input file that we pass to the code generator. This file determine the functions prototypes that we need to use from a C/C++ library.
Writing configuration files is simple according to the next rules

## Using the function prototype

* To generate code that wraps a C function, we just write the C function prototype
Example:
The previous example will guide the code generator to generate five functions that wrap the al_create_display, al_destroy_display, al_get_new_display_flags, al_set_new_display_flags and al_get_new_display_option functions.
The generated code will be as in the next example
from the previous example we can see how much of time and effort is saved using the Code Generator.

## Adding code to the generated code

* To generate code directly type it between and
Example :
We use this feature when we need to do something without the help of the code generator. for example including header files and defining constants using Macro.

## Prefix for Functions Names

* To determine a prefix in all of the functions names type it between <funcstart> and </funcstart>
for example when we wrap the Allegro game programming library and we need all of the library functions to start with "al" we type the next code in the configuration file

## Generate function to wrap structures

* To generate functions that wrap structures (create/delete/get structure members)
just type the structures names between <struct> and </struct> also after the structure name you can type the structure members between { } separated by comma.
Example
from the previous example we will generate two function to create/delete the structure ALLEGRO_COLOR Also we will generate two functions to create/delete the structure ALLEGRO_EVENT and four functions to get the structure ALLEGRO_EVENT members (type, keyboard.keycode, mouse.x, mouse.y).

## Register New Functions

We can register functions by typing the function prototype between <register> and </register> We need this feature only when we don't provide the function prototype as input directly where we need to write the code of this function.
Example:
In the previous example we register the al_exit function. This function is not part of the Allegro Library, it's just an extra function that we need to add. Then the code if this function is written inside and . This function call the exit function from the C language library.

## Writing comments in the configuration file

* To type comments just type it between <comment> and </comment>
Example:

## Executing code during code generation

* To ask from the code generator to execute Ring code during reading the configuration file, just
write the code between <runcode> and </runcode>
Example:
The previoud line of code add the string "al_fixed" to the list aNumberTypes, This list contains types that can be considered as numbers when the code generator find it in the function prototype.

## Configuration file for the Allegro Library

The next configuration file enable us to use the Allegro library functions. The configuration file size is less than 1000 lines. when the code generator take this file as input the generated source code file in the C language will be 12000 lines of code!
We can see this configuration file as a complete example about using the code generator Also we can use it to know the functions that can be used from RingAllegro when you use it to create 2D games!
.. note:: we just provided part of the configuration file, for complete copy check the Ring source

## Threads Support

Next, another part of the configutaiton file, it's important because we can learn from it how to add threads to our Ring applications by using a threads library.
The idea is using ring_vm_mutexfunctions and ring_vm_runcodefromthread to execute Ring code.

## Code Generator Rules for Wrapping C++ Classes

* We can define classes between <class> and </class>
* Between <class> and <class> we set attributes like "name, nonew, para, parent, codename, passvmpointer and abstract"
* we set the attributes using the style attributename:value or attributename only if no values are required
* The "name" attribute determine the class name in C++ code and this name will be the default name in the Ring code
* The nonew instruction means that we don't need new/delete methods
* The parent attribute determine the parent class name
* The codename attribute determine another class name in C++ code
* The passvmpoint instruction means passing the Ring VM pointer to the class constructor when we create new objects, this happens when we set the codename attribute to a class the we will define and this class need the Virtual Machine pointer (for example to use it to execute Ring code from C++ code).
* The abstract instruction means that no new method is required for this class "no objects will be created".
* Using <nodllstartup> we can avoid #include "ring.h", We need this to write our startup code.
* Using <libinitfunc> we can change the function name that register the library functions
* Using <ignorecpointertype> we can ignore pointer type check
* Using the aStringTypes list when can defined new types that treated like const char *
* Using the aBeforeReturn list when can define code that is inserted after the variable name when we return that variable from a function
* Using the aNewMethodName list we can define another method name to be used in Ring code when we call the C++ method. this feature is required because some C++ method may be identical to Ring Keywords like "load","next","end" and "done".

## Using configuration file that wrap C++ Library

To run the code generator to generate code for using C++ library in the Ring application, we can do that as we did with using C libraries but here we will generate *.cpp file instead of *.c file. Also we will determine another file to be generated (*.ring). This file will contains classes in Ring code that wraps C++ functions for using C++ classes and objects.

## Configuration file for the Qt Framework

The next configuration file is used to wrap many Qt classes The configuration file is around 3500 lines and generate C++ code around 56000 lines and generate also Ring code around 9000 lines.
.. note:: Most of the content of the previous configuration file is removed from this documentation, for a complete version see the Ring source code distribution.