clib

The clib module exposes Blade capabilites to interact with C shared libraries. The workflow follows a simple approach.

Load the library
Define the function schematics
Call the function.

That simple!

For example, the following code dirname() and cos() function from the standard C library on a Unix machine (Linux, OSX, FreeBSD etc).

# Import clib
import clib

# 1. Load 'libc' shared module available on Unix systems
var lib = clib.load('libc')

# 2. Declare the functions
var dirname = lib.define('dirname', clib.char_ptr, clib.char_ptr)
var cos = lib.define('cos', clib.double, clib.double)     # this may not work on linux

# 3. Call the functions
echo dirname('/path/to/my/file.ext')
echo cos(23)

# Close the library (this is a good practice, but not required)
lib.close()

The first argument to a definiton is the name of the function. The second is its return type. If the function takes parameters, the parameter types follow immediately. (See below for a list of the available types.)

NOT YET SUPPORTED:

Variadic functions

Properties

clib.void: C void type
type ptr

clib.bool: C bool type
type ptr

clib.uint8_t: C uint8_t type
type ptr

clib.int8_t: C int8_t type
type ptr

clib.byte: C byte type
type ptr

clib.ubyte: C ubyte type
type ptr

clib.uint16_t: C uint16_t type
type ptr

clib.int16_t: C int16_t type
type ptr

clib.uint32_t: C uint32_t type
type ptr

clib.int32_t: C int32_t type
type ptr

clib.uint64_t: C uint64_t type
type ptr

clib.int64_t: C int64_t type
type ptr

clib.ssize_t: C ssize_t type
type ptr

clib.float: C float type
type ptr

clib.double: C double type
type ptr

clib.uchar: C uchar type
type ptr

clib.char: C char type
type ptr

clib.ushort: C ushort type
type ptr

clib.short: C short type
type ptr

clib.uint: C uint type
type ptr

clib.int: C int type
type ptr

clib.ulong: C ulong type
type ptr

clib.long: C long type
type ptr

clib.size_t: C size_t type
type ptr

clib.long_double: C long_double type
type ptr

clib.char_ptr: C char_ptr type
type ptr

clib.uchar_ptr: C uchar_ptr type
type ptr

clib.ptr: C ptr type
type ptr

Functions

clib.load(name: string): Loads a new C shared library pointed to by name. Name must be a relative path, absolute path or the name of a system library. If the system shared library extension is omitted in the name, it will be automatically added.
return CLib

clib.new(type: type, …any): Creates a new C value for the specified clib type with the given values.
returns bytes

clib.get(type: type, data: string | bytes): Returns the data contained in a C type type encoded in the data. The data should either be an output of clib.new() or a call to a function returning one of struct, union or array.
For structures created with named_struct(), a dictionary will automatically be returned with the values mapped to the names of the structure elements.

returns list | dictionary

clib.get_ptr_index(pointer: ptr, type: clib_type, index: number): Get the value at the given index of a pointer based on the given CLib type.
return any

clib.get_ptr_index(pointer: ptr, type: clib_type, index: number, value: any): Sets the value at the given index of a pointer based on the given CLib type to the given value.
return any

clib.struct(…type)

Returns a type that can be used to declare structs. To create or read value for the struct you need to use the new() and get() functions respectively. Alternatively, you may use the pack() and unpack() function in the struct module respectively.

This function can also be used to define a C union or array.

return type

clib.named_struct(types: dictionary)

Returns a type that can be used to declare structs based on the named types. The function works well with the get() function because it automatically assigns the name of the struct elements when getting the value.

To create or read value for the struct you need to use the new() and get() functions respectively. Alternatively, you may use the pack() and unpack() function in the struct module respectively.

This function can also be used to define a C union or array.

return type

Classes

class Clib

class CLib provides an interface for interacting with C shared modules.

class Clib methods

CLib([name: string])

The name should follow the same practice outlined in load().

constructor

load(name: string)

Loads a new C shared library pointed to by name. Name must be a relative path, absolute path or the name of a system library. If the system shared library extension is omitted in the name, it will be automatically added except on Linux machines.

return CLib

close()

Closes the handle to the shared library.

function(name: string)

Retrieves the handle to a specific function in the shared library.

return ptr

define(name: string, return_type: type, …type)

Defines a new C function with the given name and return type.

When there are no more argument, it is declared that the function takes no argument.
define() expects a list of the argument/parameter types as expected by the function.

E.g.

define('myfunc', int, int, ptr)

Corresponds to the C declaration:

int myfunc(int a, void *b);

get_pointer()

Returns a pointer to the underlying module

return ptr