jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

adding several docs patches

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7949 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Marcelo Matus 2005-12-08 08:52:39 +00:00
commit 91d4692367
3 changed files with 159 additions and 71 deletions
Download patch file Download diff file Expand all files Collapse all files

40
Doc/Manual/Library.html
View file

@ -996,7 +996,7 @@ In the target language:
<div class="targetlang"> <div class="targetlang">
<pre> <pre>
&gt;&gt;&gt; get_packet() &gt;&gt;&gt; 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'
&gt;&gt;&gt; &gt;&gt;&gt;
</pre> </pre>
</div> </div>
@ -1295,7 +1295,7 @@ In the target language:
<div class="targetlang"> <div class="targetlang">
<pre> <pre>
&gt;&gt;&gt; foo() &gt;&gt;&gt; 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'
&gt;&gt;&gt; &gt;&gt;&gt;
</pre> </pre>
</div> </div>
@ -1412,6 +1412,42 @@ bar("Hello World"); # Pass string as std::string
</pre> </pre>
</div> </div>
<p>
A common problem that people encounter is that of classes/structures
containing a <tt>std::string</tt>. This can be overcome by defining a typemap.
For example:
</p>
<div class="code">
<pre>
%module example
%include "std_string.i"
%apply const std::string& {std::string* foo};
struct my_struct
{
std::string foo;
};
</pre>
</div>
<p>
In the target language:
</p>
<div class="targetlang">
<pre>
x = my_struct();
x.foo="Hello World"; # assign with string
print x.foo; # print as string
</pre>
</div>
<p>
</pre>
</div>
<p> <p>
This module only supports types <tt>std::string</tt> and This module only supports types <tt>std::string</tt> and
<tt>const std::string &amp;</tt>. Pointers and non-const references <tt>const std::string &amp;</tt>. Pointers and non-const references

142
Doc/Manual/Perl5.html
View file

