Index: tools/swilena/ChangeLog from Astrid Wang <astrid@lrde.epita.fr> * doc/swilena.texi: Fix body. Index: tools/swilena/doc/swilena.texi --- tools/swilena/doc/swilena.texi Sat, 03 Jan 2004 17:25:53 +0100 burrus_n (oln/n/40_swilena.te 1.1.1.3 600) +++ tools/swilena/doc/swilena.texi Fri, 23 Jan 2004 17:47:58 +0100 astrid (oln/n/40_swilena.te 1.1.1.3 600) @@ -32,7 +32,7 @@ @node Top @top Swilena @end ifnottex -This documents is intended to describe Swilena, a simplified set of +This document is intended to describe Swilena, a simplified set of wrappers around the image processing library Olena. @menu @@ -82,9 +82,9 @@ The primary target language for Swilena is Python, because Python is the best supported back-end for SWIG. However, the SWIG definition files of Swilena are not bound to a particular interpreted language: -any SWIG target language @emph{providing enough expressivity} can be +any SWIG target language @emph{providing enough expressiveness} can be used. Ruby modules are defined too, they are not documented here but -they work almost the same way than Python modules. Here are the +they work almost the same way as Python modules. Here are the required features from the interpreted language: @itemize @bullet @@ -102,29 +102,29 @@ Scheme. Currently, the source tree only knows about Python and Ruby, but this -may evolute in the future. +may evolve in the future. @unnumberedsubsec Using Swilena for Olena development Obviously, Swilena provides the developer with a programming framework around Olena that has much shorter development cycles: new algorithms -can be tested in python without waiting for the compilation of test -C++ sources. +can be tested in Python without waiting for the compilation of C++ test +sources. -Moreover, because compiling Swilena actually means instanciating Olena -templates for a nearly complete cartesian product of types, the success +Moreover, because compiling Swilena actually means instantiating Olena +templates for a nearly complete Cartesian product of types, the success of the Swilena build process proves Olena's completeness. @node Of SWIG and Swilena principles @chapter Of SWIG and Swilena principles As already suggested, Swilena and SWIG are closely related. In fact, -SWIG is a wrapper generator, and Swilena is a set of input files for SWIG, -bundled in a package providing appropriate @file{Makefile}'s to ease +SWIG is a wrapper generator, and Swilena is a set of input files for SWIG +bundled in a package providing appropriate @file{Makefile}s to ease their handling. -This sections provides some information about SWIG itself and presents -the general guidelines that guided Swilena's development. +This section provides some information about SWIG itself and presents +the general guidelines that directed Swilena's development. @menu * Introduction to SWIG:: @@ -146,7 +146,7 @@ double My_variable = 3.0; -/* Compute factorial of n */ +/* Compute n factorial */ int fact(int n) @{ if (n <= 1) return 1; else return n*fact(n-1); @@ -154,7 +154,7 @@ /* Compute n mod m */ int my_mod(int n, int m) @{ - return(n % m); + return n % m; @} @end cartouche @end example @@ -294,20 +294,23 @@ @item SWIG knows about class constructors and references and treats them trivially. @item -The SWIG description need not follow exactly the strict C++ definition. In the previous example, -the Olena class @code{window2d} is far more complex than what is expressed in the SWIG declaration; -however, for a SWIG description to be valid, it only needs to describe a class more @emph{general} -than the real one. +The SWIG description need not follow exactly the strict C++ +definition. In the previous example, the Olena class @code{window2d} +is far more complex than what is expressed in the SWIG declaration; +however, for a SWIG description to be valid, it only needs to describe +a class more @emph{general} than the real one. @item -Although it is possible to do so, the SWIG description need not express class inheritance. +Although it is possible to do so, the SWIG description need not +express class inheritance. @end itemize @node Operators and class extensions @subsection Operators and class extensions -When the target interpreted language allows overloading arithmetical operators for classes, SWIG -can propagate this C++ feature. However, if it does not, it is needed to provide an artificial - method-like interface to the class operators. +When the target interpreted language allows overloading arithmetical +operators for classes, SWIG can propagate this C++ feature. However, +if it does not, it is needed to provide an artificial method-like +interface to the class operators. Here is a demonstration: @@ -369,24 +372,28 @@ @end example Here are the key points exhibited by this example: - @itemize @minus @item -When the interpreted language allows so, SWIG understands C++ operator overloading and treats it trivially. +When the interpreted language allows so, SWIG understands C++ operator +overloading and treats it trivially. @item -The @code{%extend} SWIG sections allows adding pseudo-methods to interfaced classes. It can be used to provide -function names to C++ operators for interpreted languages that do no not cope with operator overloading (e.g. Perl). +The @code{%extend} SWIG sections allows adding pseudo-methods to +interfaced classes. It can be used to provide function names to C++ +operators for interpreted languages that do no not cope with operator +overloading (e.g. Perl). @item -When the description file includes @file{std_string.i}, SWIG knows about the C++ standard type @code{std::string}, -and knows how to convert it to and from the interpreted language's native string type. +When the description file includes @file{std_string.i}, SWIG knows +about the C++ standard type @code{std::string}, and knows how to +convert it to and from the interpreted language's native string type. @end itemize @node SWIG and C++ templates @subsection SWIG and C++ templates - -In addition to function, variables, structures and classes, SWIG knows about templates. However, because scripting languages -do not support templates and template instanciation, information must be provided to SWIG to explain -what template instances must be available to the scripting language. +In addition to function, variables, structures and classes, SWIG knows +about templates. However, because scripting languages do not support +templates and template instanciation, information must be provided to +SWIG to explain what template instances must be available to the +scripting language. Here is a demonstration: @@ -450,9 +457,11 @@ @itemize @minus @item -SWIG can only wrap template @emph{instances}. The instanciation must be made explicit. +SWIG can only wrap template @emph{instances}. The instantiation must +be made explicit. @item -However, when instanciating a template class, all its methods are instanciated at the same time. +However, when instantiating a template class, all its methods are +instantiated at the same time. @item Template instances must be given a unique identifier (e.g. @code{w_win2d_int}), because C++ template instance names @@ -467,18 +476,19 @@ @itemize @minus @item -SWIG collates all C++ namespaces in the global module namespace. Therefore, beware -of wrapped function or class names that appear simultaneously in several namespaces with -different definitions: they are not handled properly by SWIG. - +SWIG collates all C++ namespaces in the global module +namespace. Therefore, beware of wrapped function or class names that +appear simultaneously in several namespaces with different +definitions: they are not handled properly by SWIG. @item -The C++ parser in SWIG cannot deal with C++ template partial specialization. Therefore, -C++ tricks such as static hierarchies and virtual types cannot be exposed to SWIG. Consider -hiding the static inheritance tree and exposing the most derived classes instead. - +The C++ parser in SWIG cannot deal with C++ template partial +specialization. Therefore, C++ tricks such as static hierarchies and +virtual types cannot be exposed to SWIG. Consider hiding the static +inheritance tree and exposing the most derived classes instead. @item -Families of similar template functions cannot be instanciated with a single SWIG directive. -Use SWIG macros and appropriate naming conventions for this purpose: +Families of similar template functions cannot be instantiated with a +single SWIG directive. Use SWIG macros and appropriate naming +conventions for this purpose: @example @cartouche @@ -488,15 +498,15 @@ template<typename T> void bar(T x); -%define Instanciate_Templates_For(Type) +%define Instantiate_Templates_For(Type) %template (foo_ ## Type) foo<Type >; %template (bar_ ## Type) bar<Type >; %enddef -Instanciate_Templates_For(int); +Instantiate_Templates_For(int); // yields foo_int and bar_int -Instanciate_Templates_For(float); +Instantiate_Templates_For(float); // yields foo_float and bar_float @end cartouche @@ -523,13 +533,13 @@ @end example The @code{>>>} text is the Python standard prompt, where -you can enter python statements. +you can enter Python statements. You can also write Python programs as scripts, using the following script template: @example -#! /usr/bin/python +#! /usr/bin/env python ... your program here ... @end example @@ -537,9 +547,9 @@ @section Python Basics -Python does not have mandatory statement terminators. Statements end at the end -of the line. However, you can use the semicolon (@samp{;}) as -a command separator. +Python does not have mandatory statement terminators. Statements end +at the end of the line. However, you can use the semicolon (@samp{;}) +as a command separator. @example

...

...

@kbd{print "hello"} @@ -550,7 +560,8 @@ @end example

...

...

@kbd{import random} @@ -710,9 +721,12 @@ @item set set the value of the indicated pixel. @item ncols -return the number of columns in the image. This method is valid for 1D, 2D and 3D images. +return the number of columns in the image. This method is valid for +1D, 2D and 3D images.

-Python data types are the integer (signed), the float (C @samp{double}), and the character string. +Python data types are the integer (signed), the float (C +@samp{double}), and the character string. Constants can be expressed intuitively: @example @@ -626,7 +637,7 @@ @subsection Python Objects By convention, standard Python Classes have names that start with -a capital. This helps disambiguise class names and module names: +a capital. This helps disambiguate class names and module names: @example + @item nrows -return the number of rows in the image. This method is only valid for 2D and 3D images. +return the number of rows in the image. This method is only valid for +2D and 3D images. @item nslices return the number of slices of a 3D image. @end table -- astrid