[C++-sig] pyplusplus ui / API

[Roman Yakovenko]

Hi. Here is my thoughts about next messages:
http://mail.python.org/pipermail/c++-sig/2006-February/010213.html
http://mail.python.org/pipermail/c++-sig/2006-February/010222.html.

First of all what is user domain specific language (DSL)? Matthias
Baas provided the answer:

>My suggestion would be to make the declaration tree
>more "feature rich" and make it the main data structure that the user
>will interact with.

And I think he is right. Here is the "language"( public interface ) of pygccxml:
    calldef
            args
        member_function
        constructor
        destructor
        member_operator
        casting_operator
        free_function
        free_operator
    class_declaration
    class
        bases
        derived
        public_members
        protected_members
        private_members
    enumeration
    namespace
    typedef
    variable.

So basically, if you do not want to export some declaration, you write
decl.ignore = True. By default for all declarations from std namespace
and built-in ones
ignore equal to True. This will solve famous, :-(, filtering problem.
Also, it will not solve
filtering "spaghetti code". I just don't see how it can do it. If you
have a lot of special cases
you have to write them all somewhere. Take a look on the example from the second
message.

Open question: If user set ignore to True on namespace and\or class
does it mean that
pyplusplus should not export whole namespace\class?

Second thought is to "hide" a little pygccxml. This will allow simple
cases to be really simple:
module = create_module( files, GCC XML configuration )
#by default all declarations outside of the files ignore property will
be set to True ???
module.name = "hello_world"
module.write('hello_world.cpp') #if name has not been set exception
will be thrown
or
module.write_files('.') #split code of module to multiple files

Class module_t will contain declarations_tree property. User will be
able to travel
the tree and:
    to set ignore flag to True or False ( no more confusion )
    to set call policies ( no more call policies factory )
    to set alias
    to set documentation string
and may be few other things, right now I don't have good definition
for "other things"

Class module also will contain few "get\find\constructor" helper functions.
Basically they will search for some declaration according to some criteria.
This is exactly what Matthias Baas proposed and Allen Bierbaum did.

So far so good. Until now we almost back to usability level of Pyste.

Now questions I can not answer:

0. Does DSL should be based on C++ or Python terminology?
    For example: Matthias Baas and Allen Bierbaum talk about member
and free functions
    as method.

    I think that we should peek C++\Boost.Python terminology? There is
no (good ?) way
    to express register_to_python_ptr or implicit_convertible using
Python terminology.

1. What about code creators? Code creators is very powerful concept.
    1.1 What is the user interface to inject code "X" under class "Y" ?
    1.2 How user can customize generated code. For example recent
registration order
          problem. The quick and dirty work around was to set
use_keywords property of
          function_t code creator to False.
    1.3 For some declaration pyplusplus creates more then one code creator:
          1.3.1 class has 2 relevant code creators: class_t and wrapper_t
          1.3.2 if class has "casting constructor /* struct X{ X(int); }; */
                  or casting operator then implicitly_convertible code
creator will be created.
          1.3.3 There are also code creators that creates
register_ptr_to_python code

    I think you've got the idea. My point is that user should be able
to work with code
    creators tree.

    I do have some idea how to implement this, but first I would like
to know what do you
    think?

2. Pyste is able to create code without generating main. It is
possible to do it with
    pyplusplus, but you have to know low level details. How do you
solves this problem?

3. Technical problem: pygccxml is stand alone project. It is useful on
its own. I don't want
    to pollute it with code that is only useful for pyplusplus. I
think that next solution will
    work, but I don't like it:
    pygccxml defines next class pygccxml.declaration.class_t

    pyplusplus will create new class that derives from
pygccxml.declaration.class_t class.
    Lets say it will be pyplusplus.declaration_wrappers.class_t.
pyplusplus will change
    __class__ attribute of pygccxml.declaration.class_t instance to be
    pyplusplus.declaration_wrappers.class_t. Thus user will have
"original" declarations
    tree, full functionality of pygccxml and easy way to find out what
he can\should
    change\set for specific declaration. What I don't like is the
trick, that changes
    __class__ attribute.

    May be you have an other solution.

By the way it is not very difficult to implement this. I suppose it
will take +- 2 weeks
1 week to implement - core functionality already exists, 1 week to stabilize.

Thoughts, comments and suggestions are welcome.

Thanks.

--
Roman Yakovenko
C++ Python language binding
http://www.language-binding.net/