CLIP's C-API is a set of C-functions that allows using C-language
along with CLIP. It could be necessary for writing some speed critical
functions of your project; for writing "wrappers" for existing 3rd party
functions or whole libraries, etc. Besides, learning C-API will help you
understand internal structure of CLIP.
C-functions aimed to be used with CLIP (that is, which can be called
from some CLIP function, 'exported functions' in further) are in
separate C source file(s). This file must include "clip.h", which
contains declarations of C-API functions and structures.
Each exported function's name must have prefix 'clip_' and the name itself
must be in capital letters. Type of function must be 'int' and it
must get one and only parameter of type 'ClipMachine *', which is a pointer
to the structure containing context of the current CLIP Virtual Machine.
Exported function should return 0 (zero) if successful, or appropriate
error code (those described in error.ch, with 'EG_' prefix).
Example:
/* my.c */
#include <stdio.h>
#include "clip.h"
int clip_MYFUNCTION(ClipMachine *cm)
{
printf("Hello from MyFunction()\n");
return 0;
}
/* end of my.c */
/* test.prg */
MyFunction()
/* end of test.prg */
Compilation:
gcc -c -I${CLIPROOT}/include my.c
clip -eM test.prg my.o
Running:
#./test
Hello from MyFunction
#
_CLIP_PARND() | Retrieve a numeric parameter as a double. |
_CLIP_PARNI() | Retrieve a numeric parameter as an integer. |
_CLIP_PARNL() | Retrieve a numeric parameter as a long. |
_CLIP_RETND() | Post a numeric return value using a double type. |
_CLIP_RETNI() | Post a numeric return value using an int type. |
_CLIP_RETNL() | Post a numeric return value using a long type. |
_CLIP_STORND() | |
_CLIP_STORNI() | |
_CLIP_STORNL() |
double _clip_parnd(ClipMachine * cm,int num)
_clip_parnd() returns the value of the specified parameter as a double type.
_clip_parnd() retrieves a numeric value passed as a parameter from CLIP and converts it to a double type.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { double num = _clip_parnd(cm,1); /* ... */ return 0; }
int _clip_parni(ClipMachine * cm,int num)
_clip_parni() returns the value of the specified parameter as an int type.
_clip_parni() retrieves a numeric value passed as a parameter from CLIP and converts it to an int type.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { int num = _clip_parni(cm,1); /* ... */ return 0; }
long _clip_parnl(ClipMachine * cm,int num)
_clip_parnl() returns the value of the specified parameter as a long type.
_clip_parnl() retrieves a numeric value passed as a parameter from CLIP and converts it to a long type.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { long num = _clip_parnl(cm,1); /* ... */ return 0; }
void _clip_retnd(ClipMachine * cm,double n)
_clip_retnd() has no return value.
_clip_retnd() posts a numeric value into CLIP's return value area. When your exported function returns control to the calling CLIP program, the posted value becomes the CLIP return value of your exported function.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { double n; /* ... */ _clip_retnd(cm,n); return 0; }
void _clip_retni(ClipMachine * cm,int n)
_clip_retni() has no return value.
_clip_retni() posts a numeric value into CLIP's return value area. When your exported function returns control to the calling CLIP program, the posted value becomes the CLIP return value of your exported function.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { int n; /* ... */ _clip_retni(cm,n); return 0; }
void _clip_retnl(ClipMachine * cm,long n)
_clip_retnl() has no return value.
_clip_retnl() posts a numeric value into CLIP's return value area. When your exported function returns control to the calling CLIP program, the posted value becomes the CLIP return value of your exported function.
#include "clip.h" int clip_MYFUNCTION(ClipMachine * cm) { long n; /* ... */ _clip_retnl(cm,n); return 0; }