.rn '' }`
''' $RCSfile$$Revision$$Date$
'''
''' $Log$
'''
.de Sh
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb
.ft CW
.nf
.ne \\$1
..
.de Ve
.ft R

.fi
..
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(*W-|\(bv\*(Tr
.ie n \{\
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
'br\}
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
.\}
.TH MATWRAP 1 "perl 5.005, patch 03" "13/Dec/1999" "User Contributed Perl Documentation"
.UC
.if n .hy 0
.if n .na
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
.bd B 3
.	\" fudge factors for nroff and troff
.if n \{\
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
.\}
.if t \{\
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
.\}
.	\" simple accents for nroff and troff
.if n \{\
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
.\}
.if t \{\
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
.\}
.	\" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.	\" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
.\}
.rm #[ #] #H #V #F C
.SH "NAME"
matwrap -- Wrap \*(C+ functions/classes for various matrix languages
.SH "FEATURES"
matwrap is a script to generate wrapper functions for
matrix-oriented scripting languages so that \*(C+ 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/.
.PP
matwrap can handle the following constructs:
.Ip "Ordinary functions" 4
For example, suppose you have some functions defined in an \f(CW.h\fR file,
like this:
.Sp
.Vb 2
\&    float fiddle(double arg);
\&    double tweedle(int x, char *name);
.Ve
You can access these directly from \s-1MATLAB\s0 by using the following:
.Sp
.Vb 2
\&  matwrap -language matlab -o myfuncs_wrap.c fiddle.h
\&  cmex myfuncs.o myfuncs_wrap.c -o myfuncs_wrap
.Ve
Then, in \s-1MATLAB\s0, you can do the following:
.Sp
.Vb 2
\&  y = tweedle(3, 'Hello, world');
\&  A = fiddle([3, 4; 5, 6];
.Ve
Note especially the last statement, where instead of passing a scalar as
the argument, we pass a matrix.  The C function \fIfiddle()\fR is called
repeatedly on each element of the matrix and the result is returned as a
2x2 matrix.
.Sp
Floats, doubles, char *, integer, unsigned, and pointers to structures
may be used as arugments.  Support for other data types (e.g., various
\*(C+ 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.  \*(C+ operator definitions are not
supported either.
.Ip "\*(C+ classes" 4
You can access public member functions and simple public data members of
classes.  For example,
.Sp
.Vb 6
\&  class ABC {
\&  public:
\&    ABC(int constructor_arg);
\&    void do_something(float number, int idx);
\&    double x;
\&  };
.Ve
From \s-1MATLAB\s0 or a similar language, you would access this structure like
this:
.Sp
.Vb 5
\&  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.
.Ve
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.
.Sp
The same thing will work for C structs\*(--the only difference is that they
have only data members and no member functions.
.Sp
Only public members are accessible from the scripting language.
Operator overloading and function overloading are not supported.
Function pointers are not supported.
.Ip "Arrays" 4
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:
.Sp
.Vb 1
\&  void cpgbin(int nbin, const float *x, const float *data, Logical center);
.Ve
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:
.Sp
.Vb 1
\&  //%input x(nbin), data(nbin)
.Ve
then from a \s-1MATLAB\s0\-like language, you can call this function like this:
.Sp
.Vb 1
\&  cpgbin(X, Data, 1)
.Ve
where \f(CWX\fR and \f(CWData\fR are vectors.  The \f(CWnbin\fR argument is determined
from the length of the \f(CWX\fR and \f(CWData\fR vectors automatically (and the
wrapper generator makes sure they are of the same length!).
.Sp
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.)
.Sp
You may only use variable name or a constant for the array dimension.
You can also use expressions like \f(CW2*nbin\fR or \f(CW2*nbin+1\fR.  If the
expression is sufficiently simple, the wrapper generator will determine
the values of any integer values (like \f(CWnbin\fR in this example) from the
dimension of the input arrays, so they do not have to be specified as an
argument.
.SH "REQUIREMENTS"
.Ip "A \*(C+ compiler" 4
In theory, this could be made to work with an \s-1ANSI\s0 C compiler, but I
haven't tried to yet.  Currently, you must have a full \*(C+ compiler.
I've used primarily gcc and I tested very briefly with \s-1DEC\s0's cxx.
.Ip "\f(CWalloca()\fR" 4
If you are using matlab, then you can tell matwrap to use \f(CWmxCalloc\fR
instead of \f(CWalloca\fR by specifying \f(CW-use_mxCalloc\fR somewhere on the
command line.  Otherwise, you must have a compiler that supports
\f(CWalloca()\fR.  (gcc does.)
.Sp
\f(CWalloca()\fR is usually a little more efficient than \f(CWmxCalloc()\fR.  It
allocates space on the stack rather than the heap.  Unfortunately, you
may have a limited stack size, and so \f(CWalloca()\fR may fail for large
temporary arrays.  In this case, you may need to issue a command like
.Sp
.Vb 1
\&   unix('unlimit stacksize')
.Ve
or else use the \f(CW-use_mxCalloc\fR option.
.Ip "A relatively recent version of perl" 4
I've tested this only with perl 5.004 and 5.005.  Check out
http://www.perl.com/ for how to get perl.
.SH "USAGE"
.PP
.Vb 1
\&  matwrap -language languagename [-options] infile1.h infile2.h
.Ve
.Vb 2
\&  matwrap -language languagename [-options] \e
\&    -cpp cxx [-options_to_C_compiler] infile.cxx
.Ve
.SH "DESCRIPTION"
Using the first form, without the \f(CW-cpp\fR flag, files are parsed in the order
listed, so you should put any files with required typedefs and other
definitions first.  These files are \f(CW#include\fRd by the generated
wrapper code; in fact, they are the only files which are \f(CW#include\fRd.
This form can be used 1) if you don't have any \f(CW#if\fRs 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.
.PP
Alternatively, you can use the \f(CW-cpp\fR 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 \f(CW#include\fR hierarchy.  It also means that wrapper
generation runs considerably slower.  Matwrap will attempt
to guess which files need to be \f(CW#include\fRd, but it may guess wrong.
.PP
Overloaded functions and definitions of operators are not supported.  \*(C+
classes are supported (this is the main reason for this script).  Member
functions may be called, and member fields may be accessed.
.Sh "Options"
.Ip "-cpp" 4
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.,
.Sp
.Vb 2
\&  matwrap -language octave -o myfile_wrap.cxx \e
\&        -cpp g++ -Iextra_includes -Dmy_thingy=3 myfile.cxx
.Ve
All words after the \-cpp option are ignored (and passed verbatim to the
compiler), so you must supply a \f(CW-o\fR option before the \f(CW-cpp\fR.  Note that
\f(CW-o\fR 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 \f(CW-E\fR flag in the compiler command, it will be inserted for you
immediately after the name of the compiler.  Also, the \f(CW-C\fR option is
added along with the \f(CW-E\fR option so that any comments can be processed
and put into the documentation strings.  (As far as I know all compilers
support \f(CW-C\fR and \f(CW-E\fR but undoubtably this won't work well with some.  It
works fine with gcc.)
.Sp
When run in this way, \f(CWmatwrap\fR does not generate wrappers for
any functions or classes defined in files located in \f(CW/usr/include\fR or
\f(CW/usr/local/include\fR or in subdirectories of \f(CW*/gcc-lib\fR.  (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 \f(CW.h\fR files, either copy
\&\f(CW.h\fR 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).
.Ip "-cpp_ignore filename_or_directory" 4
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 \f(CW/usr/include\fR, \f(CW/usr/local/include\fR, or \f(CW*/gcc-lib\fR are not
wrapped.
.Ip "\f(CW-o\fR file" 4
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., \s-1MATLAB\s0)
will not infer a file name from your source files (this is for your
protection, so we don't accidentally wipe out a \f(CW.c\fR file with the same
name).  If you use the \f(CW-cpp\fR option, you must also specify the \f(CW-o\fR
option before the \f(CW-cpp\fR option.
.Ip "-language <language_name>" 4
Specify the language.  This option is mandatory.
.Ip "-wraponly <list>" 4
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 \f(CW.h\fR files that you
need to define all the types, but only to wrap some of the functions.
.Sp
Global functions and variables are specified simply by name.  Classes
are specified by the word \*(L'class\*(R' followed by the class name.  For
example,
.Sp
.Vb 2
\&  matwrap -language matlab myfile.h \e
\&         -wraponly myglobalfunc class myclass
.Ve
.SH "Input files"
Input files are designed to be your ordinary .h files, so your wrapper
and your \*(C+ 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:
.PP
.Vb 1
\&  double abcize(float a, int b, char *c, SomeClass *d);
.Ve
This will pass a single-precision floating point number as argument \f(CWa\fR
(probably converting from double precision or integer, depending on what
the interpreted language stored the value as).  An integer is passed as
argument \f(CWb\fR (probably converted from a double precision value).  A
null-terminated string is passed as argument \f(CWc\fR (converted from
whatever weird format the language uses).  The argument \f(CWd\fR must be a
pointer value which was returned by another function.
.PP
Vectorization is automatically performed, so that if you pass a matrix
of \f(CWm\fR by \f(CWn\fR inputs as argument \f(CWa\fR and arguments \f(CWb\fR and \f(CWc\fR as
either scalars or \f(CWm\fR by \f(CWn\fR matrices, then the function will be
called \f(CWm*n\fR times and the result will be an \f(CWm\fR by \f(CWn\fR matrix.
By default, a function is vectorized if it has both inputs and outputs
(see under \f(CW//%vectorize\fR below).  Most matrix languages do not support
vectors of strings in a natural way, so \f(CWchar *\fR arguments are not
vectorized.
.PP
Passing arguments by reference is handled in the expected way.  For
example, given the declaration
.PP
.Vb 1
\&  void fortran_sub(double *inarg1, float *inarg2);
.Ve
pointers to double and single precision numbers will be passed to the
subroutine instead of the numbers themselves.
.PP
This creates an ambiguity for the type \f(CWchar *\fR.  For example, consider
the following two functions:
.PP
.Vb 2
\&        void f1(char *a);
\&        void f2(unsigned char *b);
.Ve
Matwrap assumes that the function \f(CWf1\fR is passed a null terminated
string, despite the fact that the argument \f(CWa\fR could be a pointer to a
buffer where \f(CWf1\fR returns a character.  Although this situation can be
disambiguated with proper use of the \f(CWconst\fR qualifier, matwrap treats
\f(CWchar *\fR and \f(CWconst char *\fR as identical since many programs don't use
\f(CWconst\fR properly.  Matwrap assumes, however, that \f(CWunsigned char *\fR
is not a null terminated string but an \f(CWunsigned char\fR variable passed
by reference.  You can also force it to interpret \f(CWchar *\fR as a signed
char passed by reference by specifying the qualifier \f(CW//%input a(1)\fR
(see below).
.PP
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 \f(CW//%input\fR or \f(CW//%output\fR qualifiers.  All qualifiers follow
the definition of the function (after the \f(CW;\fR or the closing \f(CW}\fR if it
is an inline function).  Valid qualifiers are:
.Ip "//%novectorize_type type1, type2, ..." 4
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.)
.Ip "//%novectorize" 4
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.
.Ip "//%vectorize" 4
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.
.Ip "//%nowrap" 4
Don't wrap this function.  It will therefore not be callable directly
from your scripting language.
.Ip "//%name new_name" 4
Specify a different name for the function when it is invoked from the
scripting language.
.Ip "//%input argname(dim1, dim2, ...), argname(dim)" 4
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., \*(L"n\*(R" or \*(L"n+1\*(R" or \*(L"2*n\*(R", and if
the expression includes another argument to the function ("n\*(R" 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.  
.Sp
For example, if you have a function which is declared like this:
.Sp
.Vb 3
\&        void myfunc(int n, double *x, double *y);
\&                        //%input x(3*n+4)
\&                        //%output y(n*(n+1)/2)
.Ve
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:
.Sp
.Vb 1
\&        y = myfunc(x)
.Ve
On the other hand, if you had a specification like this:
.Sp
.Vb 3
\&        void return_diag(int n, double *x, double *y);
\&                        //%input x(n*(n+1)/2)
\&                        //%output y(n)
.Ve
then n will have to be explicitly specified because it is too difficult
to calculate:
.Sp
.Vb 1
\&        y = myfunc(n, x)
.Ve
.Ip "//%modify argname(dim1, dim2, ...), argname(dim1)" 4
.Ip "//%output argname(dim1, dim2, ...), argname(dim1)" 4
Same as \f(CW//%input\fR except that this also tags the variables as modify
or output variables.  If you don't specify a dimension expression (e.g.,
\*(L"//%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.)
.Sh "Unsupported \*(C+ constructs"
.Ip "Function overloading" 4
.Ip "Operator definition" 4
.Ip "Function and member function pointers" 4
It would be really nice to support these, but I think it's also really
hard.  Maybe someday.
.Ip "Two-dimensional arrays using a vector of pointers" 4
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 \f(CWfloat *x\fR, and the \f(CWi,j\fR'th element is accessed
by \f(CWx[j*n+i]\fR.  You cannot use two dimensional arrays if they are
declared like \f(CWfloat **x\fR and accessed like \f(CWx[i][j]\fR.  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.
.Ip "Arrays with an offset" 4
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:
.Sp
.Vb 4
\&  void savgol(float c[], int np, int nl, int nr, int ld, int m);
\&  
\&where the index in the array C<c> is declared to run from 1 to np.
\&You'd have to declare the array like this:
.Ve
.Vb 1
\&                                //%output c(np+1)
.Ve
and then ignore the first element.  Thus from \s-1MATLAB\s0 you'd call it with
the following sequence:
.Sp
.Vb 3
\&        savgol_coefs = savgol(np, nl, nr, ld, m);
\&        savgol_coefs = savgol_coefs(2:length(savgol_coefs));
\&                                % Discard the unused first element.
.Ve
.Ip "Passing structures by value or \*(C+ reference" 4
In other words, if Abc is the name of a class, declarations like
.Sp
.Vb 1
\&        void myfunc(Abc x);
.Ve
or
.Sp
.Vb 1
\&        void myfunc(Abc &x);
.Ve
won't work.  However, you can pass a pointer to the class:
.Sp
.Vb 1
\&        void myfunc(Abc *x);
.Ve
The wrapper generator will do the type checking and it even handles
inheritance properly.
.SH "Examples"
For more examples, see the subdirectories of \fIshare/matwrap/Examples\fR
in the distribution.  This includes a wrapper for the entire PGPLOT
library (directory \fIpgplot\fR) and a sample \*(C+ simulator for an neuron
governed by the Hodgkin-Huxley equations (directory \fIsingle_axon\fR).
.SH "Support for different languages"
.Sh "\s-1MATLAB\s0 5"
Currently, you must compile the generated wrapper code using \*(C+, even
if you are wrapping only C functions with no \*(C+ classes.  You can
compile your C functions using C as you please; you may have to put a
\f(CWextern "C" { }\fR statement in the .h file.  This restriction may be
lifted in the future.
.PP
The default maximum number of dimensions supported is four.  You can
change this by modifying the \f(CW$max_dimensions\fR variable near the top of
the file share/matwrap/wrap_matlab.pl in the distribution.
.PP
Specify \f(CW-langauge matlab\fR on the command line to use the matlab code
generator.  You \s-1MUST\s0 also use \f(CW-o\fR to specify the output file name.
(This is because matlab wrappers have an extension of \f(CW.c\fR 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.)
.PP
An annoying restriction of \s-1MATLAB\s0 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
\s-1MATLAB\s0 stub functions to supply the extra parameter.  Each of these must
be placed into its own separate file (because of another \s-1MATLAB\s0 design
inadequacy) so wrapper generation for \s-1MATLAB\s0 may actually create
hundreds of files if you have a lot of member functions.
.PP
You can specify where you want the \f(CW.m\fR files to be placed using the
\f(CW-outdir\fR option, like this:
.PP
.Vb 2
\&  matwrap -language matlab -outdir wrap_m \e
\&        myfuncs.h -o myfuncs_matlab.c
.Ve
.Vb 1
\&  mex -f mex_gcc_cxx myfunc
.Ve
This will create dozens of tiny \f(CW.m\fR files which are placed into the
directory \f(CWwrap_m\fR, and a single mexfile with the name \fImyfuncs\fR.  \s-1DO\s0
\s-1NOT\s0 \s-1CHANGE\s0 \s-1THE\s0 \s-1NAME\s0 \s-1OF\s0 \s-1THE\s0 \s-1MEX\s0 \s-1FILE\s0!  The \f(CW.m\fR files assume that the
name of the C subroutine is the name of the file, in this case,
\fImyfuncs\fR.  (You can move the mex file to a different directory, if you
want, so long as it is still in your matlabpath).
.PP
To wrap \*(C+ functions in \s-1MATLAB\s0, you'll probably need to specify the
\f(CW-f\fR 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
\*(C+.  For example, on the machine that I use, I created the file
\fImex_gcc_cxx\fR which contains the following instructions:
.PP
.Vb 6
\&        . mexopts.sh            # Load the standard definitions.
\&        CC='g++'
\&        CFLAGS='-Wall'
\&        CLIBS='-lg++ -lstdc++ -lgcc -lm -lc'
\&        COPTIMFLAGS='-O2 -g'
\&        CDEBUGFLAGS='-g'
.Ve
This works with other \*(C+ compilers if you set \f(CWCC\fR and \f(CWCLIBS\fR to use the
appropriate compiler and libraries (e.g., \f(CWCLIBS=-lcxx\fR and \f(CWCC=cxx\fR
for cxx on Digital Unix).
.PP
By default, matwrap uses \f(CWalloca()\fR to allocate temporary memory.  If
for some reason you want to use \f(CWmxCalloc()\fR, specify \f(CW-use_mxCalloc\fR
somewhere on the command line.
.PP
The following features of matlab are not currently supported:
.Ip "Vectors of strings" 4
.Ip "Structures" 4
It would be nice to be able to return whole \*(C+ structures as \s-1MATLAB\s0
structures.  Maybe this will happen in the future.
.Ip "Cell arrays" 4
Do not try to pass a cell array instead of a numeric array to a \*(C+
function.  It won't work; the wrapper code does not support it.
.PP
One quirk of operation which can be annoying is that \s-1MATLAB\s0 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:
.PP
.Vb 1
\&        void myfunc(double *d, int n_d);  //%input d(n_d)
.Ve
Suppose now you try to invoke it with the following matlab commands:
.PP
.Vb 1
\&        >> myfunc(0:0.1:pi)
.Ve
The range \f(CW0:0.1:pi\fR 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 \f(CWmyfunc\fR to be vectorized, then \f(CWmyfunc()\fR will be called once
for each element of the range, with \f(CWn_d = 1\fR.  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:
.PP
.Vb 1
\&        >> myfunc((0:0.1:pi)')
.Ve
.Sh "Octave"
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 \*(C+ 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.
.PP
To compile an octave module, you would use the following command:
.PP
.Vb 3
\&  matwrap -language octave -stub myfuncs_stubs.m \e
\&        myfuncs.h -o myfuncs_octave.cc
\&  mkoctfile myfuncts_octave
.Ve
Note that you can't do this unless you have the \fImkoctfile\fR script
installed.  \fImkoctfile\fR is not available in some binary distributions.
.PP
Then, in octave, you must first load the stub functions:
.PP
.Vb 2
\&  octave:1> myfuncs_subs
\&  octave:2> # Now you may call the functions.
.Ve
\s-1DO\s0 \s-1NOT\s0 \s-1CHANGE\s0 \s-1THE\s0 \s-1NAME\s0 \s-1OF\s0 \s-1THE\s0 .oct \s-1FILE\s0!  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 \s-1LOADPATH\s0.
.PP
(The \fImkoctfile\fR 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 \fImkoctfile\fR 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 \fImkoctfile\fR for these versions of octave are provided in
\fIshare/matwrap/mkoctfile_2_0_8_or_9.patch\fR and
\fIshare/matwrap/mkoctfile_before_2_0_8.patch\fR.)
.PP
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
(\f(CW-fPIC\fR option to gcc).  Remember you are making a shared library, so
follow the rules for making shared libraries on your system.  The
\fImkoctfile\fR 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 \fImkoctfile\fR, you may have to be careful to specify the
appropriate flags on the \f(CWcc\fR or \f(CWc++\fR command line.
.PP
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
.PP
.Vb 1
\&        void myfunc(float *a, int a_n); //%modify a(a_n)
.Ve
which takes the array \f(CWa\fR as input, does something to it, and returns
its output in the same place.  In octave, this would be called as:
.PP
.Vb 1
\&        a_out = myfunc(a_in);
.Ve
rather than as
.PP
.Vb 1
\&        myfunc(a);
.Ve
as it might be from other languages.
.PP
Octave has the same quirk as \s-1MATLAB\s0 in the usage of row vectors where
matwrap expects column variables.  See the end of the section on \s-1MATLAB\s0
for details.
.Sh "Tela"
Tela (Tensor Language) is a \s-1MATLAB\s0 clone which is reputed to be considerably
faster than \s-1MATLAB\s0 and has a number of other nice features biassed toward PDEs.
It can be found at http://www.geo.fmi.fi/prog/tela.html.
.PP
Specify \f(CW-language tela\fR to invoke the Tela wrapper generator, like this:
.PP
.Vb 2
\&  matwrap -language tela myfuncs.h -o myfuncs.ct
\&  telakka myfuncs.ct other_files.o -o tela
.Ve
That's pretty much all there is to it.  Tela doesn't support arrays of
strings so \f(CWchar *\fR parameters are not vectorized.  Otherwise, just
about everything should work as you expect.
.PP
\s-1WARNING\s0: 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 \f(CW%input\fR,
\f(CW%output\fR, and \f(CW%modify\fR declarations.  Sorry, it wasn't my idea.
.PP
The tela code generator does not currently support \f(CWshort\fR or
\f(CWunsigned short\fR.
.Sh "A note on debugging"
Since both \s-1MATLAB\s0 and Octave use dynamically loadable libraries, it can
be tricky to debug your \*(C+ code.  \s-1MATLAB\s0 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 \*(L"attach\*(R" command if your
operating system supports it.  (Linux and Digital Unix do; I do not know
about other operating systems.)  Start up \s-1MATLAB\s0 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 \*(L"\fIsleep\fR\|(30)\*(R" 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
\s-1MATLAB\s0 or Octave is at the prompt or waiting, attach to the
octave/\s-1MATLAB\s0 process using gdb, set your breakpoints, allow the program
to continue, type the command that fails, and debug away.
.SH "Writing new language support modules"
Matlab 5, octave, and Tela are the only language modules that I've
written so far.  It's not hard to write a language module\*(--most of the
tricky stuff has been taken care of by the main wrapper generator
program.  It's just a bit tedious.
.PP
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 \f(CW-language\fR option.
.PP
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.
.PP
Typically, the \fIfunction_start()\fR 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.
.PP
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
\*(L"float\*(R" and the input is an array of \*(L"double\*(R", 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.
.PP
Next, the C function is called as many times as required.
.PP
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.
.PP
Finally, the function function_end is called to do any final cleanup and
terminate the function definition.
.PP
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 \f(CW-language\fR option.
.Ip "\f(CW$max_dimensions\fR" 4
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.
.Ip "\f(CWarg_pass(\e%function_def, $argname)\fR" 4
A C or \*(C+ expression used to pass the argument to another function
which does not know anything about the type of the argument.  For
example, in the \s-1MATLAB\s0 module this function returns an expression for
the mxArray type for a given argument.
.Ip "\f(CWarg_declare("\fRarg_name_in_arglist\f(CW")\fR" 4
This returns a C/\*(C+ declaration appropriate for the argument passed
using arg_pass.  For example, in the \s-1MATLAB\s0 module this function returns
\*(L"mxArray *arg_name_in_arglist\*(R".
.Ip "\f(CWdeclare_const("\fRconstant name\f(CW", "\fRclass name\f(CW", "\fRtype\f(CW")\fR" 4
Output routines to make a given constant value accessible from the interpreter.
If \*(L"class name\*(R" is blank, this is a global constant.
.Sp
None of the language modules currently support definition of constants,
but this function is called.
.Ip "\f(CWerror_dimension(\e%function_def, $argname)\fR" 4
A C statement (including the final semicolon, if not surrounded by braces)
which indicates that an error has occured because the dimension of argument
\f(CW$argname\fR was wrong.
.Ip "\f(CWfinish()\fR" 4
Called after all functions have been wrapped, to close the output file and do
whatever other cleanup is necessary.
.Ip "\f(CWfunction_start(\e%function_def)\fR" 4
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.
.Sp
\f(CW%function_def\fR is the array defining all the arguments and outputs for this
function.  See below for its format.
.Ip "\f(CWfunction_end(\e%function_def)\fR" 4
Returns a string which finishes off the definition of a function wrapper.
.Ip "\f(CWget_outfile(\e@files_processed)\fR" 4
Get the name of an output file.  This subroutine is only called if no output
file is specified on the command line.  \f(CW\e@files_processed\fR is a list of the
\&\f(CW.h\fR files which were parsed.
.Ip "\f(CWget_c_arg_scalar(\e%function_def, $argname)\fR" 4
Returns C statements to load the current value of the given argument
into the C variable \f(CW$function_def{args}{$argname}{c_var_name}\fR.  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).
.Ip "\f(CWget_c_arg_ptr(\e%function_def, $argname)\fR" 4
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
\f(CW$function_def{args}{$argname}{c_var_name}\fR.
.Sp
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.
.Ip "\f(CWget_size(\e%function_def, $argname, $n)\fR" 4
Returns a C expression which is the size of the \f(CW$n\fR'th dimension of the given
argument.  Dimension 0 is the least-significant dimension.
.Ip "\f(CWinitialize($outfile, \e@files_processed, \e@cpp_command, $include_str)\fR" 4
Write out header information.
.Sp
.Vb 4
\&  $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").
.Ve
.Vb 3
\&  @files                A list of files explicitly listed on the command
\&                        line.  This will be a null array if no files
\&                        were explicitly listed.
.Ve
.Vb 3
\&  @cpp_command          The command string words passed to the C
\&                        preprocessor, if the C preprocessor was run.
\&                        Otherwise, this will be a null array.
.Ve
.Vb 3
\&  $include_str          A string of #include statements which represents
\&                        our best guess as to the proper files to include
\&                        to make this compilation work.
.Ve
This function also should write out \*(C+ code to define the following
functions:
.Sp
.Vb 3
\&  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.
.Ve
.Ip "\f(CWmake_output_scalar(\e%function_def, $argname)\fR" 4
Return C code to create the given output variable.  The output variable
will be a scalar.
.Ip "\f(CWmake_output_ptr(\e%function_def, $argname, $n_dimensions, @dimensions)\fR" 4
Return C code to set up a pointer to where to store the values of the output
variable.  \f(CW$n_dimensions\fR is a C expression, not necessarily a constant.
\f(CW@dimensions\fR is a list of C expressions that are the sizes of each dimension.
There may be more values in \f(CW@dimensions\fR than are needed.
.Ip "\f(CWn_dimensions(\e%function_def, $argname)\fR" 4
Returns a C expression which is the number of dimensions of the argument whose
name is \f(CW$argname\fR.
.Ip "\f(CWpointer_conversion_functions()\fR" 4
Returns code to convert to and from pointer types to the languages
internal representation, if any special code is needed.  If this
subroutine is not called, then there are no class types and pointers
will not need to be handled.
.Ip "\f(CWparse_argv(\e@ARGV)\fR" 4
Scan the argument list for language-specific options.  This is called after the
\f(CW-language\fR option has been parsed and removed from the \f(CW@ARGV\fR array.
.Ip "\f(CWput_val_scalar(\e%function_def, $argname)\fR" 4
Returns C code to take the value from the C variable whose name is given
by \f(CW$function_def{args}{$argname}{c_var_name}\fR and store it back in the
scripting language scalar variable.
.Ip "\f(CWput_val_ptr(\e%function_def, $argname)\fR" 4
Returns C code to take the value from the C array whose name is given by
\f(CW$function_def{args}{$argname}{c_var_name}\fR and store it back in the
scripting language array at the specified index.  The pointer
\f(CW$function_def{args}{$argname}{c_var_name}\fR was set up by either
\f(CWget_c_arg\fR or \f(CWmake_output\fR, depending on whether this is an
input/modify or an output variable.
.Sh "The \f(CW%function_def\fR array"
Many of these arguments require a reference to the \f(CW%function_def\fR associative
array.  This array defines everything that is known about the function.
.PP
First, there are a few entries that describe the interface to the scripting
language:
.Ip "name" 4
The name of the function.
.Ip "class" 4
The class of which this is a member function.  This element will be blank
if it is a global function.
.Ip "script_name" 4
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 \*(L"class\*(R" and \*(L"name\*(R"
fields.  This field is set by the \f(CW%name\fR directive.
.Ip "static" 4
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.
.Ip "inputs" 4
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.
.Ip "modifies" 4
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.
.Ip "outputs" 4
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.  \*(L"retval\*(R" is used as the name of the return value
of the function, if there is a return value.
.Ip "args" 4
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.
.Sp
Note that there will also be an entry in the args array for \*(L"retval\*(R" if the
function has a return value, since the return value is treated as an output
argument.
.Sp
The fields in this associative array are:
.Ip "source" 8
Whether this is an \*(L"input\*(R", \*(L"output\*(R", or \*(L"modify\*(R" variable, or whether
it can be calculated from the \*(L"dimension\*(R" of another variable.  These
are the only legal values for this field.
.Ip "type" 8
The type of this argument, i.e., \*(L"float\*(R", \*(L"double\*(R", \*(L"int\*(R", \*(L"char *\*(R", or \*(L"<class
name> *\*(R" or various combinations involving \*(L"&\*(R", \*(L"*\*(R", and \*(L"const\*(R".  All typedefs
have been translated to the basic types or class names, and \*(L"[]\*(R" is translated
to \*(L"*\*(R".  Otherwise, no other modifications have been made.
.Ip "basic_type" 8
Same as the \*(L"type\*(R" field, except that the \*(L"const\*(R" qualifiers have been
stripped, a trailing \*(L'&\*(R' has been deleted, and a trailing \*(L'*\*(R' has been
deleted if this is an array type or if it's a basic type like \*(L'double\*(R',
\&'int\*(R', etc., which we recognize.
.Ip "dimension" 8
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.
.Ip "vectorize" 8
Whether this argument may be supplied as a vector.  If so, the wrapper
generator will automatically \*(L"vectorize\*(R" the function in the sense that \s-1MATLAB\s0
functions like \*(L"sin\*(R" or \*(L"cos\*(R" are vectorized.
.Ip "c_var_name" 8
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.
.Sp
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.
.Ip "calculate" 8
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.
.PP
The remaining elements in the associative array for each function describe the 
arguments to the C/\*(C+ function and its return type:
.Ip "returns" 4
A scalar containing the return type of the function.  This information is also
contained in the \*(L"retval\*(R" entry in the \*(L"args\*(R" array.
.Ip "argnames" 4
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.
.Ip "vectorize" 4
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 \*(L"vectorize\*(R" field in the args array
(see above).
.Ip "pass_by_pointer_reference" 4
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 \*(L"double *\*(R".
This is always 0 for arrays, which are handled separately.
.Ip "Additional fields" 4
The language module may add additional fields as necessary.  Only those listed
above are set up or used by the main wrapper generator code.
.PP
For example, if the function prototype is
.PP
.Vb 1
\&        double atan2(double y, double x)
.Ve
then 
.PP
.Vb 32
\&  $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
\&  };
.Ve
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):
.PP
.Vb 1
\&  void cpgbin(int nbin, const float *x, const float *data, Logical center);
.Ve
This function plots a histogram of the given data, where \f(CWx[]\fR are the
abscissae values and \f(CWdata[]\fR are the data values.  \f(CWLogical\fR has been
defined by a typedef statement earlier in the .h file to be \f(CWint\fR.
.PP
By default, the wrapper generator will interpret the \f(CWfloat *\fR 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:
.PP
.Vb 3
\&  void cpgbin(int nbin, const float *x, const float *data, Logical center);
\&  //%input x(nbin)
\&  //%input data(nbin)
.Ve
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:
.PP
.Vb 33
\&  $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
\&  };
.Ve
Note that since this function has no output arguments, we do not attempt
to provide a vectorized version of it.
.SH "AUTHOR"
Gary Holt (holt@LNC.usc.edu).
.PP
The latest version of matwrap should be available from
http://LNC.usc.edu/~holt/matwrap/.

.rn }` ''
.IX Title "MATWRAP 1"
.IX Name "matwrap - Wrap C++ functions/classes for various matrix languages"

