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

86
Doc/Manual/Library.html
View file

@ -75,7 +75,7 @@ When searching for files, directories are searched in the following order:
<p>
Within each directory, SWIG first looks for a subdirectory corresponding to a target language (e.g., <tt>python</tt>,
<tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows
<tt>tcl</tt>, etc.). If found, SWIG will search the language specific directory first. This allows
for language-specific implementations of library files.
</p>
@ -88,7 +88,7 @@ You can override the location of the SWIG library by setting the
<p>
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 <tt>int *</tt>, <tt>double *</tt>, or <tt>void *</tt>. The modules can be
used to allocate memory, manufacture pointers, dereference memory, and wrap
@ -127,7 +127,7 @@ object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
</p>
<div class="indent"><p>
Creates a new object of type <tt>type</tt> and returns a pointer to it.
Creates a new object of type <tt>type</tt> and returns a pointer to it.
An initial value is set by copying it from <tt>value</tt>. In C, the
object is created using <tt>calloc()</tt>. In C++, <tt>new</tt> is used.
</p></div>
@ -187,7 +187,7 @@ Now, in Python:
<pre>
&gt;&gt;&gt; import example
&gt;&gt;&gt; c = example.new_intp() # Create an "int" for storing result
&gt;&gt;&gt; example.add(3,4,c) # Call function
&gt;&gt;&gt; example.add(3,4,c) # Call function
&gt;&gt;&gt; example.intp_value(c) # Dereference
7
&gt;&gt;&gt; example.delete_intp(c) # Delete
@ -267,7 +267,7 @@ Now, in Python (using proxy classes)
<pre>
&gt;&gt;&gt; import example
&gt;&gt;&gt; c = example.intp() # Create an "int" for storing result
&gt;&gt;&gt; example.add(3,4,c) # Call function
&gt;&gt;&gt; example.add(3,4,c) # Call function
&gt;&gt;&gt; c.value() # Dereference
7
</pre>
@ -369,7 +369,7 @@ should not correspond to any other name used in the interface file.
</p>
<p>
Here is an example of <tt>%array_functions()</tt>. Suppose you had a
Here is an example of <tt>%array_functions()</tt>. Suppose you had a
function like this:
</p>
@ -447,7 +447,7 @@ it can be transparently passed to any function that expects the pointer.
<p>
When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful.
When combined with proxy classes, the <tt>%array_class()</tt> macro can be especially useful.
For example:
</p>
@ -633,7 +633,7 @@ Now, in a script:
&gt;&gt;&gt; a = malloc_int()
&gt;&gt;&gt; a
'_000efa70_p_int'
&gt;&gt;&gt; free_int(a)
&gt;&gt;&gt; free_int(a)
&gt;&gt;&gt; b = malloc_intp()
&gt;&gt;&gt; b
'_000efb20_p_p_int'
@ -654,7 +654,7 @@ Now, in a script:
<p>
The <tt>cdata.i</tt> 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.
</p>
<div class="indent"><p>
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
Converts <tt>nbytes</tt> of data at <tt>ptr</tt> into a string. <tt>ptr</tt> can be any
pointer.
</p></div>
@ -674,13 +674,13 @@ pointer.
</p>
<div class="indent"><p>
Copies all of the string data in <tt>s</tt> into the memory pointed to by
<tt>ptr</tt>. The string may contain embedded NULL bytes. The length of
Copies all of the string data in <tt>s</tt> into the memory pointed to by
<tt>ptr</tt>. The string may contain embedded NULL bytes. The length of
the string is implicitly determined in the underlying wrapper code.
</p></div>
<p>
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:
</p>
@ -712,7 +712,7 @@ Python example:
&gt;&gt;&gt; memmove(c,b)
&gt;&gt;&gt; print c[4]
4
&gt;&gt;&gt;
&gt;&gt;&gt;
</pre>
</div>
@ -764,7 +764,7 @@ fixed-sized buffers.
The problems (and perils) of using <tt>char *</tt> 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.
</p>
<H3><a name="Library_nn9"></a>8.3.1 Default string handling</H3>
@ -868,7 +868,7 @@ char *foo() {
<p>
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.
</p>
<p>
@ -996,7 +996,7 @@ In the target language:
<div class="targetlang">
<pre>
&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;
</pre>
</div>
@ -1295,13 +1295,13 @@ In the target language:
<div class="targetlang">
<pre>
&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;
</pre>
</div>
<p>
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:
</p>
@ -1334,7 +1334,7 @@ void my_get_data(char **result, int *len) {
SWIG modules currently support this library.
</li>
<li>Reliable handling of raw C strings is a delicate topic. There are many ways
<li>Reliable handling of raw C strings is a delicate topic. There are many ways
to accomplish this in SWIG. This library provides support for a few common techniques.
</li>
@ -1412,6 +1412,42 @@ bar("Hello World"); # Pass string as std::string
</pre>
</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>
This module only supports types <tt>std::string</tt> and
<tt>const std::string &amp;</tt>. Pointers and non-const references
@ -1473,7 +1509,7 @@ currently a subset of the real STL vector class.
<li>Input typemaps are defined for <tt>vector&lt;X&gt;</tt>, <tt>const vector&lt;X&gt; &amp;</tt>, and
<tt>const vector&lt;X&gt; *</tt>. For each of these, a pointer <tt>vector&lt;X&gt; *</tt> may be passed or
a native list object in the target language.
a native list object in the target language.
</li>
<li>An output typemap is defined for <tt>vector&lt;X&gt;</tt>. In this case, the values in the
@ -1484,7 +1520,7 @@ vector are expanded into a list object in the target language.
object in the usual manner.
</li>
<li>An exception handler for <tt>std::out_of_range</tt> is defined.
<li>An exception handler for <tt>std::out_of_range</tt> is defined.
</li>
<li>Optionally, special methods for indexing, item retrieval, slicing, and element assignment
@ -1588,7 +1624,7 @@ IndexError: vector index out of range
</div>
<p>
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 <tt>using</tt> or typedef directives. For example:
</p>
@ -1615,12 +1651,12 @@ if you want to make their head explode.
</p>
<p>
<b>Note:</b> This module is defined for all SWIG target languages. However argument conversion
<b>Note:</b> This module is defined for all SWIG target languages. However argument conversion
details and the public API exposed to the interpreter vary.
</p>
<p>
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
<b>Note:</b> <tt>std_vector.i</tt> was written by Luigi "The Amazing" Ballabio.
</p>

142
Doc/Manual/Perl5.html
View file

@ -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 &gt; 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 = &amp;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 &amp;, Complex &amp;);
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-&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.
</p>
<div class="code"><pre>
<div class="targetlang"><pre>
# Perl code to change ownership of an object
$v = new Vector(x,y,z);
$v-&gt;DISOWN();
@ -2704,7 +2705,7 @@ $v-&gt;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-&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) :
</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-&gt;{f}-&gt;{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>

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>
<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>
<div class="indent">