Make typemap fragments official - move the documentation in fragments.swg into Typemaps.html
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@11992 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
William S Fulton
parent
f9caea4b29
commit
bdea09ed83
4 changed files with 363 additions and 329 deletions
|
|
@ -1,238 +1,15 @@
|
|||
/*
|
||||
Fragments:
|
||||
==========
|
||||
Fragments
|
||||
=========
|
||||
See the "Typemap fragments" section in the documentation for understanding
|
||||
fragments. Below is some info on how fragments and automatic type
|
||||
specialization is used.
|
||||
|
||||
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.
|
||||
Macros that make the automatic generation of typemaps easier are provided.
|
||||
|
||||
Basics:
|
||||
=======
|
||||
Consider the following code:
|
||||
|
||||
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") {
|
||||
%fragment(SWIG_From_frag(bool), "header") {
|
||||
static PyObject*
|
||||
SWIG_From_dec(bool)(bool value)
|
||||
{
|
||||
|
|
@ -242,7 +19,7 @@
|
|||
}
|
||||
}
|
||||
|
||||
%typemap(out,fragment=SWIG_From_frag(bool)) bool {
|
||||
%typemap(out, fragment=SWIG_From_frag(bool)) bool {
|
||||
$result = SWIG_From(bool)($1));
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue