[C++-sig] pyplusplus ui / API

[Allen Bierbaum]

On 2/14/06, Nat Goodspeed <ngoodspeed at solidworks.com> wrote:
> >
> > > 1. What about code creators? Code creators is very powerful concept.
> >
> > This is an area where I am at a loss as to how to handle this.  If we
> > are "filtering" and making decisions based on the decl tree it seems
> > like the cleanest interface to the user would be to allow them to make
> > some of these customizations in that gccxml tree.  Unfortunately this
> > tree does not have the code generators yet since it is really used to
> > create the code generators.
> >
> > One idea I did have is that we graft on new nodes to the decl tree
> > that are custom to pyplusplus without extending gccxml.  For example
> > we could add a custom_code_t derived from declarations_t that could be
> > added into the declaration tree by the user to add code anywhere.
> > Similarly there could be a new node for implicitly_convertibles and so
> > on.
> >
> > Is it possible for the code creators to read from something like this
> > and create the correct creators?  We would lose some power with an
> > interface like this though so I think it would be important to allow
> > direct access to the code creators after they have been instantiated.
>
> [Nat] Maybe I don't fully understand the discussion to date, and if so I
> apologize. But I like the idea of working mostly in the pygccxml
> declarations tree.
>
> IIUC, what you have in mind is for the user to write code to decorate
> that tree, then hand off the decorated tree to pyplusplus and poof!
> pyplusplus does all the rest.
>
> But would it make any sense to expose two distinct pyplusplus steps?
>
> 0. pygccxml creates the declarations tree
> 1. user code decorates the decl tree
> 2. ==> call first pyplusplus step to read decl tree and instantiate code
> creators
> 3. power user code now has the opportunity to mess with code creators
> directly
> 4. ==> call second pyplusplus step to perform all the rest of the
> processing.

It may not have been clear from my description, but this is the exact
solution I am proposing.  Make the "simple" interfaces decorate the
pygccxml tree (by injecting attributes) and then build the creators
from this.  The resulting creators tree may be a little difficult to
edit directly but it is the same as what we have now and it should
only be necessary for power users.

> Of course for simple cases (no step 3 intervention required) you could
> have a convenience routine that does both -- as long as the
> documentation makes very clear that your convenience routine is nothing
> more than

Agreed.

>
> pyplusplus.generate(pyplusplus.preprocess(mytree))
>
> (or whatever the applicable names are for steps 2 and 4 above)
>
> On the other hand, if you can make it that easy to compose the two
> pyplusplus steps, maybe it's better to avoid the convenience function so
> there's never any question about the user's opportunity to intervene
> before the second call.

I would like to shoot for making it possible for 90% of users to do
everything they need without having to intervene and edit the creators
directly.  If we can make a simplified interface that hides the vast
majority of the complexity then I think we would have a very powerful
interface indeed.

The nice thing about the method we are proposing (decorating the
gccxml tree) is that new capabilities could be added on gradually.  So
if for example a significant number of users find they are all needing
to make similar modifications to the creators then the interface could
be expanded to allow this to be added to the gccxml tree.  It seems
like this would be a nice balance between simplicity and flexibility.

-Allen