[RFAv3 3/3] NEWS and documentation for $_gdb_setting and $_gdb_int_setting.

[Philippe Waroquiers <philippe dot waroquiers at skynet dot be>]

gdb/ChangeLog
2019-06-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* NEWS: Mention $_gdb_setting and $_gdb_int_setting.

gdb/doc/ChangeLog
2019-06-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Convenience Funs): Document the new
	$_gdb_setting and $_gdb_int_setting convenience functions.
---
 gdb/NEWS            |  5 ++++
 gdb/doc/gdb.texinfo | 66 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 34c544c3d5..d17d37ceff 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -11,6 +11,11 @@
   scripts that should work error-free with many different versions,
   such as in system-wide init files.
 
+* New built-in convenience functions $_gdb_setting and $_gdb_int_setting
+  provide access to values of the GDB settings.  They are handy
+  for changing the logic of user defined commands depending on the
+  current GDB settings.
+
 * GDB now supports Thread Local Storage (TLS) variables on several
   FreeBSD architectures (amd64, i386, powerpc, riscv).  Other
   architectures require kernel changes.  TLS is not yet supported for
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 299c4a12a1..e31f43f417 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -11820,9 +11820,73 @@ $3 = void
 $4 = 1
 @end smallexample
 
+@item $_gdb_setting (@var{setting})
+@findex $_gdb_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as a string.
+@var{setting} is any setting that can be used in a @code{set} or
+@code{show} command (@pxref{Controlling GDB}).
+@code{$_gdb_setting} works for for any setting kind.  In particular,
+it also works for non string setting kinds such as boolean, auto boolean
+and integer settings.
+
+@smallexample
+(@value{GDBP}) show print frame-arguments
+Printing of non-scalar frame arguments is "scalars".
+(@value{GDBP}) p $_gdb_setting("print frame-arguments")
+$2 = "scalars"
+(@value{GDBP}) p $_gdb_setting("height")
+$3 = "30"
+(@value{GDBP})
+@end smallexample
+
+@item $_gdb_int_setting (@var{setting})
+@findex $_gdb_int_setting@r{, convenience function}
+Return the value of the @value{GDBN} @var{setting} as an integer.
+This only works for boolean, auto boolean and integer settings.
+The boolean values @code{off} and @code{on} are converted to
+the integer values @code{0} and @code{1}.  The value @code{auto} is
+converted to the value @code{2}.
+Some integer settings accepts an @code{unlimited} value.
+Depending on the setting, the @code{set} command also accepts
+the value @code{0} or the value @code{@minus{}1} as a synonym for
+@code{unlimited}.
+For example, @code{set height unlimited} is equivalent to
+@code{set height 0}.
+Some other settings accepting the @code{unlimited} value
+are using the value @code{0} to literally mean zero.
+For example, @code{set history size 0} indicates to not
+record any @value{GDBN} commands in the command history.
+For such settings, @code{@minus{}1} is the synonym
+for @code{unlimited}.
+
+The function @code{$_gdb_int_setting} converts the unlimited value
+to a @code{0} or a @code{@minus{}1} value according to what the
+@code{set} command uses.
+
+@smallexample
+@group
+(@value{GDBP}) p $_gdb_setting("height")
+$3 = "30"
+(@value{GDBP}) p $_gdb_int_setting("height")
+$4 = 30
+(@value{GDBP}) set height unlimited
+(@value{GDBP}) p $_gdb_setting("height")
+$5 = "unlimited"
+(@value{GDBP}) p $_gdb_int_setting("height")
+$6 = 0
+@end group
+@group
+(@value{GDBP}) p $_gdb_setting("history size")
+$7 = "unlimited"
+(@value{GDBP}) p $_gdb_int_setting("history size")
+$8 = -1
+(@value{GDBP})
+@end group
+@end smallexample
+
 @end table
 
-These functions require @value{GDBN} to be configured with
+The following functions require @value{GDBN} to be configured with
 @code{Python} support.
 
 @table @code
-- 
2.20.1