.IX Header "NAME"

.IX Header "FEATURES"

.IX Item "Ordinary functions"

.IX Item "\*(C+ classes"

.IX Item "Arrays"

.IX Header "REQUIREMENTS"

.IX Item "A \*(C+ compiler"

.IX Item "\f(CWalloca()\fR"

.IX Item "A relatively recent version of perl"

.IX Header "USAGE"

.IX Header "DESCRIPTION"

.IX Subsection "Options"

.IX Item "-cpp"

.IX Item "-cpp_ignore filename_or_directory"

.IX Item "\f(CW-o\fR file"

.IX Item "-language <language_name>"

.IX Item "-wraponly <list>"

.IX Header "Input files"

.IX Item "//%novectorize_type type1, type2, ..."

.IX Item "//%novectorize"

.IX Item "//%vectorize"

.IX Item "//%nowrap"

.IX Item "//%name new_name"

.IX Item "//%input argname(dim1, dim2, ...), argname(dim)"

.IX Item "//%modify argname(dim1, dim2, ...), argname(dim1)"

.IX Item "//%output argname(dim1, dim2, ...), argname(dim1)"

.IX Subsection "Unsupported \*(C+ constructs"

.IX Item "Function overloading"

.IX Item "Operator definition"

.IX Item "Function and member function pointers"

