Re: [Plplot-devel] SWIG wrapping of Python output arrays

[Alan W. I. <ir...@be...>]

On 2012-01-16 11:37-0000 Andrew Ross wrote:

> Alan,
>
> Many thanks for this! I've been slightly worried about this for some time
> so it's nice that you've found a neater solution.
>
> Your documentation changes missed out a tag though which caused octave
> documentation builds to fail. I've fixed this, but can you please
> check that I've done what you intended.

I have made a further change (revision 12133) which validates and
which also better represents what I want.

This whole area of documenting redacted functional forms for languages
that handle output arguments by moving them from the argument list to
the left side of an assignment statement needs lots more work.  For
example:

software@raven> grep ddata examples/*/*21* |grep "="
examples/lua/x21.lua:    zg = pl.griddata(x, y, z, xg, yg, alg,
opt[alg])
examples/ocaml/x21.ml:      let zg = plgriddata x y z xg yg named_alg
opt.(alg - 1) in
examples/octave/p21.m:    zg = griddata(x, y, z, xg, yg, i, opt(i));
examples/octave/x21c.m:      zg = plgriddata(x, y, z, xg, yg, alg,
opt(alg));
examples/perl/x21.pl:      $zg = plgriddata ($x, $y, $z, $xg, $yg,
$alg, $opt [$alg - 1]);
examples/python/xw21.py:            zg = plgriddata(x, y, z, xg, yg,
alg, opt[alg-1])

shows that lua, ocaml, octave, perl, and python all use this method of
dealing with output arguments with some small variations in syntax.  I
think we need a way to summarize this assignment-statement style (say
by documenting the Python syntax but mentioning the others are
similar) so we don't have to repeat this information individually for
the 5 languages that use it. Furthermore, a quick review of
bindings/swig-support/plplotcapi.i shows many OUTPUT variables and
some OUTPUT arrays that need assignment-statement style documentation
in the redacted forms for the above languages.

In sum, we need some thought and experiment about how we actually want
to handle the redacted case for languages that use an
assignment-statement style.  Once that decision is made, I am sure the
form and maybe even the tags I used for the redacted case of
plgriddata and python will need further changes.  Also, once the big
decisions are made for how to handle the assignment-statement style,
then there is a fairly large but completely straightforward editing
job on api.xml in the offing to implement those decisions.

Alan
__________________________
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); the Time
Ephemerides project (timeephem.sf.net); PLplot scientific plotting
software package (plplot.sf.net); the libLASi project
(unifont.org/lasi); the Loads of Linux Links project (loll.sf.net);
and the Linux Brochure Project (lbproject.sf.net).
__________________________

Linux-powered Science
__________________________