[PATCHv2,5/5] gdb: Introduce 'print max-depth' feature
Commit Message
* Eli Zaretskii <eliz@gnu.org> [2019-04-18 05:38:11 +0300]:
> > Date: Thu, 18 Apr 2019 02:07:26 +0100
> > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > Cc: gdb-patches@sourceware.org
> >
> > > "increase ... to increase" sounds awkward and perhaps even confusing.
> > > Can we come up with a better wording?
> >
> > You're right, that doesn't read well, how about simply dropping the
> > '...to increase' like this:
> >
> >
> > +To see the contents of structures that have been hidden the user
> > +can either increase the print max-depth, or they can print the
> > +elements of the structure that are visible, for example
>
> Fine with me, thanks.
Eli, thanks for the feedback.
Having taken Philippe's feedback on board too, I have now adjusted how
I show the effects of the different depth settings to use a table
instead of a set of paragraphs.
I just wanted to run this by you to make sure I hadn't made any silly
style mistakes.
The diff below is only for gdb/doc/gdb.texinfo - this is the only file
I've changed over the previous version of the patch.
thanks,
Andrew
--
Comments
> Date: Thu, 18 Apr 2019 22:52:32 +0100
> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: gdb-patches@sourceware.org, Philippe Waroquiers <philippe.waroquiers@skynet.be>
>
> Eli, thanks for the feedback.
>
> Having taken Philippe's feedback on board too, I have now adjusted how
> I show the effects of the different depth settings to use a table
> instead of a set of paragraphs.
>
> I just wanted to run this by you to make sure I hadn't made any silly
> style mistakes.
>
> The diff below is only for gdb/doc/gdb.texinfo - this is the only file
> I've changed over the previous version of the patch.
LGTM, thanks.
@@ -10560,6 +10560,64 @@
Display the current threshold for printing repeated identical
elements.
+@item set print max-depth @var{depth}
+@item set print max-depth unlimited
+@cindex printing nested structures
+Set the threshold after which nested structures are replaced with
+ellipsis, this can make visualising deeply nested structures easier.
+
+For example, given this C code
+
+@smallexample
+typedef struct s1 @{ int a; @} s1;
+typedef struct s2 @{ s1 b; @} s2;
+typedef struct s3 @{ s2 c; @} s3;
+typedef struct s4 @{ s3 d; @} s4;
+
+s4 var = @{ @{ @{ @{ 3 @} @} @} @};
+@end smallexample
+
+The following table shows how different values of @var{depth} will
+effect how @code{var} is printed by @value{GDBN}:
+
+@multitable @columnfractions .3 .7
+@headitem @var{depth} setting @tab Result of @samp{p var}
+@item unlimited
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@item @code{0}
+@tab @code{$1 = @{...@}}
+@item @code{1}
+@tab @code{$1 = @{d = @{...@}@}}
+@item @code{2}
+@tab @code{$1 = @{d = @{c = @{...@}@}@}}
+@item @code{3}
+@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
+@item @code{4}
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@end multitable
+
+To see the contents of structures that have been hidden the user can
+either increase the print max-depth, or they can print the elements of
+the structure that are visible, for example
+
+@smallexample
+(gdb) set print max-depth 2
+(gdb) p var
+$1 = @{d = @{c = @{...@}@}@}
+(gdb) p var.d
+$2 = @{c = @{b = @{...@}@}@}
+(gdb) p var.d.c
+$3 = @{b = @{a = 3@}@}
+@end smallexample
+
+The pattern used to replace nested structures varies based on
+language, for most languages @code{@{...@}} is used, but Fortran uses
+@code{(...)}.
+
+@item show print max-depth
+Display the current threshold after which nested structures are
+replaces with ellipsis.
+
@item set print null-stop
@cindex @sc{null} elements in arrays
Cause @value{GDBN} to stop printing the characters of an array when the first