Re: [PATCH] python: Add qualified parameter to gdb.Breakpoint

[Simon Marchi <simon.marchi@polymtl.ca>]

On 2017-12-08 07:05, Pedro Alves wrote:
> That was fast.  :-)  Thanks!
> 
> See comments about the docs below.
> 
> The code looks fine to me, except a formatting nit.
> 
>> --- a/gdb/doc/python.texi
>> +++ b/gdb/doc/python.texi
>> @@ -4885,7 +4885,7 @@ create both breakpoints and watchpoints.  The 
>> second accepts separate Python
>>  arguments similar to @ref{Explicit Locations} and can only be used to 
>> create
>>  breakpoints.
>> 
>> -@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, 
>> internal @r{][}, temporary @r{]})
>> +@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, 
>> internal @r{][}, temporary @r{][}, qualified @r{]})
>>  Create a new breakpoint according to @var{spec}, which is a string 
>> naming the
>>  location of a breakpoint, or an expression that defines a watchpoint. 
>> The
>>  contents can be any location recognized by the @code{break} command 
>> or, in the
>> @@ -4909,14 +4909,20 @@ The optional @var{temporary} argument makes 
>> the breakpoint a temporary
>>  breakpoint.  Temporary breakpoints are deleted after they have been 
>> hit.  Any
>>  further access to the Python breakpoint after it has been hit will 
>> result in a
>>  runtime error (as that breakpoint has now been automatically 
>> deleted).
>> +
>> +The optional @var{qualified} argument is a boolean that allows 
>> restricting the
>> +breakpoint to free-functions.
> 
> "free-functions" is incorrect.  With:
> 
>   struct A { void func (); }                  // #1
>   namespace B { struct A { void func (); } }  // #2
> 
> "b -q A::func()" only matches #1 while
> "b A::func()" matches both #1 and #2.
> 
> and A::func() above is not a free function.
> 
> Here's what we say for -qualified in the explicit locations part of the
> manual:
> 
> ~~~
> @item -qualified
> 
> This flag makes @value{GDBN} interpret a function name specified with
> @kbd{-function} as a complete fully-qualified name.
> 
> For example, assuming a C@t{++} program with symbols named
> @code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified
> -function B::func}} command sets a breakpoint on @code{B::func}, only.
> 
> (Note: the @kbd{-qualified} option can precede a linespec as well
> (@pxref{Linespec Locations}), so the particular example above could be
> simplified as @w{@kbd{break -qualified B::func}}.)
> ~~~
> 
> There's similar text in the linespecs part of the manual and also
> in "help break".  See:
>   $ git show a20714ff39f6 -- doc/gdb.texinfo NEWS break.c
> 
> So we either need to clarify that in the Python bits too,
> or some do some xref'ing.

Agreed, I didn't like that wording either.  I had only found the 
Linespec Locations page, which doesn't specifically say "fully-qualified 
name", but mentions free-function (though it's in an example, not a 
formal definition).  How is this?

The optional @var{qualified} argument is a boolean that allows 
interpreting
the function passed in @code{spec} as a fully-qualified name.  It is 
equivalent
to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and
@ref{Explicit Locations}).

>  It is equivalent to @code{break}'s
>> +@code{-qualified} flag (@pxref{Linespec Locations}).
>> +
>>  @end defun
>> 
>> -@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, 
>> label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][})
>> +@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, 
>> label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary  @r{][}, 
>> qualified @r{]})
>>  Create a new explicit location breakpoint (@pxref{Explicit 
>> Locations})
>>  according to the specifications contained in the key words 
>> @var{source},
>>  @var{function}, @var{label} and @var{line}.
> 
> Should @var{qualified} be added to this list too?

It is mentioned in the paragraph below.

> (BTW, noticed a typo in this paragraph:
> 
>   "create a new a explicit location"
> 
> the second "a" is spurious.)

That text changed based on Eli's comments, but thanks anyway.

>> 
>> -@var{internal} and @var{temporary} have the same usage as explained 
>> previously.
>> +@var{internal}, @var{temporary} and @var{qualified} have the same 
>> usage as
>> +explained previously.
>>  @end defun
>> 
>>  The available types are represented by constants defined in the 
>> @code{gdb}
> 
>> @@ -759,6 +761,9 @@ bppy_init (PyObject *self, PyObject *args, 
>> PyObject *kwargs)
>>  	case bp_breakpoint:
>>  	  {
>>  	    event_location_up location;
>> +	    symbol_name_match_type func_name_match_type
>> +	      = qualified ? symbol_name_match_type::FULL
>> +		  : symbol_name_match_type::WILD;
> 
> Should wrap the multi-line expression in ()s:
> 
>   symbol_name_match_type func_name_match_type
>     = (qualified ? symbol_name_match_type::FULL
>        : symbol_name_match_type::WILD);
> 
> Though I prefer breaking ternary operators like this:
> 
>   symbol_name_match_type func_name_match_type
>     = (qualified
>        ? symbol_name_match_type::FULL
>        : symbol_name_match_type::WILD);
> 
> because it makes it look more obviously like
> 
>  if COND
>    THEN
>    ELSE

Done.

Thanks,

Simon