# 6 Writing C-tela files

Contents of this section

C-tela files are C++ code equipped with Tela's function header syntax. There is a preprocessor, ctpp, that translates C-tela in ordinary C++. Calling ctpp is the responsibility of the tool program telakka ( telakka ).

Let us begin with an example of a C-tela source file (let it be mine.ct):

> `

>     // Our first C-tela example

>     [] = myfn(x)
>     /* myfn(x) checks that x is a positive scalar and outputs it.
>        Error codes:
>        1: x is not a positive scalar */
>     {
>         if (!x.IsScalar()) return 1;
>         switch (x.kind()) {
>             case Kint:
>                 if (x.IntValue() <= 0) return 1;
>                 break;
>             case Kreal:
>                 if (x.RealValue() <= 0) return 1;
>                 break;
>             case Kcomplex:
>                 return 1;
>             default:
>                 return 1;
>         }
>         cout << "myfn: x = " << x << '\n';
>         return 0;
>     }

> `

You can compile it using telakka ( telakka telakka ):

> `

>     unix> telakka -c mine.ct

> `

Then from Tela you can link the object file and test myfn as follows.

> `

>     >link("mine.o")
>     >help myfn
>     myfn(x) checks that x is a positive scalar and outputs it.
>     >myfn(2)
>     myfn: x = 2
>     >myfn(-2)
>     Warning from C-function 'myfn':
>       x is not a positive scalar.
>     >myfn(2+3.4i)
>     Warning from C-function 'myfn':
>       x is not a positive scalar.
>     >myfn(#(1.2,3,4))
>     Warning from C-function 'myfn':
>       x is not a positive scalar.

> `

There are several points to be noticed with this simple example:

    - The function is declare using the [...] = f(...) type syntax.
    - The /* ... */ comment immediately following the header is "hot".
      The Tela help command finds and displays the comment, up to line
      "Error codes:".
    - The function should return zero on success, positive integer on
      nonfatal error and negative integer on fatal error. The error codes
      should be listed in the comment, following, one per line, the
      "Error codes:" line.
    - All C++ constructs are available, in addition several classes and
      their associated members from Tela headers. The function arguments
      ("x" in our case) are of type Tobject and they can be e.g. outputted
      using cout << x.

Rules for argument syntax are very similar to those found in Tela. Output arguments are enclosed in square brackets and input arguments in parentheses. Optional arguments are separated from obligatory arguments with a semicolon, parameters to the right of the semicolon are optional and parameters on the left hand side of the semicolon are obligatory. If there is no semicolon in the output argument list, then all output arguments are optional. If there is no semicolon in the input argument list, then all input arguments are obligatory. In addition, it is possible to use the ellipsis (...) notation to denote an arbitrary number of optional arguments. The ellipsis is only allowed as the last thing in a parameter (either input or output) list. The following function has two obligatory output arguments, one optional output argument, two obligatory input arguments, and any number of optional input arguments, the first of which is named c:

> `

>     [x,y; z] = f(a,b; c...)

> `

The function body can refer to the arguments simply by name, and they are of class Tobject. Actually the argument lists are implemented using four C++ function parameters: the input argument list (argin), the length of the input argument list (Nargin), the output argument list (argout), and the length of the output argument list (Nargout). Nargin and Nargout are of type int. argin and argout are arrays of pointers to Tobject. The named arguments are just C preprocessor macros. For example, if x is the first input argument, its definition is

> `

>     #define x (*(argin[0]))

> `

The pointers contained in the argument arrays are protected against modification by the C++ keyword const. In addition the input array individual objects are also const. The C++ compiler will therefore give an error message if you try to assign or otherwise modify an input argument. Also Nargin and Nargout carry the const attribute, because changing them is unnecessary.

Ellipsis arguments have no names and therefore must be referenced using the argin and argout arrays explicitly. This is easy, for example to process all input arguments starting from the second one (which is *argin<F>1</F>, remember that in C arrays start with subscript 0), you could use a code like this:

> `

>     static void Process(const Tobject& obj) { /* ... */ }

>     [] = myfunc(x...)
>     /* Help message ... */
>     {
>         /* ... */
>         for (int i=1; i<Nargin; i++)
>             Process(*argin[i]);
>         /* ... */
>     }

> `

As mentioned earlier, C-tela code is C++ code equipped with the Tela-like function header syntax. In addition to this, there are also some small restrictions on C-tela source files:

> `

>     1. The function header must be on one line, and the first character
>     (the left square bracket) must be on first column.

>     2. The right brace which ends the C-tela function body must be in the
>     first column. No other right brace inside the function body may be in
>     first column.

>     3. You cannot temporarily remove C-tela functions from your source
>     file using preprocessor directies, e.g. by enclosing the lines in
>     #if 0 ... #endif. If you want to do this, you must also enclose the
>     function headers in a comment.

> `

These rules should not limit your programming capabilities in any serious way, and most of the time you do not have to even think about them.

Then what can you do with the Tela objects, that are of type Tobject in C++? Firstly, every Tobject has a tag containing that object's kind. The possible kinds are (from header file object.H):