.IX Item "Two-dimensional arrays using a vector of pointers"

.IX Item "Arrays with an offset"

.IX Item "Passing structures by value or \*(C+ reference"

.IX Header "Examples"

.IX Header "Support for different languages"

.IX Subsection "\s-1MATLAB\s0 5"

.IX Item "Vectors of strings"

.IX Item "Structures"

.IX Item "Cell arrays"

.IX Subsection "Octave"

.IX Subsection "Tela"

.IX Subsection "A note on debugging"

.IX Header "Writing new language support modules"

.IX Item "\f(CW$max_dimensions\fR"

.IX Item "\f(CWarg_pass(\e%function_def, $argname)\fR"

.IX Item "\f(CWarg_declare("\fRarg_name_in_arglist\f(CW")\fR"

.IX Item "\f(CWdeclare_const("\fRconstant name\f(CW", "\fRclass name\f(CW", "\fRtype\f(CW")\fR"

.IX Item "\f(CWerror_dimension(\e%function_def, $argname)\fR"

.IX Item "\f(CWfinish()\fR"

.IX Item "\f(CWfunction_start(\e%function_def)\fR"

.IX Item "\f(CWfunction_end(\e%function_def)\fR"

.IX Item "\f(CWget_outfile(\e@files_processed)\fR"

.IX Item "\f(CWget_c_arg_scalar(\e%function_def, $argname)\fR"

.IX Item "\f(CWget_c_arg_ptr(\e%function_def, $argname)\fR"

.IX Item "\f(CWget_size(\e%function_def, $argname, $n)\fR"

.IX Item "\f(CWinitialize($outfile, \e@files_processed, \e@cpp_command, $include_str)\fR"

.IX Item "\f(CWmake_output_scalar(\e%function_def, $argname)\fR"

.IX Item "\f(CWmake_output_ptr(\e%function_def, $argname, $n_dimensions, @dimensions)\fR"

.IX Item "\f(CWn_dimensions(\e%function_def, $argname)\fR"

.IX Item "\f(CWpointer_conversion_functions()\fR"

.IX Item "\f(CWparse_argv(\e@ARGV)\fR"

.IX Item "\f(CWput_val_scalar(\e%function_def, $argname)\fR"

.IX Item "\f(CWput_val_ptr(\e%function_def, $argname)\fR"

.IX Subsection "The \f(CW%function_def\fR array"

.IX Item "name"

.IX Item "class"

.IX Item "script_name"

.IX Item "static"

.IX Item "inputs"

.IX Item "modifies"

.IX Item "outputs"

.IX Item "args"

.IX Item "source"

.IX Item "type"

.IX Item "basic_type"

.IX Item "dimension"

.IX Item "vectorize"

.IX Item "c_var_name"

.IX Item "calculate"

.IX Item "returns"

.IX Item "argnames"

.IX Item "vectorize"

.IX Item "pass_by_pointer_reference"

.IX Item "Additional fields"

.IX Header "AUTHOR"