blob: 6d3e202239fd396b396d8cf621e244289e80de13 [file] [log] [blame]
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.
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
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:
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);
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;
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
* ----------------------------------------------------------------------------- */
#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_MIN (-LLONG_MAX - 1LL)
# 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
#ifndef WCHAR_MAX
# define WCHAR_MAX 65535
%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
%fragment("<stdlib.h>","header") %{
#include <stdlib.h>
#ifdef _MSC_VER
# ifndef strtoull
# define strtoull _strtoui64
# endif
# ifndef strtoll
# define strtoll _strtoi64
# endif
/* -----------------------------------------------------------------------------
* special macros for fragments
* ----------------------------------------------------------------------------- */
/* Macros to derive numeric types */
%define %numeric_type_from(Type, Base)
fragment=SWIG_From_frag(Base)) {
SWIG_From_dec(Type)(Type value)
return SWIG_From(Base)(value);
%define %numeric_type_asval(Type, Base, Frag, OverflowCond)
fragment=SWIG_AsVal_frag(Base)) {
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;
#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)
/* 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)
/* 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)
/* Macros for missing fragments */
%define %ensure_fragment(Fragment)
%fragment(`Fragment`,"header") {
%#error "Swig language implementation must provide the Fragment fragment"
%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"