> `

>     enum Tkind {                // Object kinds (types)
>         Kint,                   // Integer scalar
>         Kreal,                  // Real scalar
>         Kcomplex,               // Complex scalar
>         KIntArray,              // Integer array (n-dimensional)
>         KRealArray,             // Real array
>         KComplexArray,          // Complex array
>         KObjectArray,           // Object (pointer) array, currently not used
>         Kfunction,              // User-defined function, written in Tela
>         KCfunction,             // Compiled and linked C-Tela function
>         KIntrinsicFunction,     // Special "functions" generating inline code: abs, min, max ..
>         Kvoid,                  // Empty value, when printed prints nothing
>         Kundef                  // Undefined value, the default for new symbols
>     };

> `

Let us then list the most useful Tobject public members:

> `

>     class Tobject {
>       /* ... */
>         // --- constructors
>         Tobject();                          // default constructor: it will have Undefined value
>         Tobject(Tint a);                    // construct integer scalar object
>         Tobject(Tchar ch);                  // construct character object
>         Tobject(Treal a);                   // construct real scalar object
>         Tobject(Tcomplex a);                // construct complex scalar object
>         Tobject(Treal x, Treal y);          // construct complex scalar object
>         Tobject(const Tint itab[], int N, int stringflag=0);    // construct integer vector or string
>         Tobject(const Treal xtab[], int N); // construct real vector
>         Tobject(const Tcomplex ztab[], int N);  // construct complex vector
>         Tobject(const Tint itab[], const TDimPack& dp); // construct integer array
>         Tobject(const Treal xtab[], const TDimPack& dp);    // construct real array
>         Tobject(const Tcomplex ztab[], const TDimPack& dp); // construct complex array
>         Tobject(const Tchar *str);          // construct string
>         Tobject(const Tobject& obj);        // copy constructor: use other object's value

>         // --- assignments
>         Tobject& operator=(Tint a);         // assign integer scalar
>         Tobject& operator=(Treal a);        // assign real scalar
>         Tobject& operator=(const Tcomplex& a);  // assign complex scalar
>         Tobject& operator=(Tchar ch);       // assign character
>         Tobject& operator=(const Tchar *str);   // assign string
>         Tobject& operator=(const Tobject& obj); // copy assignment: assign other object's value
>         void izeros(const TDimPack& dp);    // set to zeroed int array of given dims
>         void rzeros(const TDimPack& dp);    // set to zeroed real array of given dims
>         void czeros(const TDimPack& dp);    // set to zeroed complex array of given dims
>         void ireserv(const TDimPack& dp);   // set to uninitialized int array of given dims
>         void rreserv(const TDimPack& dp);   // set to uninitialized real array of given dims
>         void creserv(const TDimPack& dp);   // set to uninitialized complex array of given dims
>         void SetToVoid();                   // set to void (empty) value
>         void SetToUndefined();              // set to undefined value
>         void SetStringFlag();               // set string flag (assuming it is IntArray already)
>         void SetCharFlag();                 // (assume it is Kint already)
>         void ClearStringFlag();             // unset string flag (assuming it is IntArray already)
>         void ClearCharFlag();               // (assume it is Kint already)

>         // --- comparison
>         int operator==(const Tobject& obj) const;
>         int operator!=(const Tobject& obj) const;

>         // --- inquiry functions
>         Tkind kind() const;                 // inquire object kind
>         int length() const;                 // number of elements of array object
>         Tint rank() const;                  // rank of array object
>         Tint IntValue() const;              // value of integer scalar object
>         Treal RealValue() const;            // value of real scalar object
>         const Tcomplex& ComplexValue() const;   // value of complex scalar object
>         Tint& IntRef();                     // modifiable lvalue of integer scalar object
>         Treal& RealRef();                   // modifiable lvalue of real scalar object
>         Tcomplex& ComplexRef();             // modifiable lvalue of complex scalar object
>         Tint *IntPtr() const;               // start address of elements of integer array
>         Treal *RealPtr() const;             // start address of elements of real array
>         Tcomplex *ComplexPtr() const;       // start address of elements of complex array
>         int IsNumerical() const;            // nonzero if object is numerical (scalar or array)
>         int IsArray() const;                // nonzero if object is array
>         int IsNumericalArray() const;       // nonzero if it is numerical array
>         int IsScalar() const;               // nonzero if object is (numerical) scalar
>         int IsFunction() const;             // nonzero if object is Tela-function
>         int IsCfunction() const;            // nonzero if object is C-tela function
>         int IsString() const;               // nonzero if object is string
>         int IsChar() const;                 // nonzero if object is character
>         int IsNonzero() const;              // tests whether object is not zero
>         const TDimPack& dims() const;       // return array object's dimensions

>         // --- other operations
>         friend ostream& operator<<(ostream& o, const Tobject& obj);     // outputter

>         // --- destructor
>         ~Tobject();
>     };

> `

Using all these members seems to be overwhelming task at first. But there is certain logic behind this design. Basically, you can

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter