matwrap -- Wrap C++ functions/classes for various matrix languages

matwrap is a script to generate wrapper functions for matrix-oriented scripting languages so that subroutines or member functions can be called. It doesn't support non-matrix-oriented scripting languages like perl and python and tcl because Dave Bezley's program SWIG is such a good wrapper generator for those languages. Someday I hope that all of the features in this wrapper generator are incorporated into SWIG, but since I don't understand SWIG well enough to do it myself, I'm releasing this separately. SWIG is available from http://bifrost.lanl.gov/~dmb/SWIG/ or http://www.cs.utah.edu/~beazley/SWIG/.

matwrap can handle the following constructs:

Ordinary functions

For example, suppose you have some functions defined in an CW.h file, like this:

    float fiddle(double arg);
    double tweedle(int x, char *name);

You can access these directly from MATLAB by using the following:

  matwrap -language matlab -o myfuncs_wrap.c fiddle.h
  cmex myfuncs.o myfuncs_wrap.c -o myfuncs_wrap

Then, in MATLAB, you can do the following:

  y = tweedle(3, 'Hello, world');
  A = fiddle([3, 4; 5, 6];

Note especially the last statement, where instead of passing a scalar as the argument, we pass a matrix. The C function fiddle() is called repeatedly on each element of the matrix and the result is returned as a 2x2 matrix. Floats, doubles, char *, integer, unsigned, and pointers to structures may be used as arugments. Support for other data types (e.g., various classes) is possible and may be easily added since the modules have been written for easy extensibility. Function pointers are not currently supported in any form. operator definitions are not supported either.

classes

You can access public member functions and simple public data members of classes. For example,

  class ABC {
  public:
    ABC(int constructor_arg);
    void do_something(float number, int idx);
    double x;
  };

From MATLAB or a similar language, you would access this structure like this:

  ABC_ptr = ABC_new(3);         % Call the constructor and return a pointer.
  ABC_do_something(ABC_ptr, pi, 4); % Call the member function.
  abc_x = ABC_get_x(ABC_ptr);   % Get the value of a data member.
  ABC_set_x(ABC_ptr, 3.4);      % Set the data member.
  ABC_delete(ABC_ptr);          % Discard the structure.

Accessing data members is often extremely useful when you are attempting to figure out why your code returns 27.3421 when it ought to return 4.367. The same thing will work for C structsthe only difference is that they have only data members and no member functions. Only public members are accessible from the scripting language. Operator overloading and function overloading are not supported. Function pointers are not supported.

Arrays

You can also call functions that take arrays of data, provided that they accept the arrays in a standard format. For example, suppose you want to use the pgplot distribution to make graphs (e.g., if you're using a scripting language that doesn't have good graphing capability). The following function generates a histogram of data:

  void cpgbin(int nbin, const float *x, const float *data, Logical center);

Here x[] are the abscissae values and data[] are the data values. If you add to your .h file a simple statement indicating the dimensions of the matrices, like this:

  //%input x(n), data(n)

then from a MATLAB-like language, you can call this function like this:

  cpgbin(X, Data, 1)

where CWX and CWData are vectors. The CWnbin argument is determined from the length of the CWX and CWData vectors automatically (and the wrapper generator makes sure they are of the same length!). This will also work with multidimensional arrays, provided that the function expects the array to be a single one-dimensional array which is really the concatenation of the columns of the two-dimensional array. (This is normal for Fortran programs.) The first array dimension varies the fastest, the second the next fastest, etc. (This is column major order, as in Fortran, not row-major order, as in C. Most matlab-like languages use the Fortran convention. Tela is an exception.) You may only use variable name or a constant for the array dimension. You can also use expressions like CW2*nbin or CW2*nbin+1. If the expression is sufficiently simple, the wrapper generator will determine the values of any integer values (like CWnbin in this example) from the dimension of the input arrays, so they do not have to be specified as an argument.

A compiler

In theory, this could be made to work with an ANSI C compiler, but I haven't tried to yet. Currently, you must have a full compiler. I've used primarily gcc and I tested very briefly with DEC's cxx. If you are using matlab, then you can tell matwrap to use CWmxCalloc instead of CWalloca by specifying CW-use_mxCalloc somewhere on the command line. Otherwise, you must have a compiler that supports CWalloca(). (gcc does.) CWalloca() is usually a little more efficient than CWmxCalloc(). It allocates space on the stack rather than the heap. Unfortunately, you may have a limited stack size, and so CWalloca() may fail for large temporary arrays. In this case, you may need to issue a command like

   unix('unlimit stacksize')

or else use the CW-use_mxCalloc option.

A relatively recent version of perl

I've tested this only with perl 5.004 and 5.005. Check out http://www.perl.com/ for how to get perl.

  matwrap -language languagename [-options] infile1.h infile2.h

  matwrap -language languagename [-options] \
    -cpp cxx [-options_to_C_compiler] infile.cxx

Using the first form, without the CW-cpp flag, files are parsed in the order listed, so you should put any files with required typedefs and other definitions first. These files are CW#included by the generated wrapper code; in fact, they are the only files which are CW#included. This form can be used 1) if you don't have any CW#ifs or macros that confuse the parser in your code; 2) if you can easily list all of the include files that define the relevant structures.

Alternatively, you can use the CW-cpp flag to have matwrap run the C preprocessor on your files. This means that all of the relevent definitions of types will be found, however deeply they are nested in the CW#include hierarchy. It also means that wrapper generation runs considerably slower. Matwrap will attempt to guess which files need to be CW#included, but it may guess wrong.

Overloaded functions and definitions of operators are not supported. classes are supported (this is the main reason for this script). Member functions may be called, and member fields may be accessed.

-cpp

Run the C preprocessor on your file before parsing it. This is necessary if you are using any #ifdefs in your code. Following the -cpp option should be a complete compiler command, e.g.,

  matwrap -language octave -o myfile_wrap.cxx \
        -cpp g++ -Iextra_includes -Dmy_thingy=3 myfile.cxx

All words after the -cpp option are ignored (and passed verbatim to the compiler), so you must supply a CW-o option before the CW-cpp. Note that CW-o and similar compiler options relevant for actual compilation are ignored when just running the preprocessor, so you can substitute your actual compilation command without modification. If you do not supply the CW-E flag in the compiler command, it will be inserted for you immediately after the name of the compiler. Also, the CW-C option is added along with the CW-E option so that any comments can be processed and put into the documentation strings. (As far as I know all compilers support CW-C and CW-E but undoubtably this won't work well with some. It works fine with gcc.) When run in this way, CWmatwrap does not generate wrappers for any functions or classes defined in files located in CW/usr/include or CW/usr/local/include or in subdirectories of CW*/gcc-lib. (Most likely you don't want to wrap the entire C library!) You can specify additional directories to ignore with the -cpp_ignore option. If you really want to wrap functions in one of those CW.h files, either copy CW.h file or just the relevant function definitions into a file in another directory tree. You can also restrict the functions which are wrapped using the -wrap_only option (see below).

-cpp_ignore filename_or_directory

Ignored unless used with the -cpp option. Causes functions defined in the given file name or in include files in the given directory or subdirectories of it not to be wrapped. By default, functions defined in CW/usr/include, CW/usr/local/include, or CW*/gcc-lib are not wrapped. Specify the name of the output file. If this is not specified, the name is inferred from the input files. Some language modules (e.g., MATLAB) will not infer a file name from your source files (this is for your protection, so we don't accidentally wipe out a CW.c file with the same name). If you use the CW-cpp option, you must also specify the CW-o option before the CW-cpp option.

-language <language_name>

Specify the language. This option is mandatory.

-wraponly <list>

Specify a list of global functions or variables or classes to wrap. The list extends to the end of the command line, so this must be the last option. Definitions of all functions and classes not explictly listed are ignored. This allows you to specify all the CW.h files that you need to define all the types, but only to wrap some of the functions. Global functions and variables are specified simply by name. Classes are specified by the word 'class' followed by the class name. For example,

  matwrap -language matlab myfile.h \
         -wraponly myglobalfunc class myclass

Input files are designed to be your ordinary .h files, so your wrapper and your sources are never out of date. In general, the wrapper generator does the obvious thing with each different kind of type. For example, consider the function declaration:

  double abcize(float a, int b, char *c, SomeClass *d);

This will pass a single-precision floating point number as argument CWa (probably converting from double precision or integer, depending on what the interpreted language stored the value as). An integer is passed as argument CWb (probably converted from a double precision value). A null-terminated string is passed as argument CWc (converted from whatever weird format the language uses). The argument CWd must be a pointer value which was returned by another function.

Vectorization is automatically performed, so that if you pass a matrix of CWm by CWn inputs as argument CWa and arguments CWb and CWc as either scalars or CWm by CWn matrices, then the function will be called CWm*n times and the result will be an CWm by CWn matrix. By default, a function is vectorized if it has both inputs and outputs (see under CW//%vectorize below). Most matrix languages do not support vectors of strings in a natural way, so CWchar * arguments are not vectorized.

Passing arguments by reference is handled in the expected way. For example, given the declaration

  void fortran_sub(double *inarg1, float *inarg2);

pointers to double and single precision numbers will be passed to the subroutine instead of the numbers themselves.

This creates an ambiguity for the type CWchar *. For example, consider the following two functions:

        void f1(char *a);
        void f2(unsigned char *b);

Matwrap assumes that the function CWf1 is passed a null terminated string, despite the fact that the argument CWa could be a pointer to a buffer where CWf1 returns a character. Although this situation can be disambiguated with proper use of the CWconst qualifier, matwrap treats CWchar * and CWconst char * as identical since many programs don't use CWconst properly. Matwrap assumes, however, that CWunsigned char * is not a null terminated string but an CWunsigned char variable passed by reference. You can also force it to interpret CWchar * as a signed char passed by reference by specifying the qualifier CW//%input a(1) (see below).

If you want to pass arguments as arrays, or if there are outputs other than the return value of the function, you must declare these explicitly using the CW//%input or CW//%output qualifiers. All qualifiers follow the definition of the function (after the CW; or the closing CW} if it is an inline function). Valid qualifiers are:

//%novectorize_type type1, type2, ...

Specifies that all arguments of the given types should not be vectorized even if it is possible. This could be useful if you have a class which there will be only one copy of, so it is pointless to vectorize. (This qualifier may be present anywhere in the file.)

//%novectorize

Following the definition of a global function or member function, directs matwrap not to try to vectorize the function. For some functions, vectorization simply doesn't make sense. By default, matwrap won't vectorize a function if it has no output arguments or no input arguments.

//%vectorize

Following the definition of a global function or member function, directs matwrap to vectorize the function. By default, matwrap won't vectorize a function if it has no output arguments or no input arguments. This is normally what you want, but but sometimes it makes sense to vectorize a function with no output arguments.

//%nowrap

Don't wrap this function. It will therefore not be callable directly from your scripting language.

//%name new_name

Specify a different name for the function when it is invoked from the scripting language.

//%input argname(dim1, dim2, ...), argname(dim)

Following the declaration of a global function or member function, declares the dimensions of the input arguments with the given name. This declaration must immediately follow the prototype of the function. Dimension strings may contain any arbitrary C expression. If the expression is sufficiently simple, e.g., n or n+1 or 2*n, and if the expression includes another argument to the function (n in this case), then the other argument will be calculated from the dimensions of the input variable and need not be specified as an argument in the scripting language. For example, if you have a function which is declared like this:

        void myfunc(int n, double *x, double *y);
                        //%input x(3*n+4)
                        //%output y(n*(n+1)/2)

n would be calculated from the dimension of the variable x and then used to compute the size of the output array. So you would call the function like this:

        y = myfunc(x)

On the other hand, if you had a specification like this:

        void return_diag(int n, double *x, double *y);
                        //%input x(n*(n+1)/2)
                        //%output y(n)

then n will have to be explicitly specified because it is too difficult to calculate:

        y = myfunc(n, x)

//%modify argname(dim1, dim2, ...), argname(dim1)

//%output argname(dim1, dim2, ...), argname(dim1)

Same as CW//%input except that this also tags the variables as modify or output variables. If you don't specify a dimension expression (e.g., //%output x) then the variable is tagged as a scalar output variable. (This is the proper way to tell matwrap to make an argument an output argument.)

Function overloading

Operator definition

Function and member function pointers

It would be really nice to support these, but I think it's also really hard. Maybe someday.

Two-dimensional arrays using a vector of pointers

You can use two-dimensional arrays as long as they are stored internally as a single long vector, as in Fortran. In this case, the array declaration would be CWfloat *x, and the CWi,j'th element is accessed by CWx[j*n+i]. You cannot use two dimensional arrays if they are declared like CWfloat **x and accessed like CWx[i][j]. Unfortunately, the Numerical Recipes library uses this format for all its two-dimensional matrices, so at present you can only wrap Numerical Recipes functions which take scalars or vectors. This restriction might be lifted in the future.

Arrays with an offset

The Numerical Recipes code is written so that most of its indices begin at 1 rather than at 0, I guess because its authors are Fortran junkies. This causes a problem, because it means that the pointer you pass to the subroutine is actually not the beginning of the array but before the beginning. You can get around this restriction by passing an extra blank element in your array. For example, suppose you want to wrap the function to return the Savitzky-Golay filter coefficients:

  void savgol(float c[], int np, int nl, int nr, int ld, int m);

where the index in the array CWc is declared to run from 1 to np. You'd have to declare the array like this:

                                //%output c(np+1)

and then ignore the first element. Thus from MATLAB you'd call it with the following sequence:

        savgol_coefs = savgol(np, nl, nr, ld, m);
        savgol_coefs = savgol_coefs(2:length(savgol_coefs));
                                % Discard the unused first element.

Passing structures by value or reference

In other words, if Abc is the name of a class, declarations like

        void myfunc(Abc x);

or

        void myfunc(Abc &x);

won't work. However, you can pass a pointer to the class:

        void myfunc(Abc *x);

The wrapper generator will do the type checking and it even handles inheritance properly.

For more examples, see the subdirectories of share/matwrap/Examples in the distribution. This includes a wrapper for the entire PGPLOT library (directory pgplot) and a sample simulator for an neuron governed by the Hodgkin-Huxley equations (directory single_axon).

Currently, you must compile the generated wrapper code using , even if you are wrapping only C functions with no classes. You can compile your C functions using C as you please; you may have to put a CWextern "C" { } statement in the .h file. This restriction may be lifted in the future.

The default maximum number of dimensions supported is four. You can change this by modifying the CW$max_dimensions variable near the top of the file share/matwrap/wrap_matlab.pl in the distribution.

Specify CW-langauge matlab on the command line to use the matlab code generator. You MUST also use CW-o to specify the output file name. (This is because matlab wrappers have an extension of CW.c and if we infer the file name from the name of include files, it's quite likely that we'll wipe out something that shouldn't be wiped out.)

An annoying restriction of MATLAB is that only one C function can be defined per mex file. To get around this problem, the wrapper generator defines a C function which takes an extra parameter, which is a code for the function you actually want to call. It also defines a series of MATLAB stub functions to supply the extra parameter. Each of these must be placed into its own separate file (because of another MATLAB design inadequacy) so wrapper generation for MATLAB may actually create hundreds of files if you have a lot of member functions.

You can specify where you want the CW.m files to be placed using the CW-outdir option, like this:

  matwrap -language matlab -outdir wrap_m \
        myfuncs.h -o myfuncs_matlab.c

  mex -f mex_gcc_cxx myfunc

This will create dozens of tiny CW.m files which are placed into the directory CWwrap_m, and a single mexfile with the name myfuncs. DO NOT CHANGE THE NAME OF THE MEX FILE! The CW.m files assume that the name of the C subroutine is the name of the file, in this case, myfuncs. (You can move the mex file to a different directory, if you want, so long as it is still in your matlabpath).

To wrap functions in MATLAB, you'll probably need to specify the CW-f option to the mex command, as shown above. You'll need to create the mex options file so that the appropriate libraries get linked in for . For example, on the machine that I use, I created the file mex_gcc_cxx which contains the following instructions:

        . mexopts.sh            # Load the standard definitions.
        CC='g++'
        CFLAGS='-Wall'
        CLIBS='-lg++ -lstdc++ -lgcc -lm -lc'
        COPTIMFLAGS='-O2 -g'
        CDEBUGFLAGS='-g'

This works with other compilers if you set CWCC and CWCLIBS to use the appropriate compiler and libraries (e.g., CWCLIBS=-lcxx and CWCC=cxx for cxx on Digital Unix).

By default, matwrap uses CWalloca() to allocate temporary memory. If for some reason you want to use CWmxCalloc(), specify CW-use_mxCalloc somewhere on the command line.

The following features of matlab are not currently supported:

Vectors of strings

Structures

It would be nice to be able to return whole structures as MATLAB structures. Maybe this will happen in the future.

Cell arrays

Do not try to pass a cell array instead of a numeric array to a function. It won't work; the wrapper code does not support it.

One quirk of operation which can be annoying is that MATLAB likes to use row vectors instead of column vectors. This can be a problem if you write some C code that expects a vector input, like this:

        void myfunc(double *d, int n_d);  //%input d(n_d)

Suppose now you try to invoke it with the following matlab commands:

        >> myfunc(0:0.1:pi)

The range CW0:0.1:pi is a row vector, not a column vector. As a result, a dimension error will be returned if my_func is not vectorized (which would be the default with these arguments), because the function is expecting an n_d by 1 array instead of a 1 by n_d array. If you allowed CWmyfunc to be vectorized, then CWmyfunc() will be called once for each element of the range, with CWn_d = 1. This is almost certainly not what you wanted. I haven't yet figured out a good way to handle this. Anyway, be careful, and always transpose ranges, like this:

        >> myfunc((0:0.1:pi)')

Octave is much like matlab in that it only allows one callable function to be put into a .oct file. The function in the .oct file therefore takes an extra argument which indicates which function you actually wanted to call. Fortunately, unlike matlab, octave can define more than one function per file so we don't have to have a separate .m file for each function. Instead, the functions are all placed into a separate file whose name you specify on the command line with the -stub option.

To compile an octave module, you would use the following command:

  matwrap -language octave -stub myfuncs_stubs.m \
        myfuncs.h -o myfuncs_octave.cc
  mkoctfile myfuncts_octave

Note that you can't do this unless you have the mkoctfile script installed. mkoctfile is not available in some binary distributions.

Then, in octave, you must first load the stub functions:

  octave:1> myfuncs_subs
  octave:2> # Now you may call the functions.

DO NOT CHANGE THE NAME OF THE .oct FILE! Its name is written into the stub functions. You can move the file into a different directory, however, so long as the directory is in your LOADPATH.

(The mkoctfile script for octave versions below 2.0.8 has an annoying restriction that prevents additional libraries from being linked into your module if your linker is sensitive to the order of the libraries on the command line. The mkoctfile script for versions 2.0.8 and 2.0.9 in theory supports libraries on the command line but it doesn't work. Patches to fix mkoctfile for these versions of octave are provided in share/matwrap/mkoctfile_2_0_8_or_9.patch and share/matwrap/mkoctfile_before_2_0_8.patch.)

If you compile your source code to .o or .a files separately, on many systems you need to force the compiler to make position-independent code (CW-fPIC option to gcc). Remember you are making a shared library, so follow the rules for making shared libraries on your system. The mkoctfile script should do this for you automatically if you have it compile your source files, but if you compile to .o files first and give these to mkoctfile, you may have to be careful to specify the appropriate flags on the CWcc or CWc++ command line.

Octave doesn't seem to provide a good way to support modify variables, i.e., variables that are taken as input and modified and returned as output. For example, suppose you have the function

        void myfunc(float *a, int a_n); //%modify a(a_n)

which takes the array CWa as input, does something to it, and returns its output in the same place. In octave, this would be called as:

        a_out = myfunc(a_in);

rather than as

        myfunc(a);

as it might be from other languages.

Octave has the same quirk as MATLAB in the usage of row vectors where matwrap expects column variables. See the end of the section on MATLAB for details.

Tela (Tensor Language) is a MATLAB clone which is reputed to be considerably faster than MATLAB and has a number of other nice features biassed toward PDEs. It can be found at http://www.geo.fmi.fi/prog/tela.html.

Specify CW-language tela to invoke the Tela wrapper generator, like this:

  matwrap -language tela myfuncs.h -o myfuncs.ct
  telakka myfuncs.ct other_files.o -o tela

That's pretty much all there is to it. Tela doesn't support arrays of strings so CWchar * parameters are not vectorized. Otherwise, just about everything should work as you expect.

WARNING: Tela stores data internally using a row-major scheme instead of the usual column-major ordering, so the indexes of Tela arrays are in reverse order from the index specification order in the CW%input, CW%output, and CW%modify declarations. Sorry, it wasn't my idea.

The tela code generator does not currently support CWshort or CWunsigned short.

Since both MATLAB and Octave use dynamically loadable libraries, it can be tricky to debug your code. MATLAB has a documented way of making a standalone program, but I found this extremely inconvenient. If you have gdb, it is sometimes easier to use the attach command if your operating system supports it. (Linux and Digital Unix do; I do not know about other operating systems.) Start up MATLAB or octave as you normally would, and load the shared library by calling some function in it that doesn't cause it to crash. (Or, put a sleep(3) in an appropriate place in the code, so there is enough time for you to catch it between when it loads the library and when it crashes.) Then while MATLAB or Octave is at the prompt or waiting, attach to the octave/MATLAB process using gdb, set your breakpoints, allow the program to continue, type the command that fails, and debug away.

Matlab 5, octave, and Tela are the only language modules that I've written so far. It's not hard to write a language modulemost of the tricky stuff has been taken care of by the main wrapper generator program. It's just a bit tedious.

The parsing in matwrap is entirely independent of the target language. The back end is supplied by one of several language modules, as specified by the CW-language option.

The interface is designed to make it easy to generate automatically vectorized functions. Vectorization is done automatically by the matwrap code, independent of the language module. All subroutines except those with no output arguments or no input arguments are vectorized except as explicitly requested.

Typically, the function_start() function in the language module will output the function header to the file and declare the arguments to the function. After this, the wrapper generator writes C code to check the dimensions of the arguments.

After checking the dimensions of all variables, the value of the variable is obtained from the function get_c_arg_scalar/get_c_arg_ptr. This returns a pointer to the variable, so if it is vectorized we can easily step through the pointer array. Note that if the desired type is float and the input is an array of double, then the language module will have to make a temporary array of doubles. Output variables are then created by calling make_output_scalar/make_output_ptr.

Next, the C function is called as many times as required.

Next, any modify/output arguments need to have the new values put back into the scripting language variables. This is accomplished by the put_val_scalar/put_val_ptr function. Temporary arrays may be freed here. Note that put_val is not called for input arguments so temporary arrays of input arguments will have to be freed some other way.

Finally, the function function_end is called to do any final cleanup and terminate the function definition.

The following functions and variables must be supplied by the language module. They should be in a package whose name is the same as the argument to the CW-language option. A scalar value indicating the maximum number of dimensions this language can handle (or, at least, the maximum number of dimensions that our scripts will handle). This is 2 for languages like Matlab or Octave which can only have 2-dimensional matrices. A C or expression used to pass the argument to another function which does not know anything about the type of the argument. For example, in the MATLAB module this function returns an expression for the mxArray type for a given argument. This returns a C/ declaration appropriate for the argument passed using arg_pass. For example, in the MATLAB module this function returns mxArray *arg_name_in_arglist. Output routines to make a given constant value accessible from the interpreter. If class name is blank, this is a global constant. None of the language modules currently support definition of constants, but this function is called. A C statement (including the final semicolon, if not surrounded by braces) which indicates that an error has occured because the dimension of argument CW$argname was wrong. Called after all functions have been wrapped, to close the output file and do whatever other cleanup is necessary. This should prepare a documentation string entry for the function and it should set up the definition of the function. It should return a string rather than printing the result. CW%function_def is the array defining all the arguments and outputs for this function. See below for its format. Returns a string which finishes off the definition of a function wrapper. Get the name of an output file. This subroutine is only called if no output file is specified on the command line. CW\@files_processed is a list of the CW.h files which were parsed. Returns C statements to load the current value of the given argument into the C variable CW$function_def{args}{$argname}{c_var_name}. The variable is guaranteed to be either a scalar or an array with dimensions 1,1,1... (depending on the scripting language, these may be identical). Returns C statements to set up a pointer which points to the first value of a given argument. It is possible that the argument may be a scalar, in which case we just want a pointer to that scalar value. (This happens only for vectorizable arguments when the vectorization is not used on this function call.) The dimensions are guaranteed to be correct. The type of the argument should be checked. The pointer value should be stored in the variable CW$function_def{args}{$argname}{c_var_name}. The pointer should actually point to the array of all the values of the variable. The array should have the same number of elements as the argument, since to vectorize the function, the wrapper function will simply step through this array. If we want a float type and the input vector is double or int, then a temporary array must be made which is a copy of the double/int arrays. Returns a C expression which is the size of the CW$n'th dimension of the given argument. Dimension 0 is the least-significant dimension. Write out header information.

  $outfile              The name of the output file.  This file should
                        be opened, and the function should return the
                        name of a file handle (qualified with the
                        package name, e.g., "matlab::OUTFILE").

  @files                A list of files explicitly listed on the command
                        line.  This will be a null array if no files
                        were explicitly listed.

  @cpp_command          The command string words passed to the C
                        preprocessor, if the C preprocessor was run.
                        Otherwise, this will be a null array.

  $include_str          A string of #include statements which represents
                        our best guess as to the proper files to include
                        to make this compilation work.

  int _n_dims(argument)         Returns number of dimensions.
  int _dim(argument, n)         Returns the size in the n'th dimension,
                                where 0 is the first dimension.

First, there are a few entries that describe the interface to the scripting language:

name

The name of the function.

class

The class of which this is a member function. This element will be blank if it is a global function.

script_name

The name of the function in the scripting language. If this field is blank, then the name of the function should be generated from the class and name fields. This field is set by the CW%name directive.

static

True if this is a static member function. Non-static member functions will have the class pointer specified as the first argument in the argument list.

inputs

A list of the names of arguments to the scripting language function which are only for input. Argument names are generated from the corresponding argument names in the C function prototype.

modifies

A list of the names of arguments to the scripting language function which are for both input and output. Argument names are generated from the corresponding argument names in the C function prototype.

outputs

A list of the names of arguments to the scripting language function which are for output. Argument names are generated from the corresponding argument names in the C function prototype. retval is used as the name of the return value of the function, if there is a return value.

args

An associative array indexed by the argument name which contains information about each argument of the function. Note that there may be more arguments in this associative array than in the inputs/modifies/outputs arrays because some of the arguments to the function may be merely the dimension of arrays, which are not arguments in the scripting language since they can be determined by other means. Note that there will also be an entry in the args array for retval if the function has a return value, since the return value is treated as an output argument. The fields in this associative array are:

source

Whether this is an input, output, or modify variable, or whether it can be calculated from the dimension of another variable. These are the only legal values for this field.

type

The type of this argument, i.e., float, double, int, char *, or <class name> * or various combinations involving &, *, and const. All typedefs have been translated to the basic types or class names, and [] is translated to *. Otherwise, no other modifications have been made.

basic_type

Same as the type field, except that the const qualifiers have been stripped, a trailing '&' has been deleted, and a trailing '*' has been deleted if this is an array type or if it's a basic type like 'double', 'int', etc., which we recognize.

dimension

The dimensions of this array argument. This is a reference to a list of dimensions. Each element of the list must be the name of an integer argument to the C function or else a decimal integer. If this argument is not an array, then this field will still be present but will contain no elements.

vectorize

Whether this argument may be supplied as a vector. If so, the wrapper generator will automatically vectorize the function in the sense that MATLAB functions like sin or cos are vectorized.

c_var_name

The variable name which contains the argument which is passed to the C function. The c_var_name is guaranteed not to be the same as the argument name itself, to avoid conflict with the argument declaration of the function. If the argument is to be vectorized, or if the argument is an array, then c_var_name is the name of a pointer to an array of the argument. If the argument is not to be vectorized, then c_var_name is the name of a variable containing the argument.

calculate

A C expression indicating how to calculate this particular variable from the dimension of other input/modify variables. This field will not be present if we don't see any way to calculate this variable from the other variables.

The remaining elements in the associative array for each function describe the arguments to the C/ function and its return type:

returns

A scalar containing the return type of the function. This information is also contained in the retval entry in the args array.

argnames

A list containing the name of each argument in order in the C function's argument list. If no name was specified in the prototype, a name is generated for it, since our entire scheme depends on each argument having a unique name.

vectorize

Whether a vectorized wrapper function should be generated at all, i.e., a version which calls the C function once for each element of scalar arguments which are passed in a vector. Note that vectors may be supplied for some arguments but not others, depending on the vectorize field in the args array (see above).

pass_by_pointer_reference

True if we are supposed to pass a pointer to the argument, not the argument itself. This is used for pass-by-reference when the type is double *. This is always 0 for arrays, which are handled separately.

Additional fields

The language module may add additional fields as necessary. Only those listed above are set up or used by the main wrapper generator code.

For example, if the function prototype is

        double atan2(double y, double x)

then

  $global_functions{'atan2'} = {
    name          => 'atan2',
    class         => '',
    static        => 0,
    inputs        => ["y", "x"],
    modifies      => [],
    outputs       => ["retval"],
    args          => { x => { source     => "input",
                              type       => "double",
                              basic_type => "double",
                              dimension  => [],
                              c_var_name => "_arg_x",
                              vectorize  => 1,
                              pass_by_pointer_reference = 0 },
                       y => { source     => "input",
                              type       => "double",
                              basic_type => "double",
                              dimension  => [],
                              c_var_name => "_arg_y",
                              vectorize  => 1,
                              pass_by_pointer_reference = 0 },
                       retval => { source     => "output",
                                   type       => "double",
                                   basic_type => "double",
                                   dimension  => [],
                                   c_var_name => "_arg_retval",
                                   vectorize  => 1,
                                   pass_by_pointer_reference = 0 } },
    returns       => "double",
    argnames      => ["x", "y"],
    vectorize     => 1
  };

This function is sufficiently simple that all of the relevant information can be filled out automatically, without any help from the user. For a more complicated function, it may not be possible to do so. For example, consider the following function (from the pgplot distribution):

  void cpgbin(int nbin, const float *x, const float *data, Logical center);

This function plots a histogram of the given data, where CWx[] are the abscissae values and CWdata[] are the data values. CWLogical has been defined by a typedef statement earlier in the .h file to be CWint.

By default, the wrapper generator will interpret the CWfloat * as a declaration to pass a scalar argument by reference. In this case, this is not what is wanted, so the definition file must contain additional information:

  void cpgbin(int nbin, const float *x, const float *data, Logical center);
  //%input x(n)
  //%input data(n)

This tells us that the x and data arrays are the same size, which is given by nbin. With this information, then, the following will be produced:

  $global_functions{'cpgbin'} = {
    name          => 'cpgbin',
    inputs        => ["x", "data", "center" ],
    modifies      => [],
    outputs       => [],
    args          => { "nbin" => { source     = "dimension",
                                   type       = "int",
                                   basic_type = "int",
                                   dimension  = [],
                                   vectorize  = 0,
                                   pass_by_pointer_reference = 0 },
                       "x" => { source     = "input",
                                type       = "float *",
                                basic_type = "float",
                                dimension  = ["nbin"],
                                vectorize  = 1,
                                pass_by_pointer_reference = 0 },
                       "data" => { source     = "input",
                                   type       = "float *",
                                   basic_type = "float",
                                   dimension  = ["nbin"],
                                   vectorize  = 1,
                                   pass_by_pointer_reference = 0 },
                       "center" => { source     = "input",
                                     type       = "int",
                                     basic_type = "int",
                                     dimension  = [],
                                     vectorize  = 1,
                                     pass_by_pointer_reference = 0 } },
    returns       => "void",
    argnames      => ["nbin", "x", "data", "center" ],
    vectorize     => 0
  };

Note that since this function has no output arguments, we do not attempt to provide a vectorized version of it.

Gary Holt (holt@LNC.usc.edu).

The latest version of matwrap should be available from http://LNC.usc.edu/~holt/matwrap/.