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.
459 lines
13 KiB
459 lines
13 KiB
4 years ago
|
/*
|
||
|
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
|