"Fossies" - the Fresh Open Source Software Archive

Member "swig-4.1.1/Doc/Devel/migrate.txt" (30 Nov 2022, 4759 Bytes) of package /linux/misc/swig-4.1.1.tar.gz:

    1 SWIG1.3 Migration Guide 
    2 (The not entirely complete guide to updating language modules to work with SWIG1.3).
    3 
    4 Dave Beazley
    5 August 15, 2000
    6 
    7 1. Introduction
    8 ---------------
    9 
   10 Virtually all of SWIG's internal data structures have now been
   11 rewritten.  Take everything you thought you knew about SWIG1.1 and
   12 throw it out.
   13 
   14 2. DataTypes
   15 ------------
   16 The old 'DataType' data structure is gone.  Therefore, direct
   17 manipulation of 'is_pointer', 'implicit_ptr', and 'arraystr'
   18 attributes no longer applies.  Sorry.
   19 
   20 Datatypes are now represented by the type 'SwigType' which has no
   21 public attributes.  Actually, if you look at it closely, 'SwigType' is
   22 really just an alias for 'void' and if you look at it even closer than
   23 that you will realize that it's nothing more than a string!
   24 
   25 The string encoding of types is described in more detail in the file
   26 Source/Swig/stype.c and is not so important here. What is important is
   27 the functions used to produce various types of output:
   28 
   29 SwigType_str(type,name = 0);
   30      This produces an exact C representation of the datatype with all
   31      qualifiers, arrays, references, and so forth.  name is an optional
   32      name that is given if you wanted to associate the type with a
   33      parameter name or something.
   34 
   35 SwigType_lstr(type,name = 0);
   36      This function takes a type and produces a C string containing
   37      a type suitable for assignment (appearing as an lvalue in an
   38      expression).  To do this, certain things such as 'const',
   39      arrays, and references are stripped away or converted into
   40      pointers.  
   41      
   42 SwigType_ltype(type);
   43      Returns a SwigType object corresponding to the type created
   44      by SwigType_lstr().
   45 
   46 SwigType_lcaststr(type,name);
   47      Produces a string casting a value 'name' from the real datatype
   48      to the assignable type created by SwigType_lstr().
   49 
   50 SwigType_rcaststr(type,name)
   51      Produces a string that casts a value 'name' from the type
   52      created by SwigType_lstr() to the real datatype.
   53     
   54 SwigType_manglestr(type)
   55      Produces the 'mangled' version of a datatype.
   56 
   57 
   58 Getting the 'type' code.  Most language modules still operate by
   59 looking at special integer type codes.  This interface is a little
   60 ragged and will probably go away at some point.  However, for now the
   61 following function can be used to get the type code:
   62 
   63    int SwigType_type(type)
   64 
   65 The codes are the same as the before, except that there are a few 
   66 special codes:
   67 
   68      T_STRING          - The 'char *' type and variations.
   69      T_POINTER         - Any pointer type (not char * though)
   70      T_REFERENCE       - Any C++ reference
   71      T_ARRAY           - Any array
   72      T_FUNCTION        - A function (this is usually an error).
   73 
   74 Because of the special codes, it is no longer necessary to have code like this:
   75 
   76      if ((t->is_pointer == 1) and (t->type == T_CHAR)) {
   77            ... get a string ...
   78      }
   79 
   80 Instead, just use the type code above like this:
   81 
   82      switch(SwigType_type(type)) {
   83      case T_STRING:
   84           ... get a string ...
   85           break;
   86      case T_POINTER:
   87           ... get a pointer ...
   88           break;
   89      }
   90 
   91 There are about 2-dozen type manipulation functions that could also be useful.
   92 See Source/Swig/swig.h and Source/Swig/stype.c.
   93 
   94 3. Parameter Lists
   95 ------------------
   96 
   97 The ParmList data structure is gone.  In reality, parameter lists are nothing more than
   98 a linked list of parameters.   The proper way to iterate over this list and get
   99 parameter values is as follows:
  100 
  101   ParmList *l;
  102   Parm *p;
  103 
  104   for (p = l; p; p = Getnext(p)) {
  105       SwigType *pt = Gettype(p);        /* Get parameter type */
  106       String   *pn = Getname(p);        /* Get parameter name */
  107       String   *value = Getvalue(p);    /* Get parameter value */
  108       ...
  109       do whatever
  110       ...
  111   }
  112 
  113 4. Typemaps
  114 -----------
  115 
  116 Typemaps more or less work.  However, the interface has changed slightly.  Instead of
  117 
  118      typemap_lookup("in","python",type,pname,"$source","$target",wrapper);
  119 
  120 the function is
  121 
  122      Swig_typemap_lookup("in",type,pname,"$source","$target",wrapper);
  123 
  124 There are a variety of other changes to typemaps (see CHANGES).
  125 
  126 5. Use of new types
  127 -------------------
  128 When possible, language modules should try to use the built in String,
  129 List, and Hash objects instead of C arrays or 'char *'.   This will probably require a
  130 detailed pass through the code with an eye towards cleanup.
  131 
  132 6. Miscellaneous
  133 ----------------
  134 Language modules no longer need to concern themselves with formatting the
  135 wrapper code they produce (provided you are using the special Wrapper object).
  136 The function Wrapper_print() passes everything through a pretty-printer that
  137 automatically performs indentation and tries to clean things up.   This especially
  138 works well when there are lots of typemaps.
  139 
  140