Menu
▾
▴
[Swig-cvs] SF.net SVN: swig:[13090] trunk/Doc/Manual/Octave.html
|
From: <kw...@us...> - 2012-05-14 09:24:56
|
Revision: 13090
http://swig.svn.sourceforge.net/swig/?rev=13090&view=rev
Author: kwwette
Date: 2012-05-14 09:24:45 +0000 (Mon, 14 May 2012)
Log Message:
-----------
Updated Octave documentation on module load behaviour
Modified Paths:
--------------
trunk/Doc/Manual/Octave.html
Modified: trunk/Doc/Manual/Octave.html
===================================================================
--- trunk/Doc/Manual/Octave.html 2012-05-14 09:24:34 UTC (rev 13089)
+++ trunk/Doc/Manual/Octave.html 2012-05-14 09:24:45 UTC (rev 13090)
@@ -63,7 +63,7 @@
</p>
<p>
-As of SWIG 2.0.5, the Octave module should work with Octave versions 3.0.5, 3.2.4, and 3.4.0.
+As of SWIG 2.0.7, the Octave module has been tested with Octave versions 3.0.5, 3.2.4, 3.4.3, and 3.6.1.
</p>
<H2><a name="Octave_nn3"></a>30.2 Running SWIG</H2>
@@ -95,7 +95,7 @@
<div class="shell"><pre>$ swig -octave -c++ -o example_wrap.cpp example.i </pre></div>
<p>
-This creates a C++ source file <tt>example_wrap.cpp</tt>. A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
+This creates a C++ source file "example_wrap.cpp". A C++ file is generated even when wrapping C code as Octave is itself written in C++ and requires wrapper code to be in the same language. The generated C++ source file contains the low-level wrappers that need to be compiled and linked with the rest of your C/C++ application (in this case, the gcd implementation) to create an extension module.
</p>
<H3><a name="Octave_nn4"></a>30.2.1 Command-line options</H3>
@@ -110,15 +110,12 @@
<pre>$ swig -octave -help
...
Octave Options (available with -octave)
- -global - Load all symbols into the global namespace [default]
-globals <em>name</em> - Set <em>name</em> used to access C global variables [default: 'cvar']
- - Use '.' to load C global variables into module namespace
- -noglobal - Do not load all symbols into the global namespace
+ Use '.' to load C global variables into module namespace
-opprefix <em>str</em> - Prefix <em>str</em> for global operator functions [default: 'op_']
</pre></div>
<p>
-The <em>-global</em> and <em>-noglobal</em> options determine whether the Octave module will load all symbols into the global namespace in addition to the global namespace.
The <em>-globals</em> option sets the name of the variable which is the namespace for C global variables exported by the module.
The special name "." loads C global variables into the module namespace, i.e. alongside C functions and structs exported by the module.
The <em>-opprefix</em> options sets the prefix of the names of global/friend <a href="#Octave_nn18">operator</a> functions.
@@ -138,7 +135,7 @@
</pre></div>
<p>
- where example.c is the file containing the gcd() implementation.
+ where "example.c" is the file containing the gcd() implementation.
</p>
<p>
@@ -146,7 +143,7 @@
</p>
<p>
- mkoctfile will produce example.oct, which contains the compiled extension module. Loading it into Octave is then a matter of invoking
+ mkoctfile will produce "example.oct", which contains the compiled extension module. Loading it into Octave is then a matter of invoking
</p>
<div class="targetlang"><pre>octave:1> example</pre></div>
@@ -176,58 +173,67 @@
<p>
-The SWIG module directive specifies the name of the Octave module. If you specify `module example', then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
+The SWIG module directive specifies the name of the Octave module. If you specify "module example", then in Octave everything in the module will be accessible under "example", as in the above example. When choosing a module name, make sure you don't use the same name as a built-in Octave command or standard module name.
</p>
<p>
-When Octave is asked to invoke <tt>example</tt>, it will try to find the .m or .oct file that defines the function "example". It will thusly find example.oct, that upon loading will register all of the module's symbols.
+When Octave is asked to invoke <tt>example</tt>, it will try to find the ".m" or ".oct" file that defines the function "example". You therefore need to make sure that "example.oct" is in Octave's search path, which can be specified with the environment variable "OCTAVE_PATH".
</p>
<p>
-An Octave module takes three options, <em>-global</em>, <em>-noglobal</em>, and <em>-globals</em>, which behave the same as the corresponding swig <a href="#Octave_nn4">command-line options</a>.
-Here are some example usages:
+An Octave module can either load its symbols into the global namespace, so that they can be accessed directly without having to type the module name.
+Alternatively, an Octave module can be accessed through a local variable, without being loaded globally.
</p>
- <div class="targetlang"><pre>
-octave:1> example -help
-usage: example [-global|-noglobal] [-globals <name>]
-octave:2> example -global
-octave:3> gcd(4,6)
+<p>
+To load an Octave module globally, simply type its name:
+</p>
+
+<div class="targetlang"><pre>
+octave:1> example;
+octave:2> gcd(4,6)
ans = 2
-octave:4> cvar.Foo
+octave:3> cvar.Foo
ans = 3
-octave:5> cvar.Foo=4;
-octave:6> cvar.Foo
+octave:4> cvar.Foo=4;
+octave:5> cvar.Foo
ans = 4
</pre></div>
-<br>
- <div class="targetlang"><pre>
-octave:1> example -noglobal
-octave:2> gcd(6,9)
+
+<p>
+To access an Octave module through a local variable, without loading it globally, simply assign the module name (e.g. "example") to the desired local variable:
+</p>
+
+<div class="targetlang"><pre>
+octave:1> example = example;
+octave:2> example.gcd(6,9)
ans = 3
-octave:3> cvar.Foo
-error: `cvar' undefined near line 3 column 1
octave:3> example.cvar.Foo
ans = 3
</pre></div>
-<br>
- <div class="targetlang"><pre>
-octave:1> example -globals mycvar
-octave:2> cvar.Foo
-error: `cvar' undefined near line 2 column 1
-octave:2> mycvar.Foo
+
+<p>
+The variable may have the same name as the module, or a shorter one:
+</p>
+
+<div class="targetlang"><pre>
+octave:1> ex = example;
+octave:2> ex.gcd(6,9)
ans = 3
+octave:3> ex.cvar.Foo
+ans = 3
</pre></div>
<p>
- It is also possible to rename the module / global variables namespaces with an assignment, as in: <br>
- <div class="targetlang"><pre>
-octave:1> example
-octave:2> c=example;
-octave:3> c.gcd(10,4)
+It is also possible to rename the global variables namespaces with an assignment, as in:
+</p>
+
+<div class="targetlang"><pre>
+octave:1> example;
+octave:2> cvar.gcd(10,4)
ans = 2
-octave:4> some_vars = cvar;
-octave:5> some_vars.Foo
+octave:3> some_vars = cvar;
+octave:4> some_vars.Foo
ans = 3
</pre></div>
@@ -274,9 +280,9 @@
Global variables are a little special in Octave. Given a global variable:
</p>
- <div class="code"><pre>%module example
+<div class="code"><pre>%module example
extern double Foo;
- </pre></div>
+</pre></div>
<p>
To expose variables, SWIG actually generates two functions, to get and set the value. In this case, Foo_set and Foo_set would be generated. SWIG then automatically calls these functions when you get and set the variable-- in the former case creating a local copy in the interpreter of the C variables, and in the latter case copying an interpreter variables onto the C variable.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|