[comment {-*- mode: tcl ; fill-column: 90 -*-}]
[comment {
    Standard argument types for use with cproc and cclass methods.
}]


Before going into the details first a quick overview:

[include atypes_table.inc]

And now the details:

[list_begin definitions]
[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]

[def Tcl_Interp*]

[strong Attention]: This is a [strong special] argument type. It can
[strong only] be used by the [strong first] argument of a function.
Any other argument using it will cause critcl to throw an error.

[para] When used, the argument will contain a reference to the current
interpreter that the function body may use. Furthermore the argument
will [strong not] be an argument of the Tcl command for the function.

[para] 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.

[def Tcl_Obj*]
[def object]

The function takes an argument of type [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 [strong read-only] (except for
hidden changes to its intrep, i.e. [term shimmering]).

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def pstring]

The function takes an argument of type [type critcl_pstring]
containing the original [type Tcl_Obj*] reference of the Tcl argument,
plus the length of the string and a pointer to the character array.

[example {
typedef struct critcl_pstring {
    Tcl_Obj*    o;
    const char* s;
    int         len;
} critcl_pstring;
}]

Note the [strong const]. The string is [strong 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.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def list]
[def {[]}]
[def {[*]}]

The function takes an argument of type [type critcl_list] containing the original [type Tcl_Obj*]
reference of the Tcl argument, plus the length of the Tcl list and a pointer to the array of the
list elements.

[example {
typedef struct critcl_list {
    Tcl_Obj*        o;
    Tcl_Obj* const* v;
    int             c;
} critcl_list;
}]

The Tcl argument must be convertible to [type List], an error is thrown otherwise.

[para] Note the [strong const]. The list is [strong 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.

[para] 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.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def {[N]}]

A [term list] type with additional checks limiting the length to [const N], an integer
number greater than zero.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def {[]type}]
[def {type[]}]

A [term list] type whose elements all have to be convertible for [term type]. All known
types, including user-defined, are allowed, except for [type list] and derivates. In other
words, multi-dimensional lists are not supported.

[para] The function will take a structure argument of the general form

[example {
typedef struct critcl_list_... {
    Tcl_Obj* o;
    int      c;
    (Ctype)* v;
} critcl_list_...;
}]

where [const (Ctype)] represents the C type for values of type [type type].

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def {[N]type}]
[def {type[N]}]

These are [type list] types combining the elements of [example {[N]}] and
[example {[]type}].

[para] As an example, the specification of [example {int[3] a}] describes argument [arg a]
as a list of exactly 3 elements, all of which have to be of type [type int].

[para] Note that this example can also be written in the more C-like form of
[example {int a[3]}]. The system will translate this internally to the first shown form.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def bytes]

This is the [emph new] and usable [type ByteArray] type.

[para] The function takes an argument of type [type critcl_bytes]
containing the original [type Tcl_Obj*] reference of the Tcl argument,
plus the length of the byte array and a pointer to the byte data.

[example {
typedef struct critcl_bytes {
    Tcl_Obj*             o;
    const unsigned char* s;
    int                len;
} critcl_list;
}]

The Tcl argument must be convertible to [type ByteArray], an error is
thrown otherwise.

[para] Note the [strong const]. The bytes are [strong 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.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def char*]

The function takes an argument of type [type {const char*}].
The string representation of the Tcl argument is passed in.

[para] Note the [strong const]. The string is [strong 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.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def double]

The function takes an argument of type [type double].

The Tcl argument must be convertible to [type Double], an error is thrown otherwise.

[def {double > N}]
[def {double >= N}]
[def {double < N}]
[def {double <= N}]

These are variants of [term double] above, restricting the argument value to the shown relation.

An error is thrown for Tcl arguments outside of the specified range.

[para] The limiter [arg N] has to be a constant floating point value.

[para] It is possible to use multiple limiters.

For example [term {double > A > B <= C}].

The system will fuse them to a single upper/lower limit (or both).

[para] The system will reject limits describing an empty range of values, or a range containing only
a single value.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def float]

The function takes an argument of type [type float].

The Tcl argument must be convertible to [type Double], an error is thrown otherwise.

[def {float > N}]
[def {float >= N}]
[def {float < N}]
[def {float <= N}]

These are variants of [term float] above, restricting the argument value to the shown relation.

An error is thrown for Tcl arguments outside of the specified range.

[para] The limiter [arg N] has to be a constant floating point value.

[para] It is possible to use multiple limiters.

For example [term {float > A > B <= C}].

The system will fuse them to a single upper/lower limit (or both).

[para] The system will reject limits describing an empty range of values, or a range containing only
a single value.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def boolean]
[def bool]

The function takes an argument of type [type int].

The Tcl argument must be convertible to [type Boolean], an error is
thrown otherwise.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def channel]

The function takes an argument of type [type Tcl_Channel].

The Tcl argument must be convertible to type [type Channel], an error
is thrown otherwise.

The channel is further assumed to be [strong {already registered}]
with the interpreter.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def unshared-channel]

This type is an extension of [type channel] above.

All of the information above applies.

[para] Beyond that the channel must not be shared by multiple
interpreters, an error is thrown otherwise.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def take-channel]

This type is an extension of [type unshared-channel] above.

All of the information above applies.

[para] Beyond that the code removes the channel from the current
interpreter without closing it, and disables all pre-existing event
handling for it.

[para] 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.

[para] 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 [type return-channel]. This will undo the registration
changes made by this argument type.

[strong Note] however that the removal of pre-existing event handling
done here cannot be undone.

[para] [strong 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.

[para] 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.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def int]

The function takes an argument of type [type int].

The Tcl argument must be convertible to [type Int], an error is thrown otherwise.

[def {int > N}]
[def {int >= N}]
[def {int < N}]
[def {int <= N}]

These are variants of [term int] above, restricting the argument value to the shown
relation.

An error is thrown for Tcl arguments outside of the specified range.

[para] The limiter [arg N] has to be a constant integer value.

[para] It is possible to use multiple limiters.

For example [term {int > A > B <= C}].

The system will fuse them to a single upper/lower limit (or both).

[para] The system will reject limits describing an empty range of values, or a range
containing only a single value.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def long]

The function takes an argument of type [type {long int}].

The Tcl argument must be convertible to [type Long], an error is thrown otherwise.

[def {long > N}]
[def {long >= N}]
[def {long < N}]
[def {long <= N}]

These are variants of [term long] above, restricting the argument value to the shown
relation.

An error is thrown for Tcl arguments outside of the specified range.

[para] The limiter [arg N] has to be a constant integer value.

[para] It is possible to use multiple limiters.

For example [term {long > A > B <= C}].

The system will fuse them to a single upper/lower limit (or both).

[para] The system will reject limits describing an empty range of values, or a range
containing only a single value.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def wideint]

The function takes an argument of type [type Tcl_WideInt].

The Tcl argument must be convertible to [type WideInt], an error is thrown otherwise.

[def {wideint > N}]
[def {wideint >= N}]
[def {wideint < N}]
[def {wideint <= N}]

These are variants of [term wideint] above, restricting the argument value to the shown
relation.

An error is thrown for Tcl arguments outside of the specified range.

[para] The limiter [arg N] has to be a constant integer value.

[para] It is possible to use multiple limiters.

For example [term {wideint > A > B <= C}].

The system will fuse them to a single upper/lower limit (or both).

[para] The system will reject limits describing an empty range of values, or a range
containing only a single value.

[comment {% % %% %%% %%%%% %%%%%%%% %%%%%%%%%%%%%}]
[def void*]

[list_end]