@ -67,6 +67,7 @@
<li><a href="#Perl5_nn45">Inheritance</a> <li><a href="#Perl5_nn45">Inheritance</a>
<li><a href="#Perl5_nn46">Modifying the proxy methods</a> <li><a href="#Perl5_nn46">Modifying the proxy methods</a>
</ul> </ul>
<li><a href="#Perl5_nn47">Adding additional Perl code</a>
</ul> </ul>
</div> </div>
<!-- INDEX --> <!-- INDEX -->
@ -205,7 +206,7 @@ It is also possible to use Perl to build dynamically loadable modules
for you using the MakeMaker utility. To do this, write a Perl for you using the MakeMaker utility. To do this, write a Perl
script such as the following :</p> script such as the following :</p>
<div class="code"><pre> <div class="targetlang"><pre>
# File : Makefile.PL # File : Makefile.PL
use ExtUtils::MakeMaker; use ExtUtils::MakeMaker;
WriteMakefile( 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 this may sound daunting, SWIG can do this for you automatically as
follows :</p> follows :</p>
<div class="code"><pre> <div class="targetlang"><pre>
%module example %module example
%inline %{ %inline %{
@ -308,7 +309,7 @@ To use the module, simply use the Perl <tt>use</tt> statement. If
all goes well, you will be able to do this: all goes well, you will be able to do this:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
$ perl $ perl
use example; use example;
print example::fact(4),"\n"; 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: A common error received by first-time users is the following:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin Can't locate example.pm in @INC (@INC contains: /usr/lib/perl5/5.00503/i386-lin
@ -338,7 +339,7 @@ you specified with the <tt>%module</tt> directive.
A somewhat related, but slightly different error is this: A somewhat related, but slightly different error is this:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
Can't find 'boot_example' symbol in ./example.so 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: Another common error is the following:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
Can't load './example.so' for module example: ./example.so: Can't load './example.so' for module example: ./example.so:
@ -404,7 +405,7 @@ If the <tt>foo</tt> library is compiled as a shared library, you might get the f
error when you try to use your module: error when you try to use your module:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
Can't load './example.so' for module example: libfoo.so: cannot open shared object file: 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 : use the use command as normal. For example :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
DOS &gt; perl DOS &gt; perl
use example; use example;
$a = example::fact(4); $a = example::fact(4);
@ -725,7 +726,7 @@ C functions are converted into new Perl built-in commands (or
subroutines). For example: subroutines). For example:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
%module example %module example
int fact(int a); int fact(int a);
... ...
@ -735,7 +736,7 @@ int fact(int a);
Now, in Perl: Now, in Perl:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
use example; use example;
$a = &amp;example::fact(2); $a = &amp;example::fact(2);
</pre></div> </pre></div>
@ -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 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 </p> the same name as the C global variable. Thus, an interface like this </p>
<div class="code"><pre> <div class="targetlang"><pre>
%module example; %module example;
... ...
double Spam; double Spam;
@ -759,7 +760,7 @@ double Spam;
<p> <p>
is accessed as follows :</p> is accessed as follows :</p>
<div class="code"><pre> <div class="targetlang"><pre>
use example; use example;
print $example::Spam,"\n"; print $example::Spam,"\n";
$example::Spam = $example::Spam + 4 $example::Spam = $example::Spam + 4
@ -829,7 +830,7 @@ Constants are wrapped as read-only Perl variables. For example:
In Perl: In Perl:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
print $example::FOO,"\n"; # OK print $example::FOO,"\n"; # OK
@ -854,7 +855,7 @@ Matrix *new_Matrix(int n, int m);
The module returns a value generated as follows: The module returns a value generated as follows:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
$ptr = new_Matrix(int n, int m); # Save pointer return result $ptr = new_Matrix(int n, int m); # Save pointer return result
bless $ptr, "p_Matrix"; # Bless it as a pointer to Matrix bless $ptr, "p_Matrix"; # Bless it as a pointer to Matrix
</pre></div> </pre></div>
@ -868,7 +869,7 @@ generated.</p>
To check to see if a value is the NULL pointer, use the To check to see if a value is the NULL pointer, use the
<tt>defined()</tt> command :</p> <tt>defined()</tt> command :</p>
<div class="code"><pre> <div class="targetlang"><pre>
if (defined($ptr)) { if (defined($ptr)) {
print "Not a NULL pointer."; print "Not a NULL pointer.";
} else { } else {
@ -893,7 +894,7 @@ pointers. The correct method to check equality of C pointers is to
dereference them as follows : dereference them as follows :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
if ($$a == $$b) { if ($$a == $$b) {
print "a and b point to the same thing in C"; print "a and b point to the same thing in C";
} else { } 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: These functions are then used to access structure data from Perl as follows:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
$v = example::new_Vector(); $v = example::new_Vector();
print example::Vector_x_get($v),"\n"; # Get x component print example::Vector_x_get($v),"\n"; # Get x component
example::Vector_x_set($v,7.8); # Change 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: In Perl, these functions are used in a straightforward manner:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
use example; use example;
$l = example::new_List(); $l = example::new_List();
example::List_insert($l,"Ale"); example::List_insert($l,"Ale");
@ -1211,7 +1212,7 @@ public:
Now, in Perl, the methods are accessed as follows: Now, in Perl, the methods are accessed as follows:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
example::foo_i(3); example::foo_i(3);
@ -1245,7 +1246,7 @@ Complex operator+(Complex &amp;, Complex &amp;);
Now, in Perl, you can do this: Now, in Perl, you can do this:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
$a = example::new_Complex(2,3); $a = example::new_Complex(2,3);
@ -1267,7 +1268,7 @@ a single Perl module. The name of the module is determined by the
<tt>%module</tt> directive. To use the module, do the following : <tt>%module</tt> directive. To use the module, do the following :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
% perl5 % perl5
use example; # load the example module use example; # load the example module
print example::fact(4),"\n" # Call a function in it 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
`<tt>Foo</tt>.' For example : `<tt>Foo</tt>.' For example :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
use example; # Load the module like before use example; # Load the module like before
print Foo::fact(4),"\n"; # Call a function in package FooBar print Foo::fact(4),"\n"; # Call a function in package FooBar
</pre></div> </pre></div>
@ -1371,7 +1372,7 @@ int sub(int *INPUT, int *INPUT);
In Perl, this allows you to pass simple values. For example: In Perl, this allows you to pass simple values. For example:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
$a = example::add(3,4); $a = example::add(3,4);
print "$a\n"; print "$a\n";
@ -1433,7 +1434,7 @@ void negate(int *INOUT);
In Perl, a mutated parameter shows up as a return value. For example: In Perl, a mutated parameter shows up as a return value. For example:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
$a = example::negate(3); $a = example::negate(3);
print "$a\n"; print "$a\n";
@ -1472,7 +1473,7 @@ int send_message(char *text, int *success);
When used in Perl, the function will return multiple values. When used in Perl, the function will return multiple values.
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
($bytes, $success) = example::send_message("Hello World"); ($bytes, $success) = example::send_message("Hello World");
</pre> </pre>
@ -1506,7 +1507,7 @@ void get_dimensions(Matrix *m, int *rows, *columns);
Now, in Perl: Now, in Perl:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
($r,$c) = example::get_dimensions($m); ($r,$c) = example::get_dimensions($m);
</pre> </pre>
@ -1530,7 +1531,7 @@ void add(int x, int y, int *REFERENCE);
In Perl: In Perl:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
use example; use example;
$c = 0.0; $c = 0.0;
@ -1763,7 +1764,7 @@ The <tt>$input</tt> variable is the input object (usually a <tt>SV *</tt>).
When this example is used in Perl5, it will operate as follows : When this example is used in Perl5, it will operate as follows :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
use example; use example;
$n = example::fact(6); $n = example::fact(6);
print "$n\n"; print "$n\n";
@ -1782,7 +1783,7 @@ applies to <tt>int</tt> and qualified variations such as <tt>const int</tt>. In
the typemap system follows <tt>typedef</tt> declarations. For example: the typemap system follows <tt>typedef</tt> declarations. For example:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
%typemap(in) int n { %typemap(in) int n {
$1 = (int) SvIV($input); $1 = (int) SvIV($input);
@ -1805,7 +1806,7 @@ type <tt>int</tt>.
Typemaps can also be defined for groups of consecutive arguments. For example: Typemaps can also be defined for groups of consecutive arguments. For example:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
%typemap(in) (char *str, unsigned len) { %typemap(in) (char *str, unsigned len) {
$1 = SvPV($input,$2); $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): parameter is ommitted):
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
example::count("e","Hello World"); example::count("e","Hello World");
1 1
@ -1841,7 +1842,7 @@ like this:
</p> </p>
<div class="code"> <div class="targetlang">
<pre> <pre>
%typemap(out) int { %typemap(out) int {
$result = sv_newmortal(); $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 : Perl script as follows :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
use argv; use argv;
@a = ("Dave", "Mike", "John", "Mary"); # Create an array of strings @a = ("Dave", "Mike", "John", "Mary"); # Create an array of strings
argv::print_args(\@a); # Pass it to our C function 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 : For example :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
@r = multout(7,13); @r = multout(7,13);
print "multout(7,13) = @r\n"; print "multout(7,13) = @r\n";
($x,$y) = multout(7,13); ($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 : A common misinterpretation of this function is the following Perl script :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
# Perl script # Perl script
$a = 3.5; $a = 3.5;
$b = 7.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 : Now, if you place this before the add function, you can do this :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
$a = 3.5; $a = 3.5;
$b = 7.5; $b = 7.5;
$c = 0.0; $c = 0.0;
@ -2543,7 +2544,7 @@ However, when proxy classes are enabled, these accessor functions are
wrapped inside a Perl class like this: wrapped inside a Perl class like this:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
package example::Vector; package example::Vector;
@ISA = qw( example ); @ISA = qw( example );
%OWNER = (); %OWNER = ();
@ -2609,7 +2610,7 @@ internally and described shortly.
To use our new proxy class we can simply do the following: To use our new proxy class we can simply do the following:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
# Perl code using Vector class # Perl code using Vector class
$v = new Vector(2,3,4); $v = new Vector(2,3,4);
$w = Vector-&gt;new(-1,-2,-3); $w = Vector-&gt;new(-1,-2,-3);
@ -2694,7 +2695,7 @@ by simply deleting the object from the <tt>%OWNER</tt> hash. This is
done using the <tt>DISOWN </tt>method. done using the <tt>DISOWN </tt>method.
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
# Perl code to change ownership of an object # Perl code to change ownership of an object
$v = new Vector(x,y,z); $v = new Vector(x,y,z);
$v-&gt;DISOWN(); $v-&gt;DISOWN();
@ -2704,7 +2705,7 @@ $v-&gt;DISOWN();
To acquire ownership of an object, the <tt>ACQUIRE</tt> method can be used. To acquire ownership of an object, the <tt>ACQUIRE</tt> method can be used.
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
# Given Perl ownership of a file # Given Perl ownership of a file
$u = Vector_get($v); $u = Vector_get($v);
$u-&gt;ACQUIRE(); $u-&gt;ACQUIRE();
@ -2741,7 +2742,7 @@ these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
look like this (along with some supporting code) : look like this (along with some supporting code) :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
package Particle; package Particle;
... ...
%BLESSEDMEMBERS = ( %BLESSEDMEMBERS = (
@ -2763,7 +2764,7 @@ unmodified.
This implementation allows us to operate on nested structures as follows : This implementation allows us to operate on nested structures as follows :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
# Perl access of nested structure # Perl access of nested structure
$p = new Particle(); $p = new Particle();
$p-&gt;{f}-&gt;{x} = 0.0; $p-&gt;{f}-&gt;{x} = 0.0;
@ -2789,7 +2790,7 @@ of tied hash tables. This is done by creating a Perl function like
this : this :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
sub dot_product { sub dot_product {
my @args = @_; my @args = @_;
$args[0] = tied(%{$args[0]}); # Get the real pointer values $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 : The resulting, Perl wrapper class will create the following code :
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
Package Shape; Package Shape;
@ISA = (shapes); @ISA = (shapes);
... ...
@ -2889,7 +2890,7 @@ It works like all the other <a href="Customization.html#features">%feature direc
Here is a simple example showing how to add some Perl debug code to the constructor: Here is a simple example showing how to add some Perl debug code to the constructor:
</p> </p>
<div class="code"><pre> <div class="targetlang"><pre>
/* Let's make the constructor of the class Square more verbose */ /* Let's make the constructor of the class Square more verbose */
%feature("shadow") Square(double w) %feature("shadow") Square(double w)
%{ %{
@ -2908,6 +2909,57 @@ public:
}; };
</pre></div> </pre></div>
<H2><a name="Perl5_nn47"></a>26.10 Adding additional Perl code</H2>
<p>
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 <tt>.pm</tt> file created by SWIG. One
use of Perl code might be to supply a high-level interface to certain functions.
For example:
</p>
<div class="code">
<pre>
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);
}
%}
</pre>
</div>
<p>
In this example, <tt>set_transform()</tt> provides a high-level Perl interface built on top of
low-level helper functions. For example, this code now seems to work:
</p>
<div class="targetlang">
<pre>
my $a =
[[1,0,0,0],
[0,1,0,0],
[0,0,1,0],
[0,0,0,1]];
set_transform($im, $a);
</pre>
</div>
</body> </body>

2
Doc/Manual/Python.html
View file

@ -4388,7 +4388,7 @@ steals ownership of an object. Returns 0 on success and -1 on error.
<p> <p>
<tt> <tt>
PyObject *Swig_NewPointerObj(void *ptr, swig_type_info *ty, int own)</tt> PyObject *SWIG_NewPointerObj(void *ptr, swig_type_info *ty, int own)</tt>
</p> </p>
<div class="indent"> <div class="indent">