CodeScript
API
CodeScript
is a Windows DLL (dynamic link library) which has an API (application
programming interface) which allows the user to dynamically evaluate
expressions and execute statement sequences written in a C/C++-like
language.
Workspaces
CodeScript
manages a pool of memory called a "workspace" which contains
code and data. Although the current
release is limited to one workspace, the API requires a "workspace
handle" which is returned by CS_CreateWorkspace. The typedef "CSWS" is used for a
workspace handle. For example:
CSWS my_ws;
my_ws = CS_CreateWorkspace (hInstance);
CS_ExecuteFile (my_ws,
"MYMACRO.CS");
You
must pass the application instance handle to CS_CreateWorkspace. This was
passed to your application's WinMain entry point.
You
begin using CodeScript by calling CS_CreateWorkspace and you
finish
using it my calling CS_FreeWorkspace:
CS_FreeWorkspace (my_ws);
Values
------
All
data values are represented by a 32-bit "value descriptor"
which encodes the type of value and either the actual value or a
"pointer" to the value in the workspace. You need not know the details of how a
descriptor works, but should focus on what it does. The typedef "CSVAL" is used for a value descriptor.
Although
CodeScript itself has automatic memory management, it can't know when you are
done using a value. So, you need to
tell it by calling CS_Free. CodeScript
uses a reference counting scheme and releases values when their reference count
goes to zero.
Some API
calls return a "value". For
example:
CSVAL my_val, my_obj;
my_val = CS_Evaluate (my_ws,
"2+2");
CS_Free (my_val, my_val);
my_val = CS_Call (my_ws, "rand",
0, NULL);
CS_Free (my_val, my_val);
my_obj = CS_New (my_ws,
"my_class", 0, NULL);
my_val = CS_CallMember (my_ws, my_obj,
"size", 0, NULL);
CS_Free (my_val, my_val);
my_val = CS_GetGlobal (my_ws,
"int_size");
CS_Free (my_val, my_val);
Some
API calls accept values as arguments:
my_val = CS_Evaluate (my_ws, "sqrt
(x)");
CS_SetGlobal (my_ws, "y",
my_val);
CS_Free (my_ws, my_val);
Note
that CS_Free doesn't necessarily "free" the value immediately, but
tells CodeScript that your application has one less usage of the value and
CodeScript will free the value when it knows of no other usages of that value.
Some
API calls accept an array of values.
The CSVALP typedef is used to point to one or more CSVAL values. For example:
CSVAL args [2];
args [0] = CS_Real (my_ws, 2.0);
args [1] = CS_String (my_ws, argv [0]);
my_obj = CS_New (my_ws,
"my_class", 2, args);
The
fourth parameter of CS_New is a CSVALP.
String
arguments are declared using the Windows SDK LPSTR typedef (which is "char
FAR *".)
Ids vs
Names
------------
Internally,
CodeScript maps each name to a 32-bit "id" for efficiency. Some calls
accept an id as an alternative to a name (CS_GetGlobalId, CS_SetGlobalId, and
the global variable reader/writer functions.)
To get
the id for a name:
CSID my_name_id = CS_GetNameId (ws,
"my_name");
To get
the name for an id:
char my_name [CS_MAX_NAME_SIZE + 1];
CS_GetIdName (ws, my_name_id, my_name);
API
Functions
-------------
Here
are the C declarations of the CodeScript API functions. They may also be found in CSFUNC.H:
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Bool (
CSWS ws, /*
Handle for a CodeScript workspace. */
BOOL bool) /*
Boolean: TRUE or FALSE. */
/*
Converts a boolean to a CodeScript value. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Call (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR func, /* Pointer to function name. */
int argc, /*
Number of arguments. */
CSVALP args) /* Vector of arguments. */
/* Call
a function. */
/*
Returns the function return value. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_CallMember (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL obj, /*
A CodeScript object. */
LPSTR func, /* Pointer to function name. */
int argc, /*
Number of arguments. */
CSVALP args) /* Vector of arguments. */
/* Call
a member function for a CodeScript object. */
/* Returns
the function return value. */
/*--------------------------------------------------------------------*/
LPSTR
WINAPI CS_Class (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value, /* A CodeScript value. */
LPSTR buf, /*
Pointer to a buffer to receive class name. */
int limit) /*
Size of buffer. */
/*
Returns the class name for a CodeScript value. */
/*
Returns pointer to buffer. */
/*
Predefined classes: null, bool, int, real, string, array. */
/*--------------------------------------------------------------------*/
CSWS
WINAPI CS_CreateWorkspace (
HINSTANCE hInstance) /* Instance handle
for application. */
/*
Create a new macro workspace. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_Decl (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR p) /*
Pointer to declarations. */
/*
Process one or more CodeScript declarations. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_DeclDLLFunction (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR hdr, /*
Pointer to function header. */
LPSTR lib_path, /* Pointer to .DLL file path. */
LPSTR entry_name) /* Pointer to name of function entry point. */
/*
Declare a DLL entry point for use by CodeScript. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_DeclFunction (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR hdr, /*
Pointer to function header. */
FARPROC func) /* Pointer to C (WINAPI) function. */
/*
Declare an application C function for use by CodeScript. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_DeclPath (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR p, /*
Pointer to declarations. */
LPSTR path) /* Optional pointer to path for file read from. */
/*
Process one or more CodeScript declarations. */
/* Path
is specified for use in error messages. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_DefaultLibrary (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Reset library search list to default CodeScript library. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Evaluate (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR expr) /* Pointer to text of a CodeScript expression. */
/*
Evaluate a CodeScript expression. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Execute (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR macro) /* Pointer to macro text to execute. */
/*
Execute a CodeScript macro (a sequence of CodeScript statements.) */
/*
Returns the value of a "return" statement, if any, or the null value.
*/
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_ExecuteFile (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR path) /* Pointer to a CodeScript source file. */
/* Load
and execute a CodeScript macro file. */
/* If
extension is ".CS" then the file is treated as a sequence of
statements. If the extension is ".L" then the file is loaded as
a Liana application and its
"main" function is called.
Returns the value of a "return"
statement, if any, or the null value. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_ExecuteMacro (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR macro, /* Pointer to macro text to execute. */
/* Or NULL if text should be
read from file. */
LPSTR path, /* Pointer to path for file to read. */
/* If the macro argument is
non-NULL, this
argument is either NULL or the file name to
be used in error messages. */
int argc, /*
Number of arguments to pass to macro. */
CSVALP args, /* Vector of arguments. */
LPSTR extra_args) /* Extra arguments in DOS command-line format. */
/*
Execute a CodeScript macro (a sequence of CodeScript statements.) */
/*
Returns the value of a "return" statement, if any, or the null value.
*/
/* You
have a choice of passing text to be executed or the name of a
file containing the macro text. The file name can always be
specified since it is used in error
messages. The file extension
is used to distinguish a pure
"macro" from a full Liana application.
A Liana application uses the .L file
extension.
Arguments are optional. You can pass either CodeScript values as
arguments or a DOS command-line argument
string. The command-line
arguments are only used for a Liana
application (.L file.) The
argument vector is only used for CodeScript
macros (other than
.L file.)
*/
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_ExecutePath (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR macro, /* Pointer to macro text to execute. */
LPSTR path) /* Optional pointer to path for file read from. */
/*
Execute a CodeScript macro (a sequence of CodeScript statements.) */
/* Same
as CS_Execute, but error messages will include path. */
/*
Returns the value of a "return" statement, if any, or the null value.
*/
/*--------------------------------------------------------------------*/
CSERR
WINAPI CS_Free (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value. */
/*
Frees a CodeScript value. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_FreeWorkspace (
CSWS ws) /*
Handle for a CodeScript workspace. */
/* Free
a CodeScript workspace. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_GetGlobal (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR name) /* Pointer to name of a global variable. */
/*
Returns the value of a global variable. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_GetGlobalId (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSID id) /*
Id for name of global variable. */
/*
Returns the value of a global variable. */
/*--------------------------------------------------------------------*/
LPSTR
WINAPI CS_GetIdName (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSID id, /*
Id. */
LPSTR name) /* Buffer to receive name.
Declare as:
char name [CS_MAX_NAME +
1]; */
/* Get the
name for an Id. */
/*--------------------------------------------------------------------*/
LPSTR
WINAPI CS_GetMessage (
CSWS ws, /*
Handle for a CodeScript workspace. */
int i) /*
Message index (0..n-1.) */
/*
Returns the ith error messages from the message queue. */
/*
Messages start with the text "Line ", followed by the source line
number, followed by the text ":
", followed by the message.
Some messages may not be associated with a
specific source line.
*/
/*--------------------------------------------------------------------*/
int
WINAPI CS_GetMessageCount (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Returns the number of error messages in the message queue. */
/*--------------------------------------------------------------------*/
CSID
WINAPI CS_GetNameId (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR name) /* Pointer to name. */
/* Get
the Id for a name. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Int (
CSWS ws, /*
Handle for a CodeScript workspace. */
long i) /*
32-bit signed integer. */
/*
Converts a 32-bit signed integer to a CodeScript value. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_IsA (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value, /* A CodeScript value. */
LPSTR class_name) /* Pointer to a class name. */
/*
Returns TRUE if value's class is derived from a class. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_Library (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR path) /* Pointer to path for a Liana library. */
/* Add
a Liana library to the library search list. */
/* NOTE:
Libraries are searched in the reverse of the order they are
added to the list (i.e., the last library
is searched first.
This allows you to override existing
libraries. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_LoadDecl (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR path) /* Pointer to a CodeScript source file. */
/* Load
CodeScript declarations from a file. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_LogCalls (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Begin writing function call info to CALLS.LOG. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_New (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR class_name, /* Pointer to class name. */
int argc, /*
Number of arguments. */
CSVALP args) /* Vector of arguments. */
/*
Create an object of a class and call its constructor. */
/* Returns
the new object value. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_NoDefaultLibrary (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Reset library search list to default CodeScript library. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Null (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Returns the CodeScript null value. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_Real (
CSWS ws, /*
Handle for a CodeScript workspace. */
double d) /*
Double precision float. */
/*
Converts double precision float value to a CodeScript real value. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_SetGlobal (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR name, /* Pointer to name of a global variable. */
CSVAL value) /* New CodeScript value. */
/* Modifies
the value of a global variable. */
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_SetGlobalId (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSID id, /*
Id for name of global variable. */
CSVAL value) /* New CodeScript value. */
/*
Modifies the value of a global variable. */
/*--------------------------------------------------------------------*/
FARPROC
CS_SetGlobalReader (
CSWS ws, /*
Handle for a CodeScript workspace. */
FARPROC func) /* Pointer to global variable reader function. */
/* Set
the global variable reader function. */
/*
NOTE! For Windows (not Win32), the 2nd argument must be created
by calling the MakeProcInstance macro for
an exported function. */
/* The
"func" function should be declared as follows:
CSVAL FAR PASCAL func (CSWS ws, CSID id);
*/
/*
Returns the current reader function. */
/*--------------------------------------------------------------------*/
FARPROC
WINAPI CS_SetGlobalWriter (
CSWS ws, /*
Handle for a CodeScript workspace. */
FARPROC func) /* Pointer to global variable writer function. */
/* Set
the global variable writer function. */
/*
NOTE! For Windows (not Win32), the 2nd argument must be created
by calling the MakeProcInstance macro for
an exported function. */
/* The
"func" function should be declared as follows:
CSVAL FAR PASCAL func (CSWS ws, CSID id,
CSVAL new_value);
*/
/*
Returns the current writer function. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_ShowMessages (
CSWS ws) /*
Handle for a CodeScript workspace. */
/*
Display current CodeScript error messages. */
/*
Messages are displayed in a message box, one at a time. */
/* Returns
FALSE if there were any messages displayed. */
/* This
function is equivalent to the following source code:
int i, n;
n = CS_GetMessageCount (ws);
for (i = 0; i < n; i++)
#ifdef
_WINDOWS
MessageBox (NULL, CS_GetMessage (ws, i),
"CodeScript Error", 0);
#else
printf ("CodeScript Error:
%Fs\n", CS_GetMessage (ws, i));
#endif
return n > 0;
*/
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_String (
CSWS ws, /*
Handle for a CodeScript workspace. */
LPSTR s) /*
Pointer to a C string. */
/*
Converts a C string to a CodeScript string value. */
/*--------------------------------------------------------------------*/
BOOL
WINAPI CS_ToBool (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value. */
/*
Converts a CodeScript value to a boolean. */
/*--------------------------------------------------------------------*/
long
WINAPI CS_ToInt (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value. */
/*
Converts a CodeScript value to a 32-bit signed integer. */
/*--------------------------------------------------------------------*/
double
WINAPI CS_ToReal (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value. */
/*
Converts a CodeScript value to a double precision float. */
/*--------------------------------------------------------------------*/
void
WINAPI CS_ToReal2 (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value, /* A CodeScript value. */
double FAR *buf) /* Pointer to buffer to receive value. */
/*
Converts a CodeScript value to a double precision float. */
/* Returns
as a reference parameter for use by applications using
a Borland compiler which does not return
float values compatibly
with Microsoft. */
/*--------------------------------------------------------------------*/
LPSTR
WINAPI CS_ToString (
CSWS ws, /* Handle for a
CodeScript workspace. */
CSVAL value, /* A CodeScript value. */
LPSTR buf, /*
Pointer to a buffer to receive string. */
int limit) /*
Size of buffer. */
/*
Converts a CodeScript value to a C string. */
/*
Returns pointer to the buffer argument. */
/*--------------------------------------------------------------------*/
CSTYPE
WINAPI CS_Type (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value. */
/*
Returns the type of a value. */
/* Type
codes are:
CSTYPE_Bogus - Garbage value
CSTYPE_Null - null
CSTYPE_Bool - boolean
CSTYPE_Int -
integer
CSTYPE_Real - real
CSTYPE_String - string
CSTYPE_Object - user-defined object
*/
/*--------------------------------------------------------------------*/
long
WINAPI CS_ArraySize (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value) /* A CodeScript value
representing an array. */
;
/*--------------------------------------------------------------------*/
CSVAL
WINAPI CS_ArrayGet (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL value, /* A CodeScript value representing an array. */
long i) /* Subscript */
/*
Returns a CSVAL for the ith element in the array. */
;
/*--------------------------------------------------------------------*/
void
WINAPI CS_ArrayPut (
CSWS ws, /*
Handle for a CodeScript workspace. */
CSVAL arrayvalue, /* A CodeScript value representing an array. */
long i, /* Subscript */
CSVAL newvalue /* value to be inserted
into array */
) /* Subscript */
/*--------------------------------------------------------------------*/
Simplified
Function List
------------------------
For
convenient reference here are the raw C function prototypes for
the
CodeScript API functions:
long CS_ArraySize (CSWS ws, CSVAL value);
CSVAL CS_ArrayGet (CSWS ws, CSVAL arrayvalue, long
i);
void CS_ArrayPut (CSWS ws, CSVAL arrayvalue, long
i, CSVAL newvalue);
CSVAL CS_Bool (CSWS ws, BOOL bool)
CSVAL CS_Call (CSWS ws, LPSTR func, int argc, CSVALP
args);
CSVAL CS_CallMember (CSWS ws, CSVAL obj, LPSTR func,
int argc, CSVALP args);
LPSTR CS_Class (CSWS ws, CSVAL value, LPSTR buf, int
limit);
CSWS CS_CreateWorkspace (HINSTANCE hInstance);
BOOL CS_Decl (CSWS ws, LPSTR p);
BOOL CS_DeclDLLFunction (CSWS ws, LPSTR hdr, LPSTR
lib_path, LPSTR entry_name);
BOOL CS_DeclFunction (CSWS ws, LPSTR hdr, FARPROC
func);
BOOL CS_DeclPath (CSWS ws, LPSTR p, LPSTR path);
void CS_DefaultLibrary (CSWS ws);
CSVAL CS_Evaluate (CSWS ws, LPSTR expr);
CSVAL CS_Execute (CSWS ws, LPSTR macro);
CSVAL CS_ExecuteFile (CSWS ws, LPSTR path);
CSVAL CS_ExecuteMacro (CSWS ws, LPSTR macro, LPSTR
path, int argc, CSVALP args, LPSTR extra_args);
CSVAL CS_ExecutePath (CSWS ws, LPSTR macro, LPSTR
path);
CSERR CS_Free (CSWS ws, CSVAL value);
void CS_FreeWorkspace (CSWS ws);
CSVAL CS_GetGlobal (CSWS ws, LPSTR name);
CSVAL CS_GetGlobalId (CSWS ws, CSID id);
LPSTR CS_GetIdName (CSWS ws, CSID id, LPSTR name);
LPSTR CS_GetMessage (CSWS ws, int i);
int CS_GetMessageCount (CSWS ws);
CSVAL CS_Int (CSWS ws, long i);
BOOL CS_IsA (CSWS ws, CSVAL value, LPSTR
class_name);
void CS_Library (CSWS ws);
BOOL CS_LoadDecl (CSWS ws, LPSTR path);
void CS_LogCalls (CSWS ws);
CSVAL CS_New (CSWS ws, LPSTR class_name, int argc,
CSVALP args);
void CS_NoDefaultLibrary (CSWS ws);
CSVAL CS_Null (CSWS ws);
CSVAL CS_Real (CSWS ws, double d);
CSVAL CS_SetGlobal (CSWS ws, LPSTR name, CSVAL
value);
CSVAL CS_SetGlobalId (CSWS ws, CSID id, CSVAL value);
FARPROC CS_SetGlobalReader (CSWS ws, FARPROC func);
FARPROC CS_SetGlobalWriter (CSWS ws, FARPROC func);
BOOL CS_ShowMessages (CSWS ws);
CSVAL CS_String (CSWS ws, LPSTR s);
BOOL CS_ToBool (CSWS ws, CSVAL value);
long CS_ToInt (CSWS ws, CSVAL value);
double CS_ToReal (CSWS ws, CSVAL value);
void CS_ToReal2 (CSWS ws, CSVAL value, double FAR
*buf);
LPSTR CS_ToString (CSWS ws, CSVAL value, LPSTR buf,
int limit);
CSTYPE CS_Type (CSWS ws, CSVAL value);
Copyright
1995 John W. Krupansky d/b/a Base Technology
[End of API.TXT]