[Kde-bindings] The code!

[Ashley Winters]

--- Richard Dale <Richard_Dale at tipitina.demon.co.uk> wrote:
> I've been thinking about how best to use this stuff for improving the
> java 
> bindings code generation. It solves two problems - extracting
> bindings info 
> from an -fdump'd file more accurately than by parsing headers, and
> producing 
> XML in a standard format. 
> 
> I don't personally have a requirement for the second XML bit. I think
> my 
> actual requirement is to be able to pull together bindings generation
> data 
> from several different sources. For example, I'd like to get C++
> method 
> signatures via '-fdump', C++ signal/slot or kde dcop signatures via
> command 
> line utilities, Qt doc comments from the .cpp sources in qdoc format,
> and the 
> KDE doc comments from .h headers in kdoc format. Then pull them all
> together 
> into a common tree, which I can use to drive the production of the
> final 
> code.

Good goal.

> If the XML format helps with this 'data merging', then it would be
> useful. But 
> if it turns out easier to do it another way, I'll use that.
> 
> * Default argument values
> You're producing a different xml method description for each possible
> number 
> of arguments. For java, it would be more useful to represent these as
> a 
> single method with the maximum number of args, and an additional
> couple of 
> attributes added for each arg 'is default arg' and 'default arg
> value'. 

Okay, how about a compromise?

The -fdump parser is limited in reconstructing default values. It can
retrieve constants from gcc just fine, and even variables, but
expressions aren't going to happen. Therefore, I can offer this:

Add an 'artificial' flag to all generated methods which were created
for the purpose of making bindings easier (non-defaulting arguments,
baseclass virtual methods, etc). That way, it's very easy to wean them
out.

For the non-artificial methods, go ahead and extract whatever default
arguments it's possible to extract as a "value" tag.

    <method protection="public" name="QWidget" type="constructor">
      <argument name="parent" type="class QWidget*" value="0" />
      <argument name="name" type="char const*" value="0" />
      <argument name="f" type="bool" value="0" />
    </method>

Constant integers, enums, and boolean variables should all work as
value. Whenever a value in indecipherable, I will use value="?", and
it'll be up to the language binder to figure out what to do with that
one. Perhaps there will be so few of them we could hard-code values in.
Fortunately, QWidget wouldn't have any value="?" defaults.

> This would allow the generation of a single native code JNI call with
> the 
> maximum number of args, and the other method calls with fewer args
> would be 
> produced by generating java source code. JNI calls take up more space
> in a 
> shared lib, relative to java method calls in .jar file so it pays to
> try and 
> minimise them.

Very good point. I will keep that in mind. (Although, if you wanted a
small JNI library, there's always Smoke. *cough*)

> * Class hierarchy
> How is this represented in the XML - each class would need something
> like a 
> 'parents' attribute with a list of parent classes?

<base> tag, actually. The Perl hashes randomize its location in the
file. On my computer, it's happily placed at the top of the XML file.

> * Document comments
> If you're pulling in data from different sources - both '-fdump' and 
> slot/signals command line utility so far, then why not use the
> headers or 
> sources as another source of bindings data to extract doc comments,
> default 
> arg values or anything else that is still missing? A text 'doc
> comment' 
> attribute against each method/class would be useful to hold any
> comment text, 
> even if it isn't used by the '-fdump'er' output.

Browsing through the Qt documentation, I've decided that it would
actually be an excellent way of specifying what classes to place in the
XML.

grep '\\class ' *.cpp

As you can see, that is a rather comprehensive list of classes
implemented & documented in those source files, along with the header
to parse to get -fdump info if I wanted to list them.

The qdoc standard requires \fn OR the first line after the end of the
qdoc comment to be the method signature? Works for me. I think I could
parse one line of C++ per function, just this once. I think I can
squeeze in qdoc next version, no extra charge.

I'll do that document extraction in a separate program though. XML is
too convenient to not use as an intermediate data format. :)

I might even stick the signal/slot detection in another script as well.

Hell, I'll just make the 'artificial' method generation use that same
trick, and take that cruft out of the -fdump parser. It'd be cleaner
that way.

> * Argument names
> They're there - excellent!

Yes, very handy. Not only there, but required!

> I fixed up and added the methods from the parent template class by
> hand for 
> QPointArray in the java bindings. Nearly all the other C++ list
> classes were 
> translated into java ArrayLists, so they didn't need any list
> handling 
> methods from the template classes that implemented the lists.
> QPointArray has 
> more to do with handling QPoints than just being a straightforward
> list 
> thing, so it's a bit unusual.

Yeah, templates aren't a big loss. I'm rather stunned at getting
QString/QChar and all the other utility classes working in one shot,
though. Last night, I did an XML dump of the whole Qt include/
directory. Enlightening stuff.

Ashley Winters

__________________________________________________
Do you Yahoo!?
Yahoo! Tax Center - forms, calculators, tips, more
http://taxes.yahoo.com/