adding several docs patches
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
parent
f222064ffd
commit
91d4692367
3 changed files with 159 additions and 71 deletions
|
|
@ -67,6 +67,7 @@
|
|||
<li><a href="#Perl5_nn45">Inheritance</a>
|
||||
<li><a href="#Perl5_nn46">Modifying the proxy methods</a>
|
||||
</ul>
|
||||
<li><a href="#Perl5_nn47">Adding additional Perl code</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- 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
|
||||
script such as the following :</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# 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 :</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
%module example
|
||||
|
||||
%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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
$ 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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
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 <tt>%module</tt> directive.
|
|||
A somewhat related, but slightly different error is this:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
use example;
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
%module example
|
||||
int fact(int a);
|
||||
...
|
||||
|
|
@ -735,7 +736,7 @@ int fact(int a);
|
|||
Now, in Perl:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
use example;
|
||||
$a = &example::fact(2);
|
||||
</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
|
||||
the same name as the C global variable. Thus, an interface like this </p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
%module example;
|
||||
...
|
||||
double Spam;
|
||||
|
|
@ -759,7 +760,7 @@ double Spam;
|
|||
<p>
|
||||
is accessed as follows :</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
$ptr = new_Matrix(int n, int m); # Save pointer return result
|
||||
bless $ptr, "p_Matrix"; # Bless it as a pointer to Matrix
|
||||
</pre></div>
|
||||
|
|
@ -868,7 +869,7 @@ generated.</p>
|
|||
To check to see if a value is the NULL pointer, use the
|
||||
<tt>defined()</tt> command :</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
$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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
use example;
|
||||
example::foo_i(3);
|
||||
|
|
@ -1245,7 +1246,7 @@ Complex operator+(Complex &, Complex &);
|
|||
Now, in Perl, you can do this:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
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
|
|||
<tt>%module</tt> directive. To use the module, do the following :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
% 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
|
|||
`<tt>Foo</tt>.' For example :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
use example; # Load the module like before
|
||||
print Foo::fact(4),"\n"; # Call a function in package FooBar
|
||||
</pre></div>
|
||||
|
|
@ -1371,7 +1372,7 @@ int sub(int *INPUT, int *INPUT);
|
|||
In Perl, this allows you to pass simple values. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
$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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
$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.
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
($bytes, $success) = example::send_message("Hello World");
|
||||
</pre>
|
||||
|
|
@ -1506,7 +1507,7 @@ void get_dimensions(Matrix *m, int *rows, *columns);
|
|||
Now, in Perl:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
($r,$c) = example::get_dimensions($m);
|
||||
</pre>
|
||||
|
|
@ -1530,7 +1531,7 @@ void add(int x, int y, int *REFERENCE);
|
|||
In Perl:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
use example;
|
||||
$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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
use example;
|
||||
$n = example::fact(6);
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
%typemap(in) int n {
|
||||
$1 = (int) SvIV($input);
|
||||
|
|
@ -1805,7 +1806,7 @@ type <tt>int</tt>.
|
|||
Typemaps can also be defined for groups of consecutive arguments. For example:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
%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):
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
example::count("e","Hello World");
|
||||
1
|
||||
|
|
@ -1841,7 +1842,7 @@ like this:
|
|||
</p>
|
||||
|
||||
|
||||
<div class="code">
|
||||
<div class="targetlang">
|
||||
<pre>
|
||||
%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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
@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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# 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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
$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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# 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 <tt>%OWNER</tt> hash. This is
|
|||
done using the <tt>DISOWN </tt>method.
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# 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 <tt>ACQUIRE</tt> method can be used.
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# Given Perl ownership of a file
|
||||
$u = Vector_get($v);
|
||||
$u->ACQUIRE();
|
||||
|
|
@ -2741,7 +2742,7 @@ these correctly, we use the <tt>%BLESSEDMEMBERS</tt> hash which would
|
|||
look like this (along with some supporting code) :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
package Particle;
|
||||
...
|
||||
%BLESSEDMEMBERS = (
|
||||
|
|
@ -2763,7 +2764,7 @@ unmodified.
|
|||
This implementation allows us to operate on nested structures as follows :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
# 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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
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 :
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
Package Shape;
|
||||
@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:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
<div class="targetlang"><pre>
|
||||
/* Let's make the constructor of the class Square more verbose */
|
||||
%feature("shadow") Square(double w)
|
||||
%{
|
||||
|
|
@ -2908,6 +2909,57 @@ public:
|
|||
};
|
||||
</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>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue