[pygccxml-development] single/multiple select interface

[Roman Y. <rom...@gm...>]

Hi. I did not had much time this weekend to work( write ) some
conclusions from our
conversation :-). I reviewed documentation you wrote - perfect. I like
the work you did.
Thanks.

Also, after my conversation with Matthias I think, that I fully
understand the issue.
The main question is: does class module_builder_t ( mb ) should have 2
different sets of
select functions:

    the first one for selecting single instance of declaration
    the second one for selection multiple instances of declarations

or
    should it have only second one ( multi-select )?

Here is discussion that I hope will guide us to the right answer.

    First of all, I think that this is obvious, that an user can use only s=
econd
approach to select 1 instance of declaration and to work on it. The
main Matthias
point, please correct me if I wrong, is that the user does not have to know=
 on
how many instances he works.

Here is some possible implementation of Matthias API:

[1]
class module_builder_t:
    def member_function( self, ..., num_expected=3DNone ):
        mfs =3D some magic code that according to criteria will return list=
 of
              all member functions.

        if None is num_expected:
            return multi_decl_wrapper_t( mfs )

        if num_expected !=3D len( mfs ):
            raise RuntimeError( "unexpected number of mem functions,
that match criteria: ...." )

        if num_expected =3D=3D 1:
            return mfs[0] #In this case we also can return
multi_decl_wrapper_t( mfs )
                          #that will behave as an instance of the class
                          #but this is also tricky and dirty to implement i=
t.

        return multi_decl_wrapper_t( mfs )


Here is some possible implementation of s/m select interface:

[2]
class module_builder_t:
    def member_function( self, ... ):
        mf =3D some magic code that according to criteria will return
single instance
              of matched member function or exception will be raised
        return mf

    def member_functions( self, ..., num_expected=3DNone ):
        mfs =3D some magic code that according to criteria will return list=
 of
              all member functions.

        if None is num_expected or num_expected =3D=3D len( mfs ):
            return multi_decl_wrapper_t( mfs )
        else:
            raise RuntimeError("unexpected number of mem functions,
that match criteria: ...." )

Now I am going to compare 2 approaches from an user point of view.


1) In [1] function name is member_function, while in [2] it is member_funct=
ions.
I think that "s" is essential. First time when an user starts to use this A=
PI
it could be confusing. I think he will expect one m.f. but will get some ot=
her
class instance.

2) Return type of functions depends on num_expected argument. This one
could also
confuse.

3) Lets see some ( =3D=3D my :-) ) patterns that an user has, while exporti=
ng C++
library:
    3.1 There are a lot of cases, where I need to work on whole library and=
 I
        don't care on how many instances I work. For example: exclude
all functions
        that takes as second argument pointer to X. In this case I want to =
use
        multi decl select

        mfs =3D module_builder.member_functions( .... )
        mfs.exclude()

    3.1 There are also a lot of special cases. May be in future we will hav=
e
        less of them, but right now they do exists. So single select is ver=
y
        useful here:

        mf =3D module_builder.member_function( .... )
        mf.arguments[3].default_value=3D"std::string()"

        If I will use [1] approach, I always will be forced to add a
"num_expected"
        argument.
The main point in this example is that I do want to know the number of
instances: 1 or many. I think that setting explicit number of expected
instances is annoying. I am not against "num_expected" argument, I
think that Matthias has some use case, where he needs this. ( By the
way I'd like to see it :-) ). So we actually can add it.

4) Small plus that I see for [1] approach is number of API user should
see/learn.
But I don't think that this is makes big difference.

5) How can an user rename all overloaded functions?
   mfs =3D module_builder.member_functions( .... )
   mfs.rename( "......" )
   In both solutions it simple

6) An other problem that I see in [1] approach. We want multi_decl_wrapper_=
t
to behave, as it is an instance of some declaration decorator/wrapper. We c=
an
implement such behaviour only for "set" properties and functions that user
does not care about their return values. "get" properties could not be
implemented
at all.

So, as you can guess I am for different interfaces for single and
multiple selects.
Also, I understand, that I could be wrong and more over I do not get
right an user
desire/needs. I am asking you to try to understand my points. Also, it woul=
d be
nice to see where I am wrong.

Thought, comments?

Thanks

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