BlackJ Library 1.0 API Documentation

This is the documentation of the C API which allows a host application/program to interface with the BlackJ library (blackj.dll)

Introduction

The Blackj library is a standard ECMA 262 3rd Edition implementation. The ECMA 262 standard defines the requirements for languages similar to JavaScript or JScript.

The blackj.dll library is targeted to programmers and developers who want to add scripting capabilities to their software easily and fast.

The blackj.dll library is written in highly portable ANSI C code and it is distributed in the form of a dll. It can be used from any compiler/language that supports dlls such as C/C++, Delphi and others.

This is the complete set of functions.

void* bj_script_from_file(const char* path);
void* bj_script_from_source(const char* s);
Datum bj_script_exec(void* script);
void bj_script_free(void* script);
void bj_free(void* p);
Datum bj_eval(void* script,const char* source);
int bj_get_errcount(void* script);
int bj_get_msgcount(void* script);
char* bj_get_msg(void* script,const int idx);
void* bj_get_property(void* obj,const char* name);
void* bj_get_global_property(void* script,const char* name);
void* bj_add_property(void* script,void* obj,const char* name,Datum);
void* bj_add_global_property(void* script,const char* name,Datum);
int bj_delete_property(void* scr,void* obj,const char* name);
int bj_delete_global_property(void* script,const char* name);
void* bj_construct_object(void* script);
void* bj_construct_array(void* script);
void bj_set_array_elem(void* script,void* arr,Datum d,int idx);
void* bj_alloc_object(void* script);
void* bj_alloc_property(void* script);
void bj_free_object(void* script,void* obj);
void bj_free_property(void* script,void* prop);
void bj_set_property_data(void* scr,void* prop,Datum);
Datum bj_get_property_data(void* prop);
void bj_set_property_flag(void* prop,unsigned int flag);
unsigned int bj_get_property_flags(void* prop);
void bj_set_threshold(void* script,int);
void bj_set_output_handler(void* script,void(*)(const char*));
void bj_set_input_handler(void* script,void(*)(const char**));
void bj_write_str(const char* s,Datum*d);
void bj_call_by_name(void* script,const char* name,Datum args[],int arg_count, Datum* result);

API 1.0 REFERENCE

void* bj_script_from_file(const char* path);

It will parse the text file given in path and after the source is compiled in an internal form a pointer to the newly created script is returned. Use the bj_get_errcount function to see if there were any errors.

void* bj_script_from_source(const char* s);

It will parse the source code given in parameter s and after it is compiled in an internal form a pointer to the newly created script is returned. Use the bj_get_errcount function to see if there were any errors.

Datum bj_script_exec(void* script);

It will execute the whole script and return a result or VAL_NULL. Datum is a minimal variant type which is used in the runtime and which is defined in the blackj.h header file. It has a type and can hold a different number of data types including pointers to functions, numbers, booleans, strings etc.

void bj_script_free(void* script);

It will free all global objects and resources allocated for the script.

void bj_free(void* p);

This function is used mainly to free strings that are not required and passed as parameters. Since strings are always copied you must always free strings if not using them.

Datum bj_eval(void* script,const char* source);

It will execute the source code provided in source in the global scope of the script and return a value if there is one to return or VAL_NULL.

int bj_get_errcount(void* script);

Retrieves the number of errors encountered during script compilation or execution (run time errors)

int bj_get_msgcount(void* script);

Retrieves the number of messages including warnings, errors, exceptions or other messages generated by the runtime for this particular script. All scripts get their own runtime and each running script retains its own list of messages. This list can hold a maximum of 50 messages.

char* bj_get_msg(void* script,const int idx);

Retrieves the message at index position idx. Idx can have a value from 0 up to the value returned by (bj_get_msgcount – 1). In any case the number of messages per script cannot exceed 50.

void* bj_get_property(void* obj,const char* name);

Returns a property from object obj with name provided by the second parameter.

void* bj_get_global_property(void* script,const char* name);

