Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., python, -tcl, etc.). If found, SWIG will search the language specific directory first. This allows +tcl, etc.). If found, SWIG will search the language specific directory first. This allows for language-specific implementations of library files.
@@ -88,7 +88,7 @@ You can override the location of the SWIG library by setting the-This section describes library modules for manipulating low-level C arrays and pointers. +This section describes library modules for manipulating low-level C arrays and pointers. The primary use of these modules is in supporting C declarations that manipulate bare pointers such as int *, double *, or void *. The modules can be used to allocate memory, manufacture pointers, dereference memory, and wrap @@ -127,7 +127,7 @@ object is created using calloc(). In C++, new is used.
-Creates a new object of type type and returns a pointer to it. +Creates a new object of type type and returns a pointer to it. An initial value is set by copying it from value. In C, the object is created using calloc(). In C++, new is used.
>>> import example >>> c = example.new_intp() # Create an "int" for storing result ->>> example.add(3,4,c) # Call function +>>> example.add(3,4,c) # Call function >>> example.intp_value(c) # Dereference 7 >>> example.delete_intp(c) # Delete @@ -267,7 +267,7 @@ Now, in Python (using proxy classes)@@ -764,7 +764,7 @@ fixed-sized buffers. The problems (and perils) of using char * are well-known. However, SWIG is not in the business of enforcing morality. The modules in this section provide basic functionality -for manipulating raw C strings. +for manipulating raw C strings.>>> import example >>> c = example.intp() # Create an "int" for storing result ->>> example.add(3,4,c) # Call function +>>> example.add(3,4,c) # Call function >>> c.value() # Dereference 7@@ -369,7 +369,7 @@ should not correspond to any other name used in the interface file.-Here is an example of %array_functions(). Suppose you had a +Here is an example of %array_functions(). Suppose you had a function like this:
@@ -447,7 +447,7 @@ it can be transparently passed to any function that expects the pointer.-When combined with proxy classes, the %array_class() macro can be especially useful. +When combined with proxy classes, the %array_class() macro can be especially useful. For example:
@@ -633,7 +633,7 @@ Now, in a script: >>> a = malloc_int() >>> a '_000efa70_p_int' ->>> free_int(a) +>>> free_int(a) >>> b = malloc_intp() >>> b '_000efb20_p_p_int' @@ -654,7 +654,7 @@ Now, in a script:The cdata.i module defines functions for converting raw C data to and from strings -in the target language. The primary applications of this module would be packing/unpacking of +in the target language. The primary applications of this module would be packing/unpacking of binary data structures---for instance, if you needed to extract data from a buffer. The target language must support strings with embedded binary data in order for this to work. @@ -665,7 +665,7 @@ in order for this to work.
@@ -674,13 +674,13 @@ pointer.-Converts nbytes of data at ptr into a string. ptr can be any +Converts nbytes of data at ptr into a string. ptr can be any pointer.
-Copies all of the string data in s into the memory pointed to by -ptr. The string may contain embedded NULL bytes. The length of +Copies all of the string data in s into the memory pointed to by +ptr. The string may contain embedded NULL bytes. The length of the string is implicitly determined in the underlying wrapper code.
-One use of these functions is packing and unpacking data from memory. +One use of these functions is packing and unpacking data from memory. Here is a short example:
@@ -712,7 +712,7 @@ Python example: >>> memmove(c,b) >>> print c[4] 4 ->>> +>>>
then the SWIG generated wrappers will have a memory leak--the returned data will be copied -into a string object and the old contents ignored. +into a string object and the old contents ignored.
@@ -996,7 +996,7 @@ In the target language:
>>> get_packet() -'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' +'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88' >>>
>>> foo() -'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f"\xd3\x99\x14V\xec\x06\xea\xa2\x88' +'\xa9Y:\xf6\xd7\xe1\x87\xdbH;y\x97\x7f\xd3\x99\x14V\xec\x06\xea\xa2\x88' >>>
-This is the safest and most reliable way to return binary string data in +This is the safest and most reliable way to return binary string data in SWIG. If you have functions that conform to another prototype, you might consider wrapping them with a helper function. For example, if you had this:
@@ -1334,7 +1334,7 @@ void my_get_data(char **result, int *len) { SWIG modules currently support this library. -+A common problem that people encounter is that of classes/structures +containing a std::string. This can be overcome by defining a typemap. +For example: +
+ +
+%module example
+%include "std_string.i"
+
+%apply const std::string& {std::string* foo};
+
+struct my_struct
+{
+ std::string foo;
+};
+
++In the target language: +
+ ++x = my_struct(); +x.foo="Hello World"; # assign with string +print x.foo; # print as string ++
+ + +
This module only supports types std::string and const std::string &. Pointers and non-const references @@ -1473,7 +1509,7 @@ currently a subset of the real STL vector class.
-This library module is fully aware of C++ namespaces. If you use vectors with other names, +This library module is fully aware of C++ namespaces. If you use vectors with other names, make sure you include the appropriate using or typedef directives. For example:
@@ -1615,12 +1651,12 @@ if you want to make their head explode.-Note: This module is defined for all SWIG target languages. However argument conversion +Note: This module is defined for all SWIG target languages. However argument conversion details and the public API exposed to the interpreter vary.
-Note: std_vector.i was written by Luigi "The Amazing" Ballabio. +Note: std_vector.i was written by Luigi "The Amazing" Ballabio.
diff --git a/Doc/Manual/Perl5.html b/Doc/Manual/Perl5.html index e22ef2cbd..168dea396 100644 --- a/Doc/Manual/Perl5.html +++ b/Doc/Manual/Perl5.html @@ -67,6 +67,7 @@+# File : Makefile.PL use ExtUtils::MakeMaker; WriteMakefile( @@ -254,7 +255,7 @@ initializes your extension and starts the Perl interpreter. While, this may sound daunting, SWIG can do this for you automatically as follows : -+%module example %inline %{ @@ -308,7 +309,7 @@ To use the module, simply use the Perl use statement. If all goes well, you will be able to do this: -+$ perl use example; print example::fact(4),"\n"; @@ -319,7 +320,7 @@ print example::fact(4),"\n"; A common error received by first-time users is the following: -+use example; Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin @@ -338,7 +339,7 @@ you specified with the %module directive. A somewhat related, but slightly different error is this: -+use example; Can't find 'boot_example' symbol in ./example.so @@ -358,7 +359,7 @@ of your application when you linked the extension module. Another common error is the following: -+use example; Can't load './example.so' for module example: ./example.so: @@ -404,7 +405,7 @@ If the foo library is compiled as a shared library, you might get the f error when you try to use your module: -+use example; Can't load './example.so' for module example: libfoo.so: cannot open shared object file: @@ -691,7 +692,7 @@ the wrapper file. To run your new Perl extension, simply run Perl and use the use command as normal. For example : -+DOS > perl use example; $a = example::fact(4); @@ -725,7 +726,7 @@ C functions are converted into new Perl built-in commands (or subroutines). For example: -+%module example int fact(int a); ... @@ -735,7 +736,7 @@ int fact(int a); Now, in Perl: -+@@ -749,7 +750,7 @@ variable mechanism. SWIG generates a pair of functions that intercept read/write operations and attaches them to a Perl variable with the same name as the C global variable. Thus, an interface like this -use example; $a = &example::fact(2);+%module example; ... double Spam; @@ -759,7 +760,7 @@ double Spam;is accessed as follows :
-+use example; print $example::Spam,"\n"; $example::Spam = $example::Spam + 4 @@ -829,7 +830,7 @@ Constants are wrapped as read-only Perl variables. For example: In Perl: -+use example; print $example::FOO,"\n"; # OK @@ -854,7 +855,7 @@ Matrix *new_Matrix(int n, int m); The module returns a value generated as follows: -+@@ -868,7 +869,7 @@ generated. To check to see if a value is the NULL pointer, use the defined() command : -$ptr = new_Matrix(int n, int m); # Save pointer return result bless $ptr, "p_Matrix"; # Bless it as a pointer to Matrix+if (defined($ptr)) { print "Not a NULL pointer."; } else { @@ -893,7 +894,7 @@ pointers. The correct method to check equality of C pointers is to dereference them as follows : -+if ($$a == $$b) { print "a and b point to the same thing in C"; } else { @@ -980,7 +981,7 @@ void Vector_z_set(Vector *obj, double z) These functions are then used to access structure data from Perl as follows: -+$v = example::new_Vector(); print example::Vector_x_get($v),"\n"; # Get x component example::Vector_x_set($v,7.8); # Change x component @@ -1123,7 +1124,7 @@ void List_print(List *l); In Perl, these functions are used in a straightforward manner: -+use example; $l = example::new_List(); example::List_insert($l,"Ale"); @@ -1211,7 +1212,7 @@ public: Now, in Perl, the methods are accessed as follows: -+use example; example::foo_i(3); @@ -1245,7 +1246,7 @@ Complex operator+(Complex &, Complex &); Now, in Perl, you can do this: -+use example; $a = example::new_Complex(2,3); @@ -1267,7 +1268,7 @@ a single Perl module. The name of the module is determined by the %module directive. To use the module, do the following : -+% perl5 use example; # load the example module print example::fact(4),"\n" # Call a function in it @@ -1319,7 +1320,7 @@ all of the functions in that module will be installed into the package `Foo.' For example : -+@@ -1371,7 +1372,7 @@ int sub(int *INPUT, int *INPUT); In Perl, this allows you to pass simple values. For example: -use example; # Load the module like before print Foo::fact(4),"\n"; # Call a function in package FooBar+$a = example::add(3,4); print "$a\n"; @@ -1433,7 +1434,7 @@ void negate(int *INOUT); In Perl, a mutated parameter shows up as a return value. For example: -+$a = example::negate(3); print "$a\n"; @@ -1472,7 +1473,7 @@ int send_message(char *text, int *success); When used in Perl, the function will return multiple values. -+($bytes, $success) = example::send_message("Hello World");@@ -1506,7 +1507,7 @@ void get_dimensions(Matrix *m, int *rows, *columns); Now, in Perl: -+($r,$c) = example::get_dimensions($m);@@ -1530,7 +1531,7 @@ void add(int x, int y, int *REFERENCE); In Perl: -+use example; $c = 0.0; @@ -1763,7 +1764,7 @@ The $input variable is the input object (usually a SV *). When this example is used in Perl5, it will operate as follows : -+use example; $n = example::fact(6); print "$n\n"; @@ -1782,7 +1783,7 @@ applies to int and qualified variations such as const int. In the typemap system follows typedef declarations. For example: -+%typemap(in) int n { $1 = (int) SvIV($input); @@ -1805,7 +1806,7 @@ type int. Typemaps can also be defined for groups of consecutive arguments. For example: -+%typemap(in) (char *str, unsigned len) { $1 = SvPV($input,$2); @@ -1821,7 +1822,7 @@ Perl object. This allows the function to be used like this (notice how the leng parameter is ommitted): -+example::count("e","Hello World"); 1 @@ -1841,7 +1842,7 @@ like this: -+%typemap(out) int { $result = sv_newmortal(); @@ -2167,7 +2168,7 @@ When this module is compiled, the wrapped C functions can be used in a Perl script as follows : -+use argv; @a = ("Dave", "Mike", "John", "Mary"); # Create an array of strings argv::print_args(\@a); # Pass it to our C function @@ -2253,7 +2254,7 @@ to return results. This shows up an array in Perl. For example : -+@r = multout(7,13); print "multout(7,13) = @r\n"; ($x,$y) = multout(7,13); @@ -2341,7 +2342,7 @@ void add(double a, double b, double *c) { A common misinterpretation of this function is the following Perl script : -+# Perl script $a = 3.5; $b = 7.5; @@ -2378,7 +2379,7 @@ To make this work with a reference, you can use a typemap such as this: Now, if you place this before the add function, you can do this : -+$a = 3.5; $b = 7.5; $c = 0.0; @@ -2543,7 +2544,7 @@ However, when proxy classes are enabled, these accessor functions are wrapped inside a Perl class like this: -+package example::Vector; @ISA = qw( example ); %OWNER = (); @@ -2609,7 +2610,7 @@ internally and described shortly. To use our new proxy class we can simply do the following: -+# Perl code using Vector class $v = new Vector(2,3,4); $w = Vector->new(-1,-2,-3); @@ -2694,7 +2695,7 @@ by simply deleting the object from the %OWNER hash. This is done using the DISOWN method. -+# Perl code to change ownership of an object $v = new Vector(x,y,z); $v->DISOWN(); @@ -2704,7 +2705,7 @@ $v->DISOWN(); To acquire ownership of an object, the ACQUIRE method can be used. -+# Given Perl ownership of a file $u = Vector_get($v); $u->ACQUIRE(); @@ -2741,7 +2742,7 @@ these correctly, we use the %BLESSEDMEMBERS hash which would look like this (along with some supporting code) : -+package Particle; ... %BLESSEDMEMBERS = ( @@ -2763,7 +2764,7 @@ unmodified. This implementation allows us to operate on nested structures as follows : -+# Perl access of nested structure $p = new Particle(); $p->{f}->{x} = 0.0; @@ -2789,7 +2790,7 @@ of tied hash tables. This is done by creating a Perl function like this : -+sub dot_product { my @args = @_; $args[0] = tied(%{$args[0]}); # Get the real pointer values @@ -2848,7 +2849,7 @@ public: The resulting, Perl wrapper class will create the following code : -+Package Shape; @ISA = (shapes); ... @@ -2889,7 +2890,7 @@ It works like all the other %feature direc Here is a simple example showing how to add some Perl debug code to the constructor: -++/* Let's make the constructor of the class Square more verbose */ %feature("shadow") Square(double w) %{ @@ -2908,6 +2909,57 @@ public: };26.10 Adding additional Perl code
+ + ++If writing support code in C isn't enough, it is also possible to write code in +Perl. This code gets inserted in to the .pm file created by SWIG. One +use of Perl code might be to supply a high-level interface to certain functions. +For example: +
+ +++ ++void set_transform(Image *im, double x[4][4]); + +... +/* Rewrite the high level interface to set_transform */ +%perlcode %{ +sub set_transform +{ + my ($im, $x) = @_; + my $a = new_mat44(); + for (my $i = 0; $i < 4, $i++) + { + for (my $j = 0; $j < 4, $j++) + { + mat44_set($a, $i, $j, $x->[i][j]) + } + } + example.set_transform($im, $a); + free_mat44($a); +} +%} +++In this example, set_transform() provides a high-level Perl interface built on top of +low-level helper functions. For example, this code now seems to work: +
+ ++++my $a = + [[1,0,0,0], + [0,1,0,0], + [0,0,1,0], + [0,0,0,1]]; +set_transform($im, $a); ++