[//000000001]: # (critcl\_cproc\_types \- C Runtime In Tcl $CriTcl$) [//000000002]: # (Generated from file 'critcl\_cproc\.man' by tcllib/doctools with format 'markdown') [//000000003]: # (Copyright © Jean\-Claude Wippler) [//000000004]: # (Copyright © Steve Landers) [//000000005]: # (Copyright © 2011\-2024 Andreas Kupries) [//000000006]: # (critcl\_cproc\_types$n$ 3\.3\.1 doc "C Runtime In Tcl $CriTcl$")

[ Table Of Contents | Keyword Index ]

# NAME critcl\_cproc\_types \- CriTcl cproc Type Reference # Table Of Contents - [Table Of Contents](#toc) - [Synopsis](#synopsis) - [Description](#section1) - [Standard argument types](#section2) - [Standard result types](#section3) - [Advanced: Adding types](#section4) - [Examples](#section5) - [A Simple Procedure](#subsection1) - [More Builtin Types: Strings](#subsection2) - [Custom Types, Introduction](#subsection3) - [Custom Types, Semi\-trivial](#subsection4) - [Custom Types, Support structures](#subsection5) - [Custom Types, Results](#subsection6) - [Authors](#section6) - [Bugs, Ideas, Feedback](#section7) - [Keywords](#keywords) - [Category](#category) - [Copyright](#copyright) # SYNOPSIS package require Tcl 8\.6 package require critcl ?3\.3\.1? [__::critcl::has\-resulttype__ *name*](#1) [__::critcl::resulttype__ *name* *body* ?*ctype*?](#2) [__::critcl::resulttype__ *name* __=__ *origname*](#3) [__::critcl::has\-argtype__ *name*](#4) [__::critcl::argtype__ *name* *body* ?*ctype*? ?*ctypefun*?](#5) [__::critcl::argtype__ *name* __=__ *origname*](#6) [__::critcl::argtypesupport__ *name* *code* ?*guard*?](#7) [__::critcl::argtyperelease__ *name* *code*](#8) # DESCRIPTION Be welcome to the *C Runtime In Tcl* $short: *[CriTcl](critcl\.md)*$, a system for embedding and using C code from within [Tcl](http://core\.tcl\-lang\.org/tcl) scripts\. This document is a breakout of the descriptions for the predefined argument\- and result\-types usable with the __critcl::cproc__ command, as detailed in the reference manpage for the __[critcl](critcl\.md)__ package, plus the information on how to extend the predefined set with custom types\. The breakout was made to make this information easier to find $toplevel document vs\. having to search the large main reference$\. Its intended audience are developers wishing to write Tcl packages with embedded C code\. # Standard argument types Before going into the details first a quick overview: > CriTcl type | C type | Tcl type | Notes > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > Tcl\_Interp\* | Tcl\_Interp\* | n/a | *Special*, only first > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > Tcl\_Obj\* | Tcl\_Obj\* | Any | *Read\-only* > object | | | Alias of __Tcl\_Obj\*__ above > list | critcl\_list | List | *Read\-only* > \[\], \[\*\] | | | Alias of __list__ above > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > \[N\] | | | Restricted __list__\-types\. > type\[\], type\[N\] | | | Length\-limited $\[\.\.\]$, expected > \[\]type, \[N\]type | | | element type, or both\. > | | | > | | | Element types can be all known argument > | | | types, except for any kind of list\. > | | | IOW multi\-dimensional lists are not > | | | supported\. > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > char\* | const char\* | Any | *Read\-only*, *string rep* > pstring | critcl\_pstring | Any | *Read\-only* > bytes | critcl\_bytes | ByteArray | *Read\-only* > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > int | int | Int | > long | long | Long | > wideint | Tcl\_WideInt | WideInt | > double | double | Double | > float | float | Double | > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > X > N | | | For X in __int__ \.\.\. __float__ above\. > X >= N | | | The C types are as per the base type X\. > X < N | | | N, A, B are expected to be constant integer > X <= N | | | numbers for types __int__, __long__, > X > A < B | | | and __wideint__\. For types __double__ > etc\. | | | and __float__ the N, A, and B can be floating > | | | point numbers\. Multiple restrictions are > | | | fused as much as possible to yield at most > | | | both upper and lower limits\. > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > boolean | int | Boolean | > bool | | | Alias of __boolean__ above > \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > channel | Tcl\_Channel | String | Assumed to be registered > unshared\-channel | Tcl\_Channel | String | As above, limited to current interpreter > take\-channel | Tcl\_Channel | String | As above, C code takes ownership And now the details: - Tcl\_Interp\* *Attention*: This is a *special* argument type\. It can *only* be used by the *first* argument of a function\. Any other argument using it will cause critcl to throw an error\. When used, the argument will contain a reference to the current interpreter that the function body may use\. Furthermore the argument will *not* be an argument of the Tcl command for the function\. This is useful when the function has to do more than simply returning a value\. Examples would be setting up error messages on failure, or querying the interpreter for variables and other data\. - Tcl\_Obj\* - object The function takes an argument of type __Tcl\_Obj\*__\. No argument checking is done\. The Tcl level word is passed to the argument as\-is\. Note that this value must be treated as *read\-only* $except for hidden changes to its intrep, i\.e\. *shimmering*$\. - pstring The function takes an argument of type __critcl\_pstring__ containing the original __Tcl\_Obj\*__ reference of the Tcl argument, plus the length of the string and a pointer to the character array\. typedef struct critcl_pstring { Tcl_Obj* o; const char* s; int len; } critcl_pstring; Note the *const*\. The string is *read\-only*\. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later\. - list - \[\] - \[\*\] The function takes an argument of type __critcl\_list__ containing the original __Tcl\_Obj\*__ reference of the Tcl argument, plus the length of the Tcl list and a pointer to the array of the list elements\. typedef struct critcl_list { Tcl_Obj* o; Tcl_Obj* const* v; int c; } critcl_list; The Tcl argument must be convertible to __List__, an error is thrown otherwise\. Note the *const*\. The list is *read\-only*\. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later\. Further note that the system understands a number of more complex syntactical forms which all translate into forms of lists under the hood, as described by the following points\. - \[N\] A *list* type with additional checks limiting the length to __N__, an integer number greater than zero\. - \[\]type - type\[\] A *list* type whose elements all have to be convertible for *type*\. All known types, including user\-defined, are allowed, except for __list__ and derivates\. In other words, multi\-dimensional lists are not supported\. The function will take a structure argument of the general form typedef struct critcl_list_... { Tcl_Obj* o; int c; (Ctype)* v; } critcl_list_...; where __$Ctype$__ represents the C type for values of type __type__\. - \[N\]type - type\[N\] These are __list__ types combining the elements of [N] and []type \. As an example, the specification of int[3] a describes argument *a* as a list of exactly 3 elements, all of which have to be of type __int__\. Note that this example can also be written in the more C\-like form of int a[3] \. The system will translate this internally to the first shown form\. - bytes This is the *new* and usable __ByteArray__ type\. The function takes an argument of type __critcl\_bytes__ containing the original __Tcl\_Obj\*__ reference of the Tcl argument, plus the length of the byte array and a pointer to the byte data\. typedef struct critcl_bytes { Tcl_Obj* o; const unsigned char* s; int len; } critcl_list; The Tcl argument must be convertible to __ByteArray__, an error is thrown otherwise\. Note the *const*\. The bytes are *read\-only*\. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later\. - char\* The function takes an argument of type __const char\*__\. The string representation of the Tcl argument is passed in\. Note the *const*\. The string is *read\-only*\. Any modification can have arbitrary effects, from pulling out the rug under the script because of string value and internal representation not matching anymore, up to crashes anytime later\. - double The function takes an argument of type __double__\. The Tcl argument must be convertible to __Double__, an error is thrown otherwise\. - double > N - double >= N - double < N - double <= N These are variants of *double* above, restricting the argument value to the shown relation\. An error is thrown for Tcl arguments outside of the specified range\. The limiter *N* has to be a constant floating point value\. It is possible to use multiple limiters\. For example *double > A > B <= C*\. The system will fuse them to a single upper/lower limit $or both$\. The system will reject limits describing an empty range of values, or a range containing only a single value\. - float The function takes an argument of type __float__\. The Tcl argument must be convertible to __Double__, an error is thrown otherwise\. - float > N - float >= N - float < N - float <= N These are variants of *float* above, restricting the argument value to the shown relation\. An error is thrown for Tcl arguments outside of the specified range\. The limiter *N* has to be a constant floating point value\. It is possible to use multiple limiters\. For example *float > A > B <= C*\. The system will fuse them to a single upper/lower limit $or both$\. The system will reject limits describing an empty range of values, or a range containing only a single value\. - boolean - bool The function takes an argument of type __int__\. The Tcl argument must be convertible to __Boolean__, an error is thrown otherwise\. - channel The function takes an argument of type __Tcl\_Channel__\. The Tcl argument must be convertible to type __Channel__, an error is thrown otherwise\. The channel is further assumed to be *already registered* with the interpreter\. - unshared\-channel This type is an extension of __channel__ above\. All of the information above applies\. Beyond that the channel must not be shared by multiple interpreters, an error is thrown otherwise\. - take\-channel This type is an extension of __unshared\-channel__ above\. All of the information above applies\. Beyond that the code removes the channel from the current interpreter without closing it, and disables all pre\-existing event handling for it\. With this the function takes full ownership of the channel in question, taking it away from the interpreter invoking it\. It is then responsible for the lifecycle of the channel, up to and including closing it\. Should the system the function is a part of wish to return control of the channel back to the interpeter it then has to use the result type __return\-channel__\. This will undo the registration changes made by this argument type\. *Note* however that the removal of pre\-existing event handling done here cannot be undone\. *Attention* Removal from the interpreter without closing the channel is effected by incrementing the channel's reference count without providing an interpreter, before decrementing the same for the current interpreter\. This leaves the overall reference count intact without causing Tcl to close it when it is removed from the interpreter structures\. At this point the channel is effectively a globally\-owned part of the system not associated with any interpreter\. The complementary result type then runs this sequence in reverse\. And if the channel is never returned to Tcl either the function or the system it is a part of have to unregister the global reference when they are done with it\. - int The function takes an argument of type __int__\. The Tcl argument must be convertible to __Int__, an error is thrown otherwise\. - int > N - int >= N - int < N - int <= N These are variants of *int* above, restricting the argument value to the shown relation\. An error is thrown for Tcl arguments outside of the specified range\. The limiter *N* has to be a constant integer value\. It is possible to use multiple limiters\. For example *int > A > B <= C*\. The system will fuse them to a single upper/lower limit $or both$\. The system will reject limits describing an empty range of values, or a range containing only a single value\. - long The function takes an argument of type __long int__\. The Tcl argument must be convertible to __Long__, an error is thrown otherwise\. - long > N - long >= N - long < N - long <= N These are variants of *long* above, restricting the argument value to the shown relation\. An error is thrown for Tcl arguments outside of the specified range\. The limiter *N* has to be a constant integer value\. It is possible to use multiple limiters\. For example *long > A > B <= C*\. The system will fuse them to a single upper/lower limit $or both$\. The system will reject limits describing an empty range of values, or a range containing only a single value\. - wideint The function takes an argument of type __Tcl\_WideInt__\. The Tcl argument must be convertible to __WideInt__, an error is thrown otherwise\. - wideint > N - wideint >= N - wideint < N - wideint <= N These are variants of *wideint* above, restricting the argument value to the shown relation\. An error is thrown for Tcl arguments outside of the specified range\. The limiter *N* has to be a constant integer value\. It is possible to use multiple limiters\. For example *wideint > A > B <= C*\. The system will fuse them to a single upper/lower limit $or both$\. The system will reject limits describing an empty range of values, or a range containing only a single value\. - void\* # Standard result types Before going into the details first a quick overview: > CriTcl type | C type | Tcl type | Notes > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > void | n/a | n/a | Always OK\. Body sets result > ok | int | n/a | Result code\. Body sets result > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > int | int | Int | > boolean | | | Alias of __int__ above > bool | | | Alias of __int__ above > long | long | Long | > wideint | Tcl\_WideInt | WideInt | > double | double | Double | > float | float | Double | > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > char\* | char\* | String | *Makes a copy* > vstring | | | Alias of __char\*__ above > const char\* | const char\* | | Behavior of __char\*__ above > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > string | | String | Freeable string set directly > | | | *No copy is made* > dstring | | | Alias of __string__ above > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > | | | For all below: Null is ERROR > | | | Body has to set any message > Tcl\_Obj\* | Tcl\_Obj\* | Any | *refcount \-\-* > object | | | Alias of __Tcl\_Obj\*__ above > Tcl\_Obj\*0 | | Any | *refcount unchanged* > object0 | | | Alias of __Tcl\_Obj\*0__ above > \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > known\-channel | Tcl\_Channel | String | Assumes to already be registered > new\-channel | Tcl\_Channel | String | New channel, will be registered > return\-channel | Tcl\_Channel | String | Inversion of take\-channel And now the details: - Tcl\_Obj\* - object If the returned __Tcl\_Obj\*__ is __NULL__, the Tcl return code is __TCL\_ERROR__ and the function should [set an error mesage](https://www\.tcl\-lang\.org/man/tcl/TclLib/SetResult\.htm) as the interpreter result\. Otherwise, the returned __Tcl\_Obj\*__ is set as the interpreter result\. Note that setting an error message requires the function body to have access to the interpreter the function is running in\. See the argument type __Tcl\_Interp\*__ for the details on how to make that happen\. Note further that the returned __Tcl\_Obj\*__ should have a reference count greater than __0__\. This is because the converter decrements the reference count to release possession after setting the interpreter result\. It assumes that the function incremented the reference count of the returned __Tcl\_Obj\*__\. If a __Tcl\_Obj\*__ with a reference count of __0__ were returned, the reference count would become __1__ when set as the interpreter result, and immediately thereafter be decremented to __0__ again, causing the memory to be freed\. The system is then likely to crash at some point after the return due to reuse of the freed memory\. - Tcl\_Obj\*0 - object0 Like __Tcl\_Obj\*__ except that this conversion assumes that the returned value has a reference count of __0__ and *does not* decrement it\. Returning a value whose reference count is greater than __0__ is therefore likely to cause a memory leak\. Note that setting an error message requires the function body to have access to the interpreter the function is running in\. See the argument type __Tcl\_Interp\*__ for the details on how to make that happen\. - new\-channel A __String__ Tcl\_Obj holding the name of the returned __Tcl\_Channel__ is set as the interpreter result\. The channel is further assumed to be *new*, and therefore registered with the interpreter to make it known\. - known\-channel A __String__ Tcl\_Obj holding the name of the returned __Tcl\_Channel__ is set as the interpreter result\. The channel is further assumed to be *already registered* with the interpreter\. - return\-channel This type is a variant of __new\-channel__ above\. It varies slightly from it in the registration sequence to be properly complementary to the argument type __take\-channel__\. A __String__ Tcl\_Obj holding the name of the returned __Tcl\_Channel__ is set as the interpreter result\. The channel is further assumed to be *new*, and therefore registered with the interpreter to make it known\. - char\* - vstring A __String__ Tcl\_Obj holding a *copy* of the returned __char\*__ is set as the interpreter result\. If the value is allocated then the function itself and the extension it is a part of are responsible for releasing the memory when the data is not in use any longer\. - const char\* Like __char\*__ above, except that the returned string is __const__\-qualified\. - string - dstring The returned __char\*__ is directly set as the interpreter result *without making a copy*\. Therefore it must be dynamically allocated via __Tcl\_Alloc__\. Release happens automatically when the Interpreter finds that the value is not required any longer\. - double - float The returned __double__ or __float__ is converted to a __Double__ Tcl\_Obj and set as the interpreter result\. - boolean - bool The returned __int__ value is converted to an __Int__ Tcl\_Obj and set as the interpreter result\. - int The returned __int__ value is converted to an __Int__ Tcl\_Obj and set as the interpreter result\. - long The returned __long int__ value is converted to a __Long__ Tcl\_Obj and set as the interpreter result\. - wideint The returned __Tcl\_WideInt__ value is converted to a __WideInt__ Tcl\_Obj and set as the interpreter result\. - ok The returned __int__ value becomes the Tcl return code\. The interpreter result is left untouched and can be set by the function if desired\. Note that doing this requires the function body to have access to the interpreter the function is running in\. See the argument type __Tcl\_Interp\*__ for the details on how to make that happen\. - void The function does not return a value\. The interpreter result is left untouched and can be set by the function if desired\. # Advanced: Adding types While the __critcl::cproc__ command understands the most common C types $as per the previous 2 sections$, sometimes this is not enough\. To get around this limitation the commands in this section enable users of __[critcl](critcl\.md)__ to extend the set of argument and result types understood by __critcl::cproc__\. In other words, they allow them to define their own, custom, types\. - __::critcl::has\-resulttype__ *name* This command tests if the named result\-type is known or not\. It returns a boolean value, __true__ if the type is known and __false__ otherwise\. - __::critcl::resulttype__ *name* *body* ?*ctype*? This command defines the result type *name*, and associates it with the C code doing the conversion $*body*$ from C to Tcl\. The C return type of the associated function, also the C type of the result variable, is *ctype*\. This type defaults to *name* if it is not specified\. If *name* is already declared an error is thrown\. *Attention\!* The standard result type __void__ is special as it has no accompanying result variable\. This cannot be expressed by this extension command\. The *body*'s responsibility is the conversion of the functions result into a Tcl result and a Tcl status\. The first has to be set into the interpreter we are in, and the second has to be returned\. The C code of *body* is guaranteed to be called last in the wrapper around the actual implementation of the __cproc__ in question and has access to the following environment: * __interp__ A Tcl\_Interp\* typed C variable referencing the interpreter the result has to be stored into\. * __rv__ The C variable holding the result to convert, of type *ctype*\. As examples here are the definitions of two standard result types: resulttype int { Tcl_SetObjResult(interp, Tcl_NewIntObj(rv)); return TCL_OK; } resulttype ok { /* interp result must be set by cproc body */ return rv; } int - __::critcl::resulttype__ *name* __=__ *origname* This form of the __resulttype__ command declares *name* as an alias of result type *origname*, which has to be defined already\. If this is not the case an error is thrown\. - __::critcl::has\-argtype__ *name* This command tests if the named argument\-type is known or not\. It returns a boolean value, __true__ if the type is known and __false__ otherwise\. - __::critcl::argtype__ *name* *body* ?*ctype*? ?*ctypefun*? This command defines the argument type *name*, and associates it with the C code doing the conversion $*body*$ from Tcl to C\. *ctype* is the C type of the variable to hold the conversion result and *ctypefun* is the type of the function argument itself\. Both types default to *name* if they are the empty string or are not provided\. If *name* is already declared an error is thrown\. *body* is a C code fragment that converts a Tcl\_Obj\* into a C value which is stored in a helper variable in the underlying function\. *body* is called inside its own code block to isolate local variables, and the following items are in scope: * __interp__ A variable of type __Tcl\_Interp\*__ which is the interpreter the code is running in\. * __@@__ A placeholder for an expression that evaluates to the __Tcl\_Obj\*__ to convert\. * __@A__ A placeholder for the name of the variable to store the converted argument into\. As examples, here are the definitions of two standard argument types: argtype int { if (Tcl_GetIntFromObj(interp, @@, &@A) != TCL_OK) return TCL_ERROR; } argtype float { double t; if (Tcl_GetDoubleFromObj(interp, @@, &t) != TCL_OK) return TCL_ERROR; @A = (float) t; } - __::critcl::argtype__ *name* __=__ *origname* This form of the __argtype__ command declares *name* as an alias of argument type *origname*, which has to be defined already\. If this is not the case an error is thrown\. - __::critcl::argtypesupport__ *name* *code* ?*guard*? This command defines a C code fragment for the already defined argument type *name* which is inserted before all functions using that type\. Its purpose is the definition of any supporting C types needed by the argument type\. If the type is used by many functions the system ensures that only the first of the multiple insertions of the code fragment is active, and the others disabled\. The guard identifier is normally derived from *name*, but can also be set explicitly, via *guard*\. This latter allows different custom types to share a common support structure without having to perform their own guarding\. - __::critcl::argtyperelease__ *name* *code* This command defines a C code fragment for the already defined argument type *name* which is inserted whenever the worker function of a __critcl::cproc__ returns to the shim\. It is the responsibility of this fragment to unconditionally release any resources the __critcl::argtype__ conversion code allocated\. An example of this are the *variadic* types for the support of the special, variadic *args* argument to __critcl::cproc__'s\. They allocate a C array for the collected arguments which has to be released when the worker returns\. This command defines the C code for doing that\. # Examples The examples shown here have been drawn from the section "Embedding C" in the document about *Using CriTcl*\. Please see that document for many more examples\. ## A Simple Procedure Starting simple, let us assume that the Tcl code in question is something like proc math {x y z} { return [expr {(sin($x)*rand())/$y**log($z)}] } with the expression pretending to be something very complex and slow\. Converting this to C we get: critcl::cproc math {double x double y double z} double { double up = rand () * sin (x); double down = pow(y, log (z)); return up/down; } Notable about this translation: 1. All the arguments got type information added to them, here "double"\. Like in C the type precedes the argument name\. Other than that it is pretty much a Tcl dictionary, with keys and values swapped\. 1. We now also have to declare the type of the result, here "double", again\. 1. The reference manpage lists all the legal C types supported as arguments and results\. While the above example was based on type __double__ for both arguments and result we have a number of additional types in the same category, i\.e\. simple types\. These are: > CriTcl type | C type | Tcl type | Notes > \-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > bool | | | Alias of __boolean__ below > boolean | int | Boolean | > double | double | Double | > float | float | Double | > int | int | Int | > long | long | Long | > wideint | Tcl\_WideInt | WideInt | A slightly advanced form of these simple types are a limited set of constraints on the argument value\. Note that __bool__ and alias do not support this\. critcl::cproc sqrt {{double >= 0} x} double { return sqrt(x); } In the example above CriTcl's argument handling will reject calling the command with a negative number, without ever invoking the C code\. These constraints are called *limited* because only __0__ and __1__ can be used as the borders, although all the operators __<__, __<=__, __>__, and __>=__ are possible\. It is also not possible to combine restrictions\. ## More Builtin Types: Strings Given that "Everything is a String" is a slogan of Tcl the ability of __cproc__s to receive strings as arguments, and return them as results is quite important\. We actually have a variety of builtin string types, all alike, yet different\. For arguments we have: > CriTcl type | C type | Tcl type | Notes > \-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > char\* | const char\* | Any | *Read\-only*, *string rep* > pstring | critcl\_pstring | Any | *Read\-only* > bytes | critcl\_bytes | ByteArray | *Read\-only* In C critcl::cproc takeStrings { char* cstring pstring pstring bytes barray } void { printf ("len %d = %s\n", strlen(cstring), cstring); printf ("len %d = %s\n", pstring.len, pstring.s); printf ("len %d = %s\n", barray.len, barray.s); return; // void result, no result } Notable about the above: 1. The __cstring__ is a plain __const char\*__\. It *points directly* into the __Tcl\_Obj\*__ holding the argument in the script\. 1. The __pstring__ is a slight extension to that\. The value is actually a structure containing the string pointer like __cstring__ $field __\.s__$, the length of the string $field __\.len__$, and a pointer to the __Tcl\_Obj\*__ these came from\. 1. The last, __barray__ is like __pstring__, however it has ensured that the __Tcl\_Obj\*__ is a Tcl ByteArray, i\.e\. binary data\. Treat all of them as *Read Only*\. Do not modify ever\. On the other side, string results, we have: > CriTcl type | C type | Tcl type | Notes > \-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > char\* | char\* | String | *Makes a copy* > vstring | | | Alias of __char\*__ above > const char\* | const char\* | | Behavior of __char\*__ above > \-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\- | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- > string | char\* | String | Freeable string set directly > | | | *No copy is made* > dstring | | | Alias of __string__ above critcl::cproc returnCString {} char* { return "a string"; } critcl::cproc returnString {} string { char* str = Tcl_Alloc (200); sprintf (str, "hello world"); return str; } Notable about the above: 1. The type __char\*__ is best used for static strings, or strings in some kind fixed buffer\. CriTcl's translation layer makes a copy of it for the result of the command\. While it is possible to return heap\-allocated strings it is the C code who is responsible for freeing such at some point\. If that is not done they will leak\. 1. The type __string__ on the other hand is exactly for returning strings allocated with __Tcl\_Alloc__ and associates\. For these the translation layer makes no copy at all, and sets them directly as the result of the command\. A *very important effect* of this is that the ownership of the string pointer moves from the function to Tcl\. *Tcl* will release the allocated memory when it does not need it any longer\. The C code has no say in that\. ## Custom Types, Introduction When writing bindings to external libraries __critcl::cproc__ is usually the most convenient way of writing the lower layers\. This is however hampered by the fact that critcl on its own only supports a few standard $arguably the most import$ standard types, whereas the functions we wish to bind most certainly will use much more, specific to the library's function\. The critcl commands __argtype__, __resulttype__ and their adjuncts are provided to help here, by allowing a developer to extend critcl's type system with custom conversions\. This and the three following sections will demonstrate this, from trivial to complex\. The most trivial use is to create types which are aliases of existing types, standard or other\. As an alias it simply copies and uses the conversion code from the referenced types\. Our example is pulled from an incomplete project of mine, a binding to *Jeffrey Kegler*'s *libmarpa* library managing Earley parsers\. Several custom types simply reflect the typedef's done by the library, to make the __critcl::cproc__s as self\-documenting as the underlying library functions themselves\. critcl::argtype Marpa_Symbol_ID = int critcl::argtype Marpa_Rule_ID = int critcl::argtype Marpa_Rule_Int = int critcl::argtype Marpa_Rank = int critcl::argtype Marpa_Earleme = int critcl::argtype Marpa_Earley_Set_ID = int ... method sym-rank: proc { Marpa_Symbol_ID sym Marpa_Rank rank } Marpa_Rank { return marpa_g_symbol_rank_set (instance->grammar, sym, rank); } ... ## Custom Types, Semi\-trivial A more involved custom argument type would be to map from Tcl strings to some internal representation, like an integer code\. The first example is taken from the __tclyaml__ package, a binding to the __libyaml__ library\. In a few places we have to map readable names for block styles, scalar styles, etc\. to the internal enumeration\. critcl::argtype yaml_sequence_style_t { if (!encode_sequence_style (interp, @@, &@A)) return TCL_ERROR; } ... critcl::ccode { static const char* ty_block_style_names [] = { "any", "block", "flow", NULL }; static int encode_sequence_style (Tcl_Interp* interp, Tcl_Obj* style, yaml_sequence_style_t* estyle) { int value; if (Tcl_GetIndexFromObj (interp, style, ty_block_style_names, "sequence style", 0, &value) != TCL_OK) { return 0; } *estyle = value; return 1; } } ... method sequence_start proc { pstring anchor pstring tag int implicit yaml_sequence_style_t style } ok { /* Syntax: seq_start