Return a global property by providing its name. This can be a global variable that can hold a number, an object or a function (which can be either an object, a pointer to a mathematical function or a pointer to an internal function)

void* bj_add_property(void* script,void* obj,const char* name,Datum);

This function will add a new property and return a pointer to it. If there is already a property under the same name it will be ovewritten unless it has the FLAG_READ_ONLY flag. If this is the case you must first get a reference to the property by a call to bj_get_property, and then assign the new value or change its flags and call bj_add_property again.

void* bj_add_global_property(void* script,const char* name,Datum);

This function will add a new global property accessible to the running script as a global function.

int bj_delete_property(void* scr,void* obj,const char* name);

It will delete a property unless it has the FLAG_READ_ONLY flag. If this is the case you must first get a reference to the property by a call to bj_get_property, then clear the flag and call bj_delete_property again.

int bj_delete_global_property(void* script,const char* name);

It will delete the global property if it finds one.

void* bj_construct_object(void* script);

It will construct a native object and return a reference to it. You can then add properties to it and add it to the global scope or return it from a host function.

void* bj_construct_array(void* script);

It will construct a native array object and return a reference to it. You can then add items to it and add it to the global scope or return it from a host function. Although you can use the bj_add_property to add properties to it use the bj_set_array_elem to add indexed – numbered array elements.

void bj_set_array_elem(void* script,void* arr,Datum d,int idx);

It will add or replace an array element at position idx.

void* bj_alloc_object(void* script);

It will allocate the space and return a reference to an internal object.

void* bj_alloc_property(void* script);

It will allocate the space and return a reference to an internal property.

void bj_free_object(void* script,void* obj);

It will free an object allocated by a call to either bj_alloc_object or bj_construct_object

void bj_free_property(void* script,void* prop);

It will release memory allocated for a property. You will rarely need to call this function since any property added to an object will be free when the script is freed.

void bj_set_property_data(void* scr,void* prop,Datum);

It will assign the Datum to the property reference prop in script scr.

Datum bj_get_property_data(void* prop);

It will return the data from a property.

void bj_set_property_flag(void* prop,unsigned int flag);

It will set one flag. This usually can be FLAG_NO_OWN which means that the runtime should no free the data of this property (probably because you take responsibility to free it). FLAG_READ_ONLY means that this property’s data cannot be overwritten by code in the script nor this property can be deleted by a call to delete inside a script. There is also the FLAG_FREE_NAME flag which tells to the runtime to also free the string for a property name. If you have used a static string you don’t need to use this.

unsigned int bj_get_property_flags(void* prop);

It will return all flags as an unsigned int. The flags can be checked by using bitwise operators.

void bj_set_threshold(void* script,int);

It tells the bj_script_exec function to execute a limited number of internal instructions and then return. The type of the datum returned will be VAL_THRESHOLD so that you know if execution terminated because the script finished or the threshold reached. This allows you to maintain a list of scripts for example and execute a limited number of commands sequentially. This will be like having concurrent execution of many scripts in the same process without messing with threads.

void bj_set_output_handler(void* script,void()(const char));

You can provide a pointer to a function which will be called whenever a print statement is encountered in a script. The parameter contains the string that the script needs to print to the output. You can handle ths output in any way you want. If you don’t set an ouput handler the standard output will be used.

void bj_set_input_handler(void* script,void(*)(const char**));

You can provide a pointer to a function which will be called whenever a read(x) statement is encountered in a script. The parameter contains the string that will be passed as input to the script. If you don’t use an input handler and a script executes a read(x) statement in a GUI environment it will stop responding waiting for input forever.

void bj_write_str(const char* s,Datum* d);

Any string passed to the runtime must be copied. This function ensures that the string will be correcly assigned to the Datum.

void bj_call_by_name(void* script,const char* name,Datum args[],int arg_count,Datum* result);

