You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
458 lines
13 KiB
458 lines
13 KiB
/* |
|
Fragments: |
|
========== |
|
|
|
Second to typemaps, fragments are one the most powerful and |
|
dangerous swig features. So, if you are starting to read about them, |
|
make sure you read all of this document. |
|
|
|
Basics: |
|
======= |
|
|
|
Fragments provide a way to include or generate code into "on-demand" |
|
as the typemaps could require. |
|
|
|
For example, if you have a very long typemap |
|
|
|
%typemap(in) MyClass * { |
|
MyClass *value = 0; |
|
|
|
<very long typemap> |
|
.... |
|
value = somewhere_converted_from_input_object_here($input); |
|
... |
|
<very long typemap> |
|
|
|
$result = value; |
|
} |
|
|
|
very soon you will discover yourself copying the same long |
|
conversion code in several typemaps, such as varin, directorout, |
|
etc. Also, you will discover that swig copes verbatim the same very |
|
long conversion code for every argument that requires it, making the |
|
code very large too. |
|
|
|
To eliminate this automatic or manual code copying, we define a |
|
fragment that includes the common conversion code: |
|
|
|
%fragment("AsMyClass","header") { |
|
MyClass *AsMyClass(PyObject *obj) { |
|
MyClass *value = 0; |
|
<very long conversion> |
|
.... |
|
value = somewhere_converted_from_input_object_here(obj); |
|
... |
|
<very long conversion> |
|
|
|
return value; |
|
} |
|
} |
|
|
|
%typemap(in,fragment="AsMyClass") MyClass * { |
|
$result = AsMyClass($input); |
|
} |
|
|
|
%typemap(varin,fragment="AsMyClass") MyClass * { |
|
$result = AsMyClass($input); |
|
} |
|
|
|
When the 'in' or 'varin' typemaps for MyClass are invoked, the |
|
fragment "AsMyClass" is added to the "header" section, and then the |
|
typemap code is emitted. Hence, the method AsMyClass will be |
|
included in the wrapping code and it will be available at the time |
|
the typemap is applied. |
|
|
|
To define a fragment then you need a name, a section where it goes, |
|
and the code. Usually the section refers to the "header" part, and |
|
both string and braces forms are accepted, ie: |
|
|
|
%fragment("my_name","header") { ... } |
|
%fragment("my_name","header") "..."; |
|
|
|
To ensure all the fragment/typemap engine works as expected, there |
|
are some rules that fragments follow: |
|
|
|
1.- A fragment is added to the wrapping code only once, ie, for the |
|
method: |
|
|
|
int foo(MyClass *a, MyClass *b); |
|
|
|
the wrapped code will look as much as: |
|
|
|
MyClass *AsMyClass(PyObject *obj) { |
|
..... |
|
} |
|
|
|
int _wrap_foo(...) { |
|
.... |
|
arg1 = AsMyClass(obj1); |
|
arg2 = AsMyClass(obj2); |
|
... |
|
result = foo(arg1, arg2); |
|
} |
|
|
|
|
|
even when there will be duplicated typemap to process 'a' and |
|
'b', the 'AsMyClass' method will be defined only once. |
|
|
|
|
|
2.- A fragment can only defined once, and the first definition |
|
is the only one taking in account. All other definitions of the |
|
same fragments are silently ignored. For example, you can have |
|
|
|
|
|
%fragment("AsMyClass","header") { <definition 1> } |
|
.... |
|
%fragment("AsMyClass","header") { <definition 2> } |
|
|
|
and then only the first definition is considered. In this way |
|
you can change the 'system' fragments by including yours first. |
|
|
|
Note that this behavior is opposite to the typemaps, where the |
|
last typemap applied or defined prevails. Fragment follows the |
|
first-in-first-out convention since they are intended to be |
|
"global", while typemaps intend to be "locally" specialized. |
|
|
|
3.- Fragments names can not contain commas. |
|
|
|
|
|
A fragment can include one or more additional fragments, for example: |
|
|
|
%fragment("<limits.h>", "header") { |
|
#include <limits.h> |
|
} |
|
|
|
|
|
%fragment("AsMyClass", "header", fragment="<limits.h>") { |
|
MyClass *AsMyClass(PyObject *obj) { |
|
MyClass *value = 0; |
|
int ival = somewhere_converted_from_input_object_here(obj) |
|
... |
|
if (ival < CHAR_MIN) { |
|
value = something_from_ival(ival); |
|
} else { |
|
... |
|
} |
|
... |
|
return value; |
|
} |
|
} |
|
|
|
in this case, when the "AsMyClass" fragment is emitted, it also |
|
trigger the inclusion of the "<limits.h>" fragment. |
|
|
|
You can add as many fragments as you want, for example |
|
|
|
%fragment("bigfragment","header", fragment="frag1", fragment="frag2", fragment="frag3") ""; |
|
|
|
here, when the "bigfragment" is included, the three fragments "frag1", |
|
"frag2" and "frag3" are included. Note that as "bigframent" is defined |
|
empty, "", it does not add any code by itself, buy only trigger the |
|
inclusion of the other fragments. |
|
|
|
In a typemap you can also include more than one fragment, but since the |
|
syntax is different, you need to specify them in a 'comma separated' |
|
list, for example, considering the previous example: |
|
|
|
%typemap(in,fragment="frag1,frag2,frag3") {...} |
|
|
|
is equivalent to |
|
|
|
%typemap(in,fragment="bigfragment") {...} |
|
|
|
|
|
Finally, you can force the inclusion of a fragment at any moment as follow: |
|
|
|
%fragment("bigfragment"); |
|
|
|
which is very useful inside a template class, for example. |
|
|
|
|
|
Fragment type specialization |
|
============================ |
|
|
|
Fragments can be "type specialized". The syntax is as follows |
|
|
|
%fragment("name","header") { a type independent fragment } |
|
%fragment("name" {Type}, "header") { a type dependent fragment } |
|
|
|
and they can also, as typemaps, be used inside templates, for exampe: |
|
|
|
template <class T> |
|
struct A { |
|
%fragment("incode"{A<T>},"header") { |
|
'incode' specialized fragment |
|
} |
|
|
|
%typemap(in,fragment="incode"{A<T>}) { |
|
here we use the 'type specialized' |
|
fragment "incode"{A<T>} |
|
} |
|
}; |
|
|
|
which could seems a not much interesting feature, but is |
|
fundamental for automatic typemap and template specialization. |
|
|
|
|
|
Fragments and automatic typemap specialization: |
|
=============================================== |
|
|
|
Since fragments can be type specialized, they can be elegantly used |
|
to specialized typemaps . |
|
|
|
For example, if you have something like: |
|
|
|
%fragment("incode"{float}, "header") { |
|
float in_method_float(PyObject *obj) { |
|
... |
|
} |
|
} |
|
|
|
%fragment("incode"{long}, "header") { |
|
float in_method_long(PyObject *obj) { |
|
... |
|
} |
|
} |
|
|
|
%define %my_typemaps(Type) |
|
%typemaps(in,fragment="incode"{Type}) { |
|
value = in_method_##Type(obj); |
|
} |
|
%enddef |
|
|
|
%my_typemaps(float); |
|
%my_typemaps(long); |
|
|
|
then the proper "incode"{float,double} fragment will be included, |
|
and the proper in_method_{float,double} will be called. |
|
|
|
Since this is a recurrent fragment use, we provide a couple of |
|
macros that make the automatic generation of typemaps easier: |
|
|
|
|
|
Consider for example the following code: |
|
|
|
%fragment(SWIG_From_frag(bool),"header") { |
|
static PyObject* |
|
SWIG_From_dec(bool)(bool value) |
|
{ |
|
PyObject *obj = value ? Py_True : Py_False; |
|
Py_INCREF(obj); |
|
return obj; |
|
} |
|
} |
|
|
|
%typemap(out,fragment=SWIG_From_frag(bool)) bool { |
|
$result = SWIG_From(bool)($1)); |
|
} |
|
|
|
Here the macros |
|
|
|
SWIG_From_frag => fragment |
|
SWIG_From_dec => declaration |
|
SWIG_From => call |
|
|
|
allow you to define/include a fragment, and declare and call the |
|
'from-bool' method as needed. In the simpler case, these macros |
|
just return something like |
|
|
|
SWIG_From_frag(bool) => "SWIG_From_bool" |
|
SWIG_From_dec(bool) => SWIG_From_bool |
|
SWIG_From(bool) => SWIG_From_bool |
|
|
|
But they are specialized for the different languages requirements, |
|
such as perl or tcl that requires passing the interpreter pointer, |
|
and also they can manage C++ ugly types, for example: |
|
|
|
SWIG_From_frag(std::complex<double>) => "SWIG_From_std_complex_Sl_double_Sg_" |
|
SWIG_From_dec(std::complex<double>) => SWIG_From_std_complex_Sl_double_Sg_ |
|
SWIG_From(std::complex<double>) => SWIG_From_std_complex_Sl_double_Sg_ |
|
|
|
|
|
Hence, to declare methods to use with typemaps, always use the |
|
SWIG_From* macros. In the same way, the SWIG_AsVal* and SWIG_AsPtr* |
|
set of macros are provided. |
|
|
|
*/ |
|
|
|
|
|
/* ----------------------------------------------------------------------------- |
|
* Define the basic macros to 'normalize' the type fragments |
|
* ----------------------------------------------------------------------------- */ |
|
|
|
#ifndef SWIG_AS_DECL_ARGS |
|
#define SWIG_AS_DECL_ARGS |
|
#endif |
|
|
|
#ifndef SWIG_FROM_DECL_ARGS |
|
#define SWIG_FROM_DECL_ARGS |
|
#endif |
|
|
|
#ifndef SWIG_AS_CALL_ARGS |
|
#define SWIG_AS_CALL_ARGS |
|
#endif |
|
|
|
#ifndef SWIG_FROM_CALL_ARGS |
|
#define SWIG_FROM_CALL_ARGS |
|
#endif |
|
|
|
#define %fragment_name(Name, Type...) %string_name(Name) "_" {Type} |
|
|
|
#define SWIG_Traits_frag(Type...) %fragment_name(Traits, Type) |
|
#define SWIG_AsPtr_frag(Type...) %fragment_name(AsPtr, Type) |
|
#define SWIG_AsVal_frag(Type...) %fragment_name(AsVal, Type) |
|
#define SWIG_From_frag(Type...) %fragment_name(From, Type) |
|
|
|
#define SWIG_AsVal_name(Type...) %symbol_name(AsVal, Type) |
|
#define SWIG_AsPtr_name(Type...) %symbol_name(AsPtr, Type) |
|
#define SWIG_From_name(Type...) %symbol_name(From, Type) |
|
|
|
#define SWIG_AsVal_dec(Type...) SWIG_AsVal_name(Type) SWIG_AS_DECL_ARGS |
|
#define SWIG_AsPtr_dec(Type...) SWIG_AsPtr_name(Type) SWIG_AS_DECL_ARGS |
|
#define SWIG_From_dec(Type...) SWIG_From_name(Type) SWIG_FROM_DECL_ARGS |
|
|
|
#define SWIG_AsVal(Type...) SWIG_AsVal_name(Type) SWIG_AS_CALL_ARGS |
|
#define SWIG_AsPtr(Type...) SWIG_AsPtr_name(Type) SWIG_AS_CALL_ARGS |
|
#define SWIG_From(Type...) SWIG_From_name(Type) SWIG_FROM_CALL_ARGS |
|
|
|
/* ------------------------------------------------------------ |
|
* common fragments |
|
* ------------------------------------------------------------ */ |
|
|
|
/* Default compiler options for gcc allow long_long but not LLONG_MAX. |
|
* Define SWIG_NO_LLONG_MAX if this added limits support is not wanted. */ |
|
%fragment("<limits.h>","header") %{ |
|
#include <limits.h> |
|
#if !defined(SWIG_NO_LLONG_MAX) |
|
# if !defined(LLONG_MAX) && defined(__GNUC__) && defined (__LONG_LONG_MAX__) |
|
# define LLONG_MAX __LONG_LONG_MAX__ |
|
# define LLONG_MIN (-LLONG_MAX - 1LL) |
|
# define ULLONG_MAX (LLONG_MAX * 2ULL + 1ULL) |
|
# endif |
|
#endif |
|
%} |
|
|
|
%fragment("<math.h>","header") %{ |
|
#include <math.h> |
|
%} |
|
|
|
%fragment("<wchar.h>","header") %{ |
|
#include <wchar.h> |
|
#include <limits.h> |
|
#ifndef WCHAR_MIN |
|
# define WCHAR_MIN 0 |
|
#endif |
|
#ifndef WCHAR_MAX |
|
# define WCHAR_MAX 65535 |
|
#endif |
|
%} |
|
|
|
%fragment("<float.h>","header") %{ |
|
#include <float.h> |
|
%} |
|
|
|
%fragment("<stdio.h>","header") %{ |
|
#include <stdio.h> |
|
#if defined(_MSC_VER) || defined(__BORLANDC__) || defined(_WATCOM) |
|
# ifndef snprintf |
|
# define snprintf _snprintf |
|
# endif |
|
#endif |
|
%} |
|
|
|
%fragment("<stdlib.h>","header") %{ |
|
#include <stdlib.h> |
|
#ifdef _MSC_VER |
|
# ifndef strtoull |
|
# define strtoull _strtoui64 |
|
# endif |
|
# ifndef strtoll |
|
# define strtoll _strtoi64 |
|
# endif |
|
#endif |
|
%} |
|
|
|
/* ----------------------------------------------------------------------------- |
|
* special macros for fragments |
|
* ----------------------------------------------------------------------------- */ |
|
|
|
/* Macros to derive numeric types */ |
|
|
|
%define %numeric_type_from(Type, Base) |
|
%fragment(SWIG_From_frag(Type),"header", |
|
fragment=SWIG_From_frag(Base)) { |
|
SWIGINTERNINLINE SWIG_Object |
|
SWIG_From_dec(Type)(Type value) |
|
{ |
|
return SWIG_From(Base)(value); |
|
} |
|
} |
|
%enddef |
|
|
|
%define %numeric_type_asval(Type, Base, Frag, OverflowCond) |
|
%fragment(SWIG_AsVal_frag(Type),"header", |
|
fragment=Frag, |
|
fragment=SWIG_AsVal_frag(Base)) { |
|
SWIGINTERN int |
|
SWIG_AsVal_dec(Type)(SWIG_Object obj, Type *val) |
|
{ |
|
Base v; |
|
int res = SWIG_AsVal(Base)(obj, &v); |
|
if (SWIG_IsOK(res)) { |
|
if (OverflowCond) { |
|
return SWIG_OverflowError; |
|
} else { |
|
if (val) *val = %numeric_cast(v, Type); |
|
} |
|
} |
|
return res; |
|
} |
|
} |
|
%enddef |
|
|
|
#define %numeric_signed_type_asval(Type, Base, Frag, Min, Max) \ |
|
%numeric_type_asval(Type, Base, Frag, (v < Min || v > Max)) |
|
|
|
#define %numeric_unsigned_type_asval(Type, Base, Frag, Max) \ |
|
%numeric_type_asval(Type, Base, Frag, (v > Max)) |
|
|
|
|
|
/* Macro for 'signed long' derived types */ |
|
|
|
%define %numeric_slong(Type, Frag, Min, Max) |
|
%numeric_type_from(Type, long) |
|
%numeric_signed_type_asval(Type, long, Frag , Min, Max) |
|
%enddef |
|
|
|
/* Macro for 'unsigned long' derived types */ |
|
|
|
%define %numeric_ulong(Type, Frag, Max) |
|
%numeric_type_from(Type, unsigned long) |
|
%numeric_unsigned_type_asval(Type, unsigned long, Frag, Max) |
|
%enddef |
|
|
|
|
|
/* Macro for 'double' derived types */ |
|
|
|
%define %numeric_double(Type, Frag, Min, Max) |
|
%numeric_type_from(Type, double) |
|
%numeric_signed_type_asval(Type, double, Frag , Min, Max) |
|
%enddef |
|
|
|
|
|
/* Macros for missing fragments */ |
|
|
|
%define %ensure_fragment(Fragment) |
|
%fragment(`Fragment`,"header") { |
|
%#error "Swig language implementation must provide the Fragment fragment" |
|
} |
|
%enddef |
|
|
|
%define %ensure_type_fragments(Type) |
|
%fragment(SWIG_From_frag(Type),"header") { |
|
%#error "Swig language implementation must provide a SWIG_From_frag(Type) fragment" |
|
} |
|
%fragment(SWIG_AsVal_frag(Type),"header") { |
|
%#error "Swig language implementation must provide a SWIG_AsVal_frag(Type) fragment" |
|
} |
|
%enddef
|
|
|