ctalk.html

C-Talk is interpreted scripting language with C-like syntax and dynamic type checking. Variables in

<TR><TD><code>getType(x)</code></TD><TD>returns argument's type code (integer as defined in ctalk.h)</TD></TR>
<TR><TD><code>getTypeName(x)</code></TD><TD>returns argument's type name</TD></TR>
</TABLE>

<H3>Miscellaneous</H3>
<TABLE BORDER>
<TR><TD><code>rc = execute("cp f.dbs f.sav") </code></TD><TD>execute shell command and wait for result</TD></TR>
<TR><TD><code>t = time()            </code></TD><TD>get current system time (seconds)</TD></TR>
<TR><TD><code>assert(i >= 0)        </code></TD><TD>check the assert condition, throw exception if predicate is false </TD></TR>
<TR><TD><code>loadDLL("test.dll")   </code></TD><TD>load dynamic linking library</TD></TR>
<TR><TD><code>loadModule("test.ctk")</code></TD><TD>load C-Talk module</TD></TR>
<TR><TD><code>chdir(path)           </code></TD><TD>change current directory</TD></TR>
<TR><TD><code>dir = pwd()           </code></TD><TD>get name of working directory</TD></TR>
<TR><TD><code>sleep(seconds)        </code></TD><TD>sleep specified amount of seconds</TD></TR>
<TR><TD><code>options("socket")     </code></TD><TD>when called without argumetns, returns array of command line options, or gets value of specified option</TD></TR>
<TR><TD><code>printExceptionStackTrace()</code></TD><TD>print stack trace for the frame where exception was thrown,
till the frame where it is catched</TD></TR>
</TABLE>


<H2>Program execution</H2>
C-Talk is command line tool which accepts list of files with C-Talk programs 
as parameters:

<PRE>
$ ctalk file-1 file-2 ...
</PRE>

The loaded module is first compiled to byte code and the all global-level 
statements are executed. For example, the result of following program execution:

<PRE>
hello = "Hello World";

foo(hello);

foo(s) { 
	println(s);
}
</PRE>

will be printing of "Hello World" line at the screen



<H2>C-Talk primitives</H2>
C-Talk system library includes only basci set of functions. 
It makes it possible to make C-Talk distribution very compact.
It was inteded that particular extensions will be added to C-Talk using primitives mechanism. 
Most of C-Talk functions will be implemented in C/C++. 
C-Talk provides special library for mapping C-Talk type to C++ types. C-Talk primitives can accept varying 
number of arguments. To declare C-Talk primitive, C programmer should define 
the function:

<PRE>
CtkObject foo_func(int nArgs, CtkObject args[]) { ... }
REGISTER(foo_func, "foo");
</PRE>

The code above defines the function "foo_func" and registers it as C-Talk 
primitive "foo". Now C-Talk program can call "foo()" function in the same way 
as it was declared in C-Talk.

The C-Talk C-interface library provides methods for creating objects of C-Talk
types, converting <code>CtkObject</code> with type checking to primitive C 
types, operations with C-Talk types (such as strings, arrays and mutexes), 
throwing C-Talk exceptions. Macros <B>IS_</B>XXX can be used to check object type, 
macros <B>TO_</B>XXX perform conversion to the specified type or throw exception if type 
doesn't match, macro <B>MAKE_</B>XXX create object with specified type and value, 
mcaros <B>CHECK_PRIMITIVE_N_ARGS</B> and <B>CHECK_PRIMITIVE_ARGUMENT</B> can be used to check number 
of passed arguments and type of each argument.<P>

C-Talk provide even more convinient weay for checking types passed arguments.
Function <code>ctkParseArguments</code> takes format string and optional list of arguments palceholder and
perform necessary checks and conversions.

