Introduction¶

picoc allows you to define your own library functions. These functions are written in C using your system's native C compiler. Since the native C compiler can access the hardware this means you can add functions which give picoc control of your hardware.

How libraries work¶

Your picoc distribution contains two files which are used to define library functions for your system. If your system is called "foobar" you'll be using:

• library_foobar.c - this is where the foobar-specific library functions go

• clibrary.c - this is where standard C library functions like printf() are defined

We'll start by defining a simple function in library_foobar.c. We need to do two things:

• add the function prototype to our list of picoc library functions

• define the native C implementation of the function

The prototype list¶

Each of the library_XXX.c files defines a list of picoc prototypes for each of the functions it defines. For example:

struct LibraryFunction PlatformLibrary[] =
{
    { ShowComplex,  "void ShowComplex(struct complex *)" },
    { Cpeek,        "int peek(int, int)" },
    { Cpoke,        "void poke(int, int, int)" },
    { Crandom,      "int random(int)" },
    { NULL,         NULL }
};

The first column is the name of the C function. The second column is the function prototype. The "{ NULL, NULL }" line at the end is required.

The native C function¶

The native C function is called with these parameters:

void MyCFunc(struct ParseState *Parser, struct Value *ReturnValue, struct Value **Param, int NumArgs);

• struct ParseState *Parser - this contains internal information about the progress of parsing. It's mostly used here so error messages from your function can report the line number where an error occurred.

• struct Value *ReturnValue - this points to the place you can put your return value. This is pre-created as a value of the correct return type so all you have to do is store your result here.

• struct Value **Param - this points to an array of parameters. These are all pre-checked as being the correct type.

• int NumArgs - this is the number of parameters. Normally this will already have been checked and will be exactly what you've defined in your function prototype. It is however possible to define functions with variable numbers of arguments using a stdarg-like "..." method and this is where you find out how many parameters were passed in if you're doing that.

Here's an example function definition of "random" (as defined above):

void Crandom(struct ParseState *Parser, struct Value *ReturnValue, struct Value **Param, int NumArgs)
{
    ReturnValue->Val->Integer = random() % Param[0]->Val->Integer;
}

This function calls "random()" from the C standard library. It accesses an integer parameter and returns an integer value.

Passing parameters¶

We've seen how to pass integers into functions. What about passing other data types?

Passing pointers¶

Pointer parameters are slighty more complicated to access since you have to dereference the pointer to get at the underlying data.

Here's how we dereference a pointer parameter. In this example I'll be reading an 'int *' parameter:

    int IntValue = *(int *)Param[0]->Val->NativePointer;

Passing strings / char *¶

In this example I'll be reading a 'char *' parameter. It's pretty similar to the 'int *' example above:

    char *CharPtr = (char *)Param[0]->Val->NativePointer;

picoc strings work like C strings - they're pointers to arrays of characters, terminated by a null character. Once you have the C char * you can use it just like a normal C string.

Pointers to arrays of other data types work the same way.

Passing pointers to structures and unions¶

If you're defining library functions which take structures as parameters you'll have to do a little more work. You need to pre-define the structure so the function prototype can refer to it.

In library_XXX.c you'll find a function called PlatformLibraryInit(). This is called before the library prototypes are defined. Here's some code which will define a complex number structure:

void PlatformLibraryInit()
{
    struct ParseState Parser;
    char *Identifier;
    struct ValueType *ParsedType;
    void *Tokens;
    const char *IntrinsicName = TableStrRegister("complex library");
    const char *StructDefinition = "struct complex { int i; int j; }";
    
    /* define an example structure */
    Tokens = LexAnalyse(IntrinsicName, StructDefinition, strlen(StructDefinition), NULL);
    LexInitParser(&Parser, StructDefinition, Tokens, IntrinsicName, TRUE);
    TypeParse(&Parser, &ParsedType, &Identifier);
    HeapFree(Tokens);
}

This code takes the structure definition in StructDefinition and runs the lexical analyser over it. This returns some lexical tokens. Then we initialise the parser and have it parse the type of the structure definition from the tokens we made. That's enough to define the structure in the system. Finally we free the tokens.

Now let's say we're going to define a function to display a complex number. Our prototype will look like:

    { ShowComplex,   "void ShowComplex(struct complex *)" },

And finally we can define the library function:

struct complex { int i; int j; };  /* make this C declaration match the picoc one */
void ShowComplex(struct ParseState *Parser, struct Value *ReturnValue, struct Value **Param, int NumArgs)
{
    struct complex *ComplexVal = Param[0]->Val->NativePointer;  /* casts the pointer */
        
    /* print the result */
    PrintInt(ComplexVal->i, PlatformPutc);
    PlatformPutc(',');
    PrintInt(ComplexVal->j, PlatformPutc);
}

Unions work exactly the same way as structures. Define the prototype as "union" rather than "struct" and you're away.

Returning values¶

Returning values from library functions is very much like accessing parameters. The type of return values is already set before your native C function is called so all you have to do is fill in the value.

Just as with parameters, ints, chars and enums are stored in ReturnValue->Val->Integer and floating point values are returned in ReturnValue->Val->FP.

Returning pointers¶

Returning a pointer to a static string or some other allocated data is easy. Your return code will look something like:

    ReturnValue->Val->NativePointer = "hello";

Variable numbers of parameters¶

You can define your own stdarg-style library functions like printf(). Your function prototype should use "..." in the parameter list to indicate the potential extra parameters just like the standard stdarg system. Here's an example from clibrary.c:

    { LibPrintf,        "void printf(char *, ...)" },

The NumArgs parameter to the native C function lets you know how many parameters were passed in. You access the variable parameters just like normal parameters using the Param[] array.

Take a look at clibrary.c for the full definition of LibPrintf() if you need a more complete example.

Sharing native values with picoc¶

Sometimes you have native variables you'd like to share with picoc. We can define a picoc value which shares memory with a native variable. Then we store this variable in the picoc symbol table so your programs can find it by name. There's an easy way to do this:

int RobotIsExploding = 0;
void PlatformLibraryInit()
{
    VariableDefinePlatformVar(NULL, "RobotIsExploding", &IntType, (union AnyValue *)&RobotIsExploding, FALSE);
}

The variable RobotIsExploding can be written by your native C program and read by picoc just like any other picoc variable. In this case it's protected from being written by the last parameter "IsWritable" being set to FALSE. Set it to TRUE and picoc will be able to write it too.