Once you have loaded a script you may call any function defined in it by its name and pass to it any number of parameters as an array of Datum structures. You must provide the result Datum where any results by the call will be returned. The arg_count must be the corrent number of parameters passed (the length of args array).




	BlackJ Library 1.0 API Documentation Copyright © 2005 Evgenidis Konstantinos This is the documentation of the C API which allows a host application/program to interface with the BlackJ library (blackj.dll) Introduction The Blackj library is a standard ECMA 262 3rd Edition implementation. The ECMA 262 standard defines the requirements for languages similar to JavaScript or JScript. The blackj.dll library is targeted to programmers and developers who want to add scripting capabilities to their software easily and fast. The blackj.dll library is written in highly portable ANSI C code and it is distributed in the form of a dll. It can be used from any compiler/language that supports dlls such as C/C++, Delphi and others. This is the complete set of functions. void* bj_script_from_file(const char* path); void* bj_script_from_source(const char* s); Datum bj_script_exec(void* script); void bj_script_free(void* script); void bj_free(void* p); Datum bj_eval(void* script,const char* source); int bj_get_errcount(void* script); int bj_get_msgcount(void* script); char* bj_get_msg(void* script,const int idx); void* bj_get_property(void* obj,const char* name); void* bj_get_global_property(void* script,const char* name); void* bj_add_property(void* script,void* obj,const char* name,Datum); void* bj_add_global_property(void* script,const char* name,Datum); int bj_delete_property(void* scr,void* obj,const char* name); int bj_delete_global_property(void* script,const char* name); void* bj_construct_object(void* script); void* bj_construct_array(void* script); void bj_set_array_elem(void* script,void* arr,Datum d,int idx); void* bj_alloc_object(void* script); void* bj_alloc_property(void* script); void bj_free_object(void* script,void* obj); void bj_free_property(void* script,void* prop); void bj_set_property_data(void* scr,void* prop,Datum); Datum bj_get_property_data(void* prop); void bj_set_property_flag(void* prop,unsigned int flag); unsigned int bj_get_property_flags(void* prop); void bj_set_threshold(void* script,int); void bj_set_output_handler(void* script,void()(const char)); void bj_set_input_handler(void* script,void()(const char)); void bj_write_str(const char s,Datumd); void bj_call_by_name(void script,const char* name,Datum args[],int arg_count, Datum* result); API 1.0 REFERENCE void* bj_script_from_file(const char* path); It will parse the text file given in path and after the source is compiled in an internal form a pointer to the newly created script is returned. Use the bj_get_errcount function to see if there were any errors. void* bj_script_from_source(const char* s); It will parse the source code given in parameter s and after it is compiled in an internal form a pointer to the newly created script is returned. Use the bj_get_errcount function to see if there were any errors. Datum bj_script_exec(void* script); It will execute the whole script and return a result or VAL_NULL. Datum is a minimal variant type which is used in the runtime and which is defined in the blackj.h header file. It has a type and can hold a different number of data types including pointers to functions, numbers, booleans, strings etc. void bj_script_free(void* script); It will free all global objects and resources allocated for the script. void bj_free(void* p); This function is used mainly to free strings that are not required and passed as parameters. Since strings are always copied you must always free strings if not using them. Datum bj_eval(void* script,const char* source); It will execute the source code provided in source in the global scope of the script and return a value if there is one to return or VAL_NULL. int bj_get_errcount(void* script); Retrieves the number of errors encountered during script compilation or execution (run time errors) int bj_get_msgcount(void* script); Retrieves the number of messages including warnings, errors, exceptions or other messages generated by the runtime for this particular script. All scripts get their own runtime and each running script retains its own list of messages. This list can hold a maximum of 50 messages. char* bj_get_msg(void* script,const int idx); Retrieves the message at index position idx. Idx can have a value from 0 up to the value returned by (bj_get_msgcount – 1). In any case the number of messages per script cannot exceed 50. void* bj_get_property(void* obj,const char* name); Returns a property from object obj with name provided by the second parameter. void* bj_get_global_property(void* script,const char* name); Return a global property by providing its name. This can be a global variable that can hold a number, an object or a function (which can be either an object, a pointer to a mathematical function or a pointer to an internal function) void* bj_add_property(void* script,void* obj,const char* name,Datum); This function will add a new property and return a pointer to it. If there is already a property under the same name it will be ovewritten unless it has the FLAG_READ_ONLY flag. If this is the case you must first get a reference to the property by a call to bj_get_property, and then assign the new value or change its flags and call bj_add_property again. void* bj_add_global_property(void* script,const char* name,Datum); This function will add a new global property accessible to the running script as a global function. int bj_delete_property(void* scr,void* obj,const char* name); It will delete a property unless it has the FLAG_READ_ONLY flag. If this is the case you must first get a reference to the property by a call to bj_get_property, then clear the flag and call bj_delete_property again. int bj_delete_global_property(void* script,const char* name); It will delete the global property if it finds one. void* bj_construct_object(void* script); It will construct a native object and return a reference to it. You can then add properties to it and add it to the global scope or return it from a host function. void* bj_construct_array(void* script); It will construct a native array object and return a reference to it. You can then add items to it and add it to the global scope or return it from a host function. Although you can use the bj_add_property to add properties to it use the bj_set_array_elem to add indexed – numbered array elements. void bj_set_array_elem(void* script,void* arr,Datum d,int idx); It will add or replace an array element at position idx. void* bj_alloc_object(void* script); It will allocate the space and return a reference to an internal object. void* bj_alloc_property(void* script); It will allocate the space and return a reference to an internal property. void bj_free_object(void* script,void* obj); It will free an object allocated by a call to either bj_alloc_object or bj_construct_object void bj_free_property(void* script,void* prop); It will release memory allocated for a property. You will rarely need to call this function since any property added to an object will be free when the script is freed. void bj_set_property_data(void* scr,void* prop,Datum); It will assign the Datum to the property reference prop in script scr. Datum bj_get_property_data(void* prop); It will return the data from a property. void bj_set_property_flag(void* prop,unsigned int flag); It will set one flag. This usually can be FLAG_NO_OWN which means that the runtime should no free the data of this property (probably because you take responsibility to free it). FLAG_READ_ONLY means that this property’s data cannot be overwritten by code in the script nor this property can be deleted by a call to delete inside a script. There is also the FLAG_FREE_NAME flag which tells to the runtime to also free the string for a property name. If you have used a static string you don’t need to use this. unsigned int bj_get_property_flags(void* prop); It will return all flags as an unsigned int. The flags can be checked by using bitwise operators. void bj_set_threshold(void* script,int); It tells the bj_script_exec function to execute a limited number of internal instructions and then return. The type of the datum returned will be VAL_THRESHOLD so that you know if execution terminated because the script finished or the threshold reached. This allows you to maintain a list of scripts for example and execute a limited number of commands sequentially. This will be like having concurrent execution of many scripts in the same process without messing with threads. void bj_set_output_handler(void* script,void()(const char)); You can provide a pointer to a function which will be called whenever a print statement is encountered in a script. The parameter contains the string that the script needs to print to the output. You can handle ths output in any way you want. If you don’t set an ouput handler the standard output will be used. void bj_set_input_handler(void* script,void()(const char)); You can provide a pointer to a function which will be called whenever a read(x) statement is encountered in a script. The parameter contains the string that will be passed as input to the script. If you don’t use an input handler and a script executes a read(x) statement in a GUI environment it will stop responding waiting for input forever. void bj_write_str(const char s,Datum* d); Any string passed to the runtime must be copied. This function ensures that the string will be correcly assigned to the Datum. void bj_call_by_name(void* script,const char* name,Datum args[],int arg_count,Datum* result); Once you have loaded a script you may call any function defined in it by its name and pass to it any number of parameters as an array of Datum structures. You must provide the result Datum where any results by the call will be returned. The arg_count must be the corrent number of parameters passed (the length of args array).

Privacy Policy : Terms of Use