<PRE>
void ctkParseArguments(int nArgs, CtkObject* args, char const* format, ...);
</PRE>
<DL>
<DT>Parameters:
<DD><B>nArgs</B> - number of arguments passed to the function (first parameter of any primitive)
<DD><B>args</B> - array of arguments passed to the function (second parameter of any primitive)
<DD><B>format</B> - format string specifying number and types of expected arguments.<BR>
In format string each character describes one correpondent parameter.<BR>
Upercase character in format string cause checking of the argument type and copying CtkObject to the placeholder.<BR>
Lowercase character in format string cause checking and storing arguments in native C format.<BR>
',' character in format string split mandatory and optional parameters. <BR>
If type or number of parameters doesn't match, exception is thrown.
<TABLE BORDER>
<TR><TH>Format symbol</TH><TH>Expected C-Talk type of argument</TH><TH>Type of placeholder for parameter value</TH></TR>
<TR><TD>o</TD><TD>any</TD><TD>CtkObject</TD></TR>
<TR><TD>i</TD><TD>CTK_INTEGER</TD><TD>ctk_integer</TD></TR>
<TR><TD>r</TD><TD>CTK_REAL</TD><TD>ctk_real</TD></TR>
<TR><TD>p</TD><TD>CTK_RAW_POINTER or CTK_NULL</TD><TD>void*</TD></TR>
<TR><TD>P</TD><TD>CTK_RAW_POINTER</TD><TD>CtkObject</TD></TR>
<TR><TD>s</TD><TD>CTK_STRING or CTK_NULL</TD><TD>char*</TD></TR>
<TR><TD>S</TD><TD>CTK_STRING</TD><TD>CtkObject</TD></TR>
<TR><TD>a</TD><TD>CTK_ARRAY or CTK_NULL</TD><TD>CtkArray*</TD></TR>
<TR><TD>A</TD><TD>CTK_ARRAY</TD><TD>CtkObject</TD></TR>
<TR><TD>f</TD><TD>CTK_FILE or CTK_NULL</TD><TD>CtkFile*</TD></TR>
<TR><TD>F</TD><TD>CTK_FILE</TD><TD>CtkObject</TD></TR>
<TR><TD>m</TD><TD>CTK_MUTEX or CTK_NULL</TD><TD>CtkMutex*</TD></TR>
<TR><TD>M</TD><TD>CTK_MUTEX</TD><TD>CtkObject</TD></TR>
<TR><TD>t</TD><TD>CTK_THREAD or CTK_NULL</TD><TD>CtkThread*</TD></TR>
<TR><TD>T</TD><TD>CTK_THREAD</TD><TD>CtkObject</TD></TR>
<TR><TD>l</TD><TD>CTK_FUNCTION or CTK_NULL</TD><TD>CtkFunction*</TD></TR>
<TR><TD>L</TD><TD>CTK_FUNCTION</TD><TD>CtkObject</TD></TR>
<TR><TD>u</TD><TD>CTK_USER_TYPE or CTK_NULL</TD><TD>void*</TD></TR>
<TR><TD>U</TD><TD>CTK_USER_TYPE</TD><TD>CtkObject</TD></TR>
</TABLE>
</DL><P>

Example:

<pre>
CtkObject myPrimitive(int nArgs, CtkObject* args) {
    char*       s;
    ctk_integer i;
    ctk_real    r;
    CtkObject   o;

    ctkParseArguments(nArgs, args, "siro", &s, &i, &r, &o);
    ...
}
</pre><P>

<H2>Loading DLLs</H2>
It is possible to load DLL using <code<>loadDLL</code> method.
The single parameter of this function contains name of loaded DLL.
If this name contains no extension, then default OS extension will be added
(".dll" at windows, ".so" at Unix).<P>

When DLL is loaded, all primitives registered in this DLL becomes available. 
But since these primitives descriptors were not available at compilation time,
you can invoke these primitives in the module loaded the DLL only by specifying function name as string:

<pre>
loadDLL("mydll");
"myfunc"("hello world");
</pre>

If you want to access primitives defined in DLL in normal way, 
you should place you code in separate module and load it after loading of DLL:

<pre>
loadDLL("mydll");
loadModule("mymodule");

-----------------------
mymodule.ctk:
-----------------------
myfunc("hello world");
</pre>

C-Talk is also able to transparently call DLL functions.
The only restriction is that these functions should not have more than 5 formal parameters, 
parameter type should be <code>int</code>, <code>char*</code> or pointer to any user defined type
and function should return <int>, pointer or nothing. C-Talk detects function profile from 
types of passed arguments. So it is not able to check if formal parameters of the function 
are compatible with passed actual parameter. If you pass floating point value to function expecting
int argument, then most likely it will cause system crash. 
Call of native DLL function is done as call of norm,al primitive:

<pre>
loadDLL("User32");
"MessageBoxA"(0, "Correct text", "MsgBox Sample", 0);
</pre>

If you want to write <code>MessageBoxA()</code> instead of <code>"MessageBoxA"()</code>, 
you should place your code in separate module and load it after loading of DLL.<P>

DLL function called in this way is assumed to return value of raw pointer type.
So it can be pointer to any user defined type which you can then pass as argument
to other DLL functions. If the function really returns integer, then you can convert 
returned value using <code>integer()</code> function.


</BODY>
</HTML>