Re: [PATCH 6/7] [python] API for macros: Add docs.

[Matt Rice <ratmice at gmail dot com>]

On Fri, Aug 26, 2011 at 5:07 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, 26 Aug 2011 04:17:24 -0700
>> From: Matt Rice <ratmice@gmail.com>
>> Cc: gdb-patches@sourceware.org
>>
>> That Symtab_and_line represents that single source line, and if we use
>> 'in effect',
>> without explicitly qualifying the scope under consideration,
>> we leave the user to decide under what scope macros are considered to
>> be in effect.
>> and the user's idea of that scope may or may not match the actual
>> scope that the function uses.
>
> I expect the users to know the definition of a macro scope. ?Are you
> talking about some specific ambiguity, or in general? ?If the former,
> what is the ambiguity?
>
>> e.g. it could be from `0 - line' as it is, or it could be 'macros used
>> from line - line end'
>> (which is a function we do not even implement.)
>
> "In effect" means that a macro _can_ be used in this line. ?I don't
> see any ambiguity here, and it surely isn't the job of the GDB manual
> to teach the rules of defining and using macros.
>
>> >> how about the following.
>> >>
>> >> Returns all of the macros defined before the source line given by the
>> >> @code{gdb.Symtab_and_line}'s @code{line} attribute which are in still
>> >> effect.
>> >
>> > How is this different from my suggestion above?
>>
>> It explicitly specifies a scope as 'defined before the source line given...'
>
> Which is inaccurate (e.g., what about definitions in other files that
> are included by this one?). ?Again, it is not our job to document how
> macros are defined and used, the reader should already know that,
> especially if she is writing a Python script ;-)

at least now I see why you are against adding it...
I think that it's beneath mention that #include causes a macro to be defined.
Anyhow, i don't care enough to argue about it anymore... i'll go with
your original suggestion.

>> >> >> >> +@defmethod Symtab macros
>> >> >> >> +Return all of the macros contained in the symbol table.
>> >> >> >> +@end defmethod
>> >> >> >
>> >> >> > Return what, exactly? only their names? something else?
>> >> >>
>> >> >> i'll try 'Return a list of macro objects for all of the macros
>> >> >> contained in the symbol table.'
>> >> >
>> >> > Based on the example above (which I highly recommend to have in the
>> >> > manual), I'd say "a list of macro objects with their values and
>> >> > include trail".
>> >>
>> >> hrm, except what is above is the output of the string function,
>> >> if you actually print the return value without converting to a string
>> >> it prints something like (<gdb.Macro 0x.......>, <gdb.Macro 0x.....>),
>> >
>> > What are the 0x.... numbers here?
>>
>> The addresses of the python objects.
>
> Then it should be a "list of macro objects specified by their
> addresses".

I don't like this though.... what you're seeing is just a side-effect
of the python print method.
the implementation of a list's str() method to convert to a string
using python's repr()
on it's contents, these are just basic things every python object has,
and will inherit if it doesn't provide a custom implementation.  the
address, and the descriptive string  are things that happen well after
the macros function returns.


(gdb) py print macro_objs
[<gdb.Macro object at 0x7f2c67fc9340>, <gdb.Macro object at 0x7f2c67fc93e8>]
(gdb) py print macro_objs[0]
<gdb.Macro A include_trail=[('/home/ratmice/tests/macro1.c', 7)]>

(gdb) py print repr(macro_objs[0])
<gdb.Macro object at 0x7f2c67fc9340>
(gdb) py print str(macro_objs[0])
<gdb.Macro A include_trail=[('/home/ratmice/tests/macro1.c', 7)]>

(gdb) py help(repr)
repr(...)
    repr(object) -> string

    Return the canonical string representation of the object.
    For most object types, eval(repr(object)) == object.

(gdb) py print help(str)
Help on class str in module __builtin__:

class str(basestring)
 |  str(object) -> string
 |
 |  Return a nice string representation of the object.
 |  If the argument is a string, the return value is the same object.
 |