Limitations of automatic generated of Swig files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section discusses the limitations of automatically generating
swig files.  From the previous example we see that the module
``NumberIO`` had a swig interface file :samp:`NumberIO.i`
automatically generated by the compiler.  If we consider three of the
procedure definitions in :samp:`NumberIO.def` we can see the
success and limitations of the automatic interface generation.

.. code-block:: modula2

  PROCEDURE StrToHex (a: ARRAY OF CHAR; VAR x: CARDINAL) ;
  PROCEDURE StrToInt (a: ARRAY OF CHAR; VAR x: INTEGER) ;
  PROCEDURE ReadInt (VAR x: CARDINAL) ;

Below are the swig interface prototypes:

.. code-block:: modula2

  extern void NumberIO_StrToHex (char *_m2_address_a,
                                 int _m2_high_a, unsigned int *OUTPUT);
  /*  parameters: x is known to be an OUTPUT */
  extern void NumberIO_StrToInt (char *_m2_address_a,
                                 int _m2_high_a, int *OUTPUT);
  /*  parameters: x is guessed to be an OUTPUT */
  extern void NumberIO_ReadInt (int *x);
  /*  parameters: x is unknown */

In the case of ``StrToHex`` it can be seen that the compiler
detects that the last parameter is an output.  It explicitly tells
swig this by using the parameter name ``OUTPUT`` and in the
following comment it informs the user that it knows this to be an
output parameter.  In the second procedure ``StrToInt`` it marks
the final parameter as an output, but it tells the user that this is
only a guess.  Finally in ``ReadInt`` it informs the user that
it does not know whether the parameter, ``x``, is an output, input
or an inout parameter.

The compiler decides whether to mark a parameter as either:
``INPUT``, ``OUTPUT`` or ``INOUT`` if it is read before
written or visa versa in the first basic block.  At this point
it will write output that the parameter is known.  If it is not
read or written in the first basic block then subsequent basic blocks
are searched and the result is commented as a guess.  Finally if
no read or write occurs then the parameter is commented as unknown.
However, clearly it is possible to fool this mechanism.  Nevertheless
automatic generation of implementation module into swig interface files
was thought sufficiently useful despite these limitations.

In conclusion it would be wise to check all parameters in any
automatically generated swig interface file.  Furthermore you can
force the automatic mechanism to generate correct interface files by
reading or writing to the ``VAR`` parameter in the first basic
block of a procedure.