On 2007-02-19 17:44-0500 hbabcockos1@... wrote:
> On Feb 18, 2007, at 11:54 PM, Alan W. Irwin wrote:
>> On 2007-02-18 22:36-0500 hbabcockos1@... wrote:
>>> In the process of working my way through updating the documentation
>>> I've noticed that there are a reasonable number of functions that I
>>> cannot find in the Python API. Is this because they are really
>>> missing? Or am I not looking in the right place? My approach has been
>>> to grep for the function name in the bindings/python directory.
>>> Example (missing) functions include plfill3, plflush, plgcol0 and
>> Both Python and Java API are implemented in the file
>> bindings/swig-support/plplotcapi.i. Those API's are probably our
>> third-most complete ones after C and C++.
> Thanks! Now how do I figure out the redacted form for Python?
> Using the function plbin as an example, for java I can go:
> grep plbin bindings/java/*
> and I get:
> java/PLStream.java: plplotjavac.plbin(x, y, center);
> From which I infer that the first argument, nbin, has been dropped.
> If I look in bindings/swig-support/plplotcapi.i to try and see what Python
> will do I see:
> %feature("autodoc", "Plot a histogram using x to store data values and y to
> store frequencies.") plbin;
> plbin(PLINT n, PLFLT *Array, PLFLT *ArrayCk, PLINT center);
> Which suggests that Python has kept the first argument.
Actually not. Both the python and java interfaces are generated using the
information in bindings/swig-support/plplotcapi.i, but
bindings/python/plplotcmodule.i and bindings/java/plplotjavac.i do
additional platform-dependent processing. In both those latter files look
for "with preceding count". The lines just after that comment show SWIG how
to transform the pattern "PLINT n, PLFLT *Array," into one array argument
for both python and java. Through such tricks, the python and java
redundant array dimension information is all removed.
For your documentation efforts, I suggest you assume that all dimension
information dropped by swig for java is also dropped for python. It is a
bug in how the argument patterns are handled in
bindings/python/plplotcmodule.i and bindings/java/plplotjavac.i if that
turns out not to be the case.
N.B. where the python interface actually differs from java is the way
information is returned for output arguments. In python the output
arguments are completely removed from the argument list, and instead the
output arguments are returned as the function value (which is returned as a
list of output arguments). For the java case, the output arguments stay in
the argument list. For example, look for how plg* functions are used in
examples/java versus examples/python and assume that same treatment is
used for both languages for all output variables. (Again it is an interface
bug if that proves not to be the case.)
Alan W. Irwin
Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).
Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the Yorick front-end to PLplot (yplot.sf.net); the
Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project