[python] [patch] set/show extended-prompt

[python] [patch] set/show extended-prompt

[Phil Muldoon]

This patch adds extended-prompt capabilities to GDB.  In addition it
adds a prompt substitution library.  I made the extended-prompt lazily
control the prompt_hook on setting, over controlling it unconditionally.  The
rest of the function remains the same other than in-Python documentation
as was found in Archer.

2011-08-11  Phil Muldoon  <pmuldoon@redhat.com>
            Tom Tromey  <tromey@redhat.com>

        * python/lib/gdb/prompt.py: New file.
        * python/lib/gdb/command/prompt.py: New file.

2011-08-11  Phil Muldoon  <pmuldoon@redhat.com>

        * gdb.python/python.exp: Add extended-prompt tests.

2011-08-11  Phil Muldoon  <pmuldoon@redhat.com>
                                                                                                                                 
        * gdb.texinfo (Prompt): Add set/show extended-prompt                                                                     
        documentation.                                                                                                           
        (Basic Python): Add prompt_hook anchor.                                                                                  
        (Python modules): Reword module text for reflect multiple modules.                                                       
        (gdb.prompt): Document gdb.prompt module.

--

diff --git a/gdb/data-directory/Makefile.in b/gdb/data-directory/Makefile.in
index 11cf2e6..c04aea4 100644
--- a/gdb/data-directory/Makefile.in
+++ b/gdb/data-directory/Makefile.in
@@ -55,8 +55,10 @@ PYTHON_FILES = \
 	gdb/__init__.py \
 	gdb/types.py \
 	gdb/printing.py \
+	gdb/prompt.py \
 	gdb/command/__init__.py \
-	gdb/command/pretty_printers.py
+	gdb/command/pretty_printers.py \
+	gdb/command/prompt.py
 
 FLAGS_TO_PASS = \
 	"prefix=$(prefix)" \
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9a0c8db..dec6933 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19620,6 +19620,34 @@ Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
 @end table
 
+Versions of @value{GDBN} that ship with Python scripting enabled have
+prompt extensions.  The commands for interacting with these extensions
+are:
+
+@table @code
+@kindex set extended-prompt
+@item set extended-prompt @var{prompt}
+Set an extended prompt that allows for substitutions.
+@xref{gdb.prompt} for a list of the flags that can be used for
+substitution.  The prompt is updated with the value of the
+flags each time it is displayed.
+
+For example:
+
+@smallexample
+set extended-prompt Current working directory: \w (gdb)
+@end smallexample
+
+Note that when an extended-prompt is set, it takes control of the
+@var{prompt_hook} hook.  @xref{prompt_hook} for further information.
+
+@kindex show extended-prompt
+@item show extended-prompt
+Prints the extended prompt.  Each time the prompt is displayed, it is
+updated with the current value of the flags passed to it with ``set
+extended-prompt''.
+@end table
+
 @node Editing
 @section Command Editing
 @cindex readline
@@ -21176,6 +21204,8 @@ provided, it is decoded the way that @value{GDBN}'s inbuilt
 @end defun
 
 @defop Operation {@value{GDBN}} prompt_hook current_prompt
+@anchor{prompt_hook}
+
 If @var{prompt_hook} is callable, @value{GDBN} will call the method
 assigned to this operation before a prompt is displayed by
 @value{GDBN}.
@@ -23881,11 +23911,12 @@ top of the source tree to the source search path.
 @subsection Python modules
 @cindex python modules
 
-@value{GDBN} comes with a module to assist writing Python code.
+@value{GDBN} comes with several modules to assist writing Python code.
 
 @menu
 * gdb.printing::       Building and registering pretty-printers.
 * gdb.types::          Utilities for working with types.
+* gdb.prompt::         Utilities for prompt value substitution.
 @end menu
 
 @node gdb.printing
@@ -23953,6 +23984,54 @@ Return @code{True} if @var{type}, assumed to be a type with fields
 Return a Python @code{dictionary} type produced from @var{enum_type}.
 @end table
 
+@node gdb.prompt
+@subsubsection gdb.prompt
+@cindex gdb.prompt
+
+This module provides a method for prompt value-substitution.
+
+@table @code
+@item substitute_prompt (@var{string})
+Return @var{string} with the flags substituted by values.  Some flags
+take arguments.  You can specify arguments to a flag inside ``@{@}''
+immediately following the flag.
+
+The flags you can pass to this function are:
+
+@table @code
+@item @var{\\}
+Substitute a backslash.
+@item @var{\e}
+Substitute an ESC character.
+@item @var{\f}
+Substitute the selected frame; an argument names a frame parameter.
+@item @var{\n}
+Substitute a  newline.
+@item @var{\p}
+Substitute a parameter's value; the argument names the parameter.
+@item @var{\r}
+Substitute a carriage return.
+@item @var{\t}
+Substitute the  selected thread; an argument names a thread parameter.
+@item @var{\v}
+Substitute the version of GDB.
+@item @var{\w}
+Substitute the current working directory.
+@end table
+
+For example:
+
+@smallexample
+substitute_prompt (``frame: \f, print arguments: \p@{print frame-arguments@}'')
+@end smallexample
+
+will return the string:
+
+@smallexample
+``frame: main, print arguments: scalars''
+@end smallexample
+@end table
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters
diff --git a/gdb/python/lib/gdb/command/prompt.py b/gdb/python/lib/gdb/command/prompt.py
index e69de29..4a2d35b 100644
--- a/gdb/python/lib/gdb/command/prompt.py
+++ b/gdb/python/lib/gdb/command/prompt.py
@@ -0,0 +1,66 @@
+# Extended prompt.
+# Copyright (C) 2011 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""GDB command for working with extended prompts."""
+
+import gdb
+import gdb.prompt
+
+class _ExtendedPrompt(gdb.Parameter):
+   
+    """Set the extended prompt.
+
+Usage: set extended-prompt VALUE
+
+Substitutions are applied to VALUE to compute the real prompt.
+
+The currently defined substitutions are:
+
+""" 
+    # Add the prompt library's dynamically generated help to the
+    # __doc__ string.
+    __doc__ = __doc__ + gdb.prompt.prompt_help()
+
+    set_doc = "Set the extended prompt."
+    show_doc = "Show the extended prompt."
+
+    def __init__(self):
+        super(_ExtendedPrompt, self).__init__("extended-prompt",
+                                              gdb.COMMAND_SUPPORT,
+                                              gdb.PARAM_STRING_NOESCAPE)
+        self.value = ''
+        self.hook_set = False
+
+    def get_show_string (self, pvalue):
+        if self.value is not '':
+           return "The extended prompt is: " + self.value
+        else:
+           return "The extended prompt is not set."
+
+    def get_set_string (self):
+        if self.hook_set == False:
+           gdb.prompt_hook = self.before_prompt_hook
+           self.hook_set = True
+        return ""
+
+    def before_prompt_hook(self, current):
+        if self.value is not '':
+            newprompt = gdb.prompt.substitute_prompt(self.value)
+            return newprompt.replace('\\', '\\\\')
+        else:
+            return None
+
+_ExtendedPrompt()
diff --git a/gdb/python/lib/gdb/prompt.py b/gdb/python/lib/gdb/prompt.py
index e69de29..57e43d3 100644
--- a/gdb/python/lib/gdb/prompt.py
+++ b/gdb/python/lib/gdb/prompt.py
@@ -0,0 +1,139 @@
+# Extended prompt utilities.
+# Copyright (C) 2011 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+""" Extended prompt library functions."""
+
+import gdb
+import os
+
+def _prompt_pwd(ignore):
+    "The current working directory."
+    return os.getcwdu()
+
+def _prompt_object_attr(func, what, attr, nattr):
+    """Internal worker for fetching GDB attributes."""
+    if attr is None:
+        attr = nattr
+    try:
+        obj = func()
+    except gdb.error:
+        return '<no %s>' % what
+    if hasattr(obj, attr):
+        result = getattr(obj, attr)
+        if callable(result):
+            result = result()
+        return result
+    else:
+        return '<no attribute %s on current %s>' % (attr, what)
+
+def _prompt_frame(attr):
+    "The selected frame; an argument names a frame parameter."
+    return _prompt_object_attr(gdb.selected_frame, 'frame', attr, 'name')
+
+def _prompt_thread(attr):
+    "The selected thread; an argument names a thread parameter."
+    return _prompt_object_attr(gdb.selected_thread, 'thread', attr, 'num')
+
+def _prompt_version(attr):
+    "The version of GDB."
+    return gdb.VERSION
+
+def _prompt_esc(attr):
+    "The ESC character."
+    return '\033'
+
+def _prompt_bs(attr):
+    "A backslash."
+    return '\\'
+
+def _prompt_n(attr):
+    "A newline."
+    return '\n'
+
+def _prompt_r(attr):
+    "A carriage return."
+    return '\r'
+
+def _prompt_param(attr):
+    "A parameter's value; the argument names the parameter."
+    return gdb.parameter(attr)
+
+prompt_substitutions = {
+    'e': _prompt_esc,
+    '\\': _prompt_bs,
+    'n': _prompt_n,
+    'r': _prompt_r,
+    'v': _prompt_version,
+    'w': _prompt_pwd,
+    'f': _prompt_frame,
+    't': _prompt_thread,
+    'p': _prompt_param
+}
+
+def prompt_help():
+    """Generate help dynamically from the __doc__ strings of attribute
+    functions."""
+
+    result = ''
+    keys = prompt_substitutions.keys()
+    keys.sort()
+    for key in keys:
+        result += '  \\%s\t%s\n' % (key, prompt_substitutions[key].__doc__)
+    result += """
+A substitution can be used in a simple form, like "\\f".
+An argument can also be passed to it, like "\\f{name}".
+The meaning of the argument depends on the particular substitution."""
+    return result
+
+def substitute_prompt(prompt):
+    "Perform substitutions on PROMPT."
+
+    result = ''
+    plen = len(prompt)
+    i = 0
+    while i < plen:
+        if prompt[i] == '\\':
+            i = i + 1
+            if i >= plen:
+                break
+            cmdch = prompt[i]
+
+            if cmdch in prompt_substitutions:
+                cmd = prompt_substitutions[cmdch]
+
+                if i + 1 < plen and prompt[i + 1] == '{':
+                    j = i + 1
+                    while j < plen and prompt[j] != '}':
+                        j = j + 1
+                    # Just ignore formatting errors.
+                    if j >= plen or prompt[j] != '}':
+                        arg = None
+                    else:
+                        arg = prompt[i + 2 : j]
+                        i = j
+                else:
+                    arg = None
+                result += str(cmd(arg))
+            else:
+                # Unrecognized escapes are turned into the escaped
+                # character itself.
+                result += prompt[i]
+        else:
+            result += prompt[i]
+
+        i = i + 1
+
+    return result
diff --git a/gdb/testsuite/gdb.python/python.exp b/gdb/testsuite/gdb.python/python.exp
index 832afc0..c0f064f 100644
--- a/gdb/testsuite/gdb.python/python.exp
+++ b/gdb/testsuite/gdb.python/python.exp
@@ -275,3 +275,36 @@ gdb_test_multiple "end" "end programming" {
 	pass "end programming"
     }
 }
+
+gdb_py_test_multiple "prompt substitution readline" \
+  "python" "" \
+  "import gdb.command.prompt" "" \
+  "end" ""
+
+gdb_test_multiple "set extended-prompt one two three " \
+    "set basic extended prompt" {
+    -re "\[\r\n\]one two three $" {
+	pass "set basic extended prompt"
+    }
+}
+
+gdb_test_multiple "set extended-prompt \\w " \
+    "set extended prompt working directory" {
+    -re "\[\r\n\].*gdb.*testsuite.* $" {
+	pass "set extended prompt working directory"
+    }
+}
+
+gdb_test_multiple "set extended-prompt some param \\p{python print-stack} " \
+    "set extended prompt parameter" {
+    -re "\[\r\n\]some param True $" {
+	pass "set extended prompt parameter"
+    }
+}
+

Re: [python] [patch] set/show extended-prompt

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> Date: Thu, 11 Aug 2011 16:06:45 +0100
> 
> 
> This patch adds extended-prompt capabilities to GDB.  In addition it
> adds a prompt substitution library.  I made the extended-prompt lazily
> control the prompt_hook on setting, over controlling it unconditionally.  The
> rest of the function remains the same other than in-Python documentation
> as was found in Archer.

Thanks, I have a few comments about the documentation part:

> +@xref{gdb.prompt} for a list of the flags that can be used for
                    ^
If you run "make info", it will complain here, because you need to add
a comma after the right brace.

> +               The prompt is updated with the value of the
> +flags each time it is displayed.

Is "flags" a good term?  I think "escape sequence" is better, e.g.:

  Any escape sequences specified as part of the prompt string are
  replaced with the corresponding strings each time the prompt is
  displayed.

> +Note that when an extended-prompt is set, it takes control of the
> +@var{prompt_hook} hook.  @xref{prompt_hook} for further information.
                                              ^
Likewise, you need a comma here.

> +@item show extended-prompt
> +Prints the extended prompt.  Each time the prompt is displayed, it is
> +updated with the current value of the flags passed to it with ``set
> +extended-prompt''.

@code{set extended-prompt}.  And the same comment about "flags"
applies here as well.

> +@smallexample
> +substitute_prompt (``frame: \f, print arguments: \p@{print frame-arguments@}'')
> +@end smallexample

The line inside @example should be broken into two, as it is too long.

> +will return the string:

This line needs an @exdent before it, because it is not a new
paragraph.

> +@smallexample
> +``frame: main, print arguments: scalars''
> +@end smallexample

Aren't these ``..'' quotes left verbatim in the printed version of the
manual?  I think you need literal ".." quotes here, since they are not
converted inside @smallexample.

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Phil Muldoon <pmuldoon@redhat.com>
>> Date: Thu, 11 Aug 2011 16:06:45 +0100
>> 
>> 
>> This patch adds extended-prompt capabilities to GDB.  In addition it
>> adds a prompt substitution library.  I made the extended-prompt lazily
>> control the prompt_hook on setting, over controlling it unconditionally.  The
>> rest of the function remains the same other than in-Python documentation
>> as was found in Archer.
>
> Thanks, I have a few comments about the documentation part:
>
>> +@xref{gdb.prompt} for a list of the flags that can be used for
                     ^
> If you run "make info", it will complain here, because you need to add
> a comma after the right brace.

I normally run 'make info', but my preferred method of proof-reading is
to generate a PDF with 'make pdf'.  This time it looks like I forgot to
sanity check with 'make info', apologies for that.  BTW, it does not
error with 'make pdf', but good point, will adjust.


>> +               The prompt is updated with the value of the
>> +flags each time it is displayed.
>
> Is "flags" a good term?  I think "escape sequence" is better, e.g.:
>
>   Any escape sequences specified as part of the prompt string are
>   replaced with the corresponding strings each time the prompt is
>   displayed.

One of the flags is a specific escape (/e), so I worried about collision
with that term.  That is why ended up using flags.  I'm have no strong
opinions on terminology here, so I will go with what your suggest.

>> +@smallexample
>> +substitute_prompt (``frame: \f, print arguments: \p@{print frame-arguments@}'')
>> +@end smallexample
>
> The line inside @example should be broken into two, as it is too long.

I'm never sure how to break up function examples like these for the
documentation (other than making a smaller example).  Any suggestions on
where to include the break?

>> +@smallexample
>> +``frame: main, print arguments: scalars''
>> +@end smallexample
>
> Aren't these ``..'' quotes left verbatim in the printed version of the
> manual?  I think you need literal ".." quotes here, since they are not
> converted inside @smallexample.

Yes, you are right.  I relied on the emacs Texinfo major mode to do the
right thing here, but I guess it does not in the context of
@smallexample.  When you mean literal quotes, do you mean just pasting
in '"'?

Cheers,

Phil

Re: [python] [patch] set/show extended-prompt

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Thu, 11 Aug 2011 17:59:55 +0100
> 
> >> +@smallexample
> >> +substitute_prompt (``frame: \f, print arguments: \p@{print frame-arguments@}'')
> >> +@end smallexample
> >
> > The line inside @example should be broken into two, as it is too long.
> 
> I'm never sure how to break up function examples like these for the
> documentation (other than making a smaller example).

Just divide it into 2 lines, and if you want to make sure the reader
doesn't perceive the line break as significant, say something like
"this is one long line" in parentheses.

> Any suggestions on where to include the break?

It is not important, other than keeping each line shorter than 64
characters.

> >> +``frame: main, print arguments: scalars''
> >> +@end smallexample
> >
> > Aren't these ``..'' quotes left verbatim in the printed version of the
> > manual?  I think you need literal ".." quotes here, since they are not
> > converted inside @smallexample.
> 
> Yes, you are right.  I relied on the emacs Texinfo major mode to do the
> right thing here, but I guess it does not in the context of
> @smallexample.

Texinfo mode only does the opposite: inserts ``..'' when you type
"..".

> When you mean literal quotes, do you mean just pasting in '"'?

Yes.

Re: [python] [patch] set/show extended-prompt

[Matt Rice]

On Thu, Aug 11, 2011 at 8:06 AM, Phil Muldoon <pmuldoon@redhat.com> wrote:

> +@item @var{\e}
> +Substitute an ESC character.

> +def _prompt_esc(attr):
> +    "The ESC character."
> +    return '\033'

won't usage of this (without an equivalent to bash's \[ \]) mess up
the prompt width calculation?
maybe something like...

@item @var{\[}
Begins a sequence of non-printing characters.
@item @var{\]}
Ends a sequence of non-printing characters.

def _prompt_nonprinting_begin(attr):
   "Begins a sequence of non-printing characters."
   return '\001'

def _prompt_nonprinting_end(attr):
   "Ends a sequence of non-printing characters."
   return '\002'

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Matt Rice <ratmice@gmail.com> writes:

> On Thu, Aug 11, 2011 at 8:06 AM, Phil Muldoon <pmuldoon@redhat.com> wrote:
>
>> +@item @var{\e}
>> +Substitute an ESC character.
>
>> +def _prompt_esc(attr):
>> +    "The ESC character."
>> +    return '\033'
>
> won't usage of this (without an equivalent to bash's \[ \]) mess up
> the prompt width calculation?
> maybe something like...

Not sure what you mean by width in this context.  I checked strlen and
for /efoo/e and it reported the length at five?

Cheers

Phil

> @item @var{\[}
> Begins a sequence of non-printing characters.
> @item @var{\]}
> Ends a sequence of non-printing characters.
>
> def _prompt_nonprinting_begin(attr):
>    "Begins a sequence of non-printing characters."
>    return '\001'
>
> def _prompt_nonprinting_end(attr):
>    "Ends a sequence of non-printing characters."
>    return '\002'

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Phil Muldoon <pmuldoon@redhat.com> writes:

> Matt Rice <ratmice@gmail.com> writes:
>
>> On Thu, Aug 11, 2011 at 8:06 AM, Phil Muldoon <pmuldoon@redhat.com> wrote:
>>
>>> +@item @var{\e}
>>> +Substitute an ESC character.
>>
>>> +def _prompt_esc(attr):
>>> +    "The ESC character."
>>> +    return '\033'
>>
>> won't usage of this (without an equivalent to bash's \[ \]) mess up
>> the prompt width calculation?
>> maybe something like...
>
> Not sure what you mean by width in this context.  I checked strlen and
> for /efoo/e and it reported the length at five?

We talked a little about this on irc.  In the submitted case, readline
is counting the actual \e as a character, so when it re-displays a prompt
it calculates the prompt length incorrectly (including the ESC).  Matt's
approach nullifies this.  I'll adjust the patch, documentation and tests
accordingly

Cheers,

Phil.

>> @item @var{\[}
>> Begins a sequence of non-printing characters.
>> @item @var{\]}
>> Ends a sequence of non-printing characters.
>>
>> def _prompt_nonprinting_begin(attr):
>>    "Begins a sequence of non-printing characters."
>>    return '\001'
>>
>> def _prompt_nonprinting_end(attr):
>>    "Ends a sequence of non-printing characters."
>>    return '\002'

Re: [python] [patch] set/show extended-prompt

[Tom Tromey]

>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> writes:

Phil> This patch adds extended-prompt capabilities to GDB.  In addition
Phil> it adds a prompt substitution library.  I made the extended-prompt
Phil> lazily control the prompt_hook on setting, over controlling it
Phil> unconditionally.  The rest of the function remains the same other
Phil> than in-Python documentation as was found in Archer.

The code bits are ok.

This needs a NEWS entry.

The doc/ChangeLog entry looks messed up to me.

Tom

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Tom Tromey <tromey@redhat.com> writes:

>>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> writes:
>
> Phil> This patch adds extended-prompt capabilities to GDB.  In addition
> Phil> it adds a prompt substitution library.  I made the extended-prompt
> Phil> lazily control the prompt_hook on setting, over controlling it
> Phil> unconditionally.  The rest of the function remains the same other
> Phil> than in-Python documentation as was found in Archer.
>
> The code bits are ok.

I am going to submit another patch with Matt's suggested changes to the
escape issue.  I expect this will be a formality, but I would prefer an
explicit OK with the new changes.


> This needs a NEWS entry.


Agreed I forgot about the NEWS entry (again).

> The doc/ChangeLog entry looks messed up to me.


In which way?  I generated ChangeLogs with each change in texinfo mode
with add-changelog-mode and checked the reference back to the entry.
They seem correct?  I am not sure what is messed-up?

Cheers,

Phil

Re: [python] [patch] set/show extended-prompt

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Fri, 12 Aug 2011 23:20:12 +0100
> 
> > The doc/ChangeLog entry looks messed up to me.
> 
> 
> In which way?  I generated ChangeLogs with each change in texinfo mode
> with add-changelog-mode and checked the reference back to the entry.
> They seem correct?  I am not sure what is messed-up?

I think Tom means the extra whitespace, which I guess was inserted by
your mailer or something?  Other than that, I see no problems with the
log entries.

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Tom Tromey <tromey@redhat.com> writes:

>>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> writes:
>
> Phil> This patch adds extended-prompt capabilities to GDB.  In addition
> Phil> it adds a prompt substitution library.  I made the extended-prompt
> Phil> lazily control the prompt_hook on setting, over controlling it
> Phil> unconditionally.  The rest of the function remains the same other
> Phil> than in-Python documentation as was found in Archer.
>
> The code bits are ok.
>
> This needs a NEWS entry.

Thanks, I have added Matt Rice's non-printing character suggestion.  So
that needs to be approved.  I've also added a NEWS entry, and removed
the white-spaces from the ChangeLog (bizarre, not sure how that
happened).

I've updated the documentation to reflect the required changes too.

OK?

Cheers,

Phil

2011-08-15  Phil Muldoon  <pmuldoon@redhat.com>
            Tom Tromey  <tromey@redhat.com>
            Matt Rice <ratmice@gmail.com>

        * python/lib/gdb/prompt.py: New file.
        * python/lib/gdb/command/prompt.py: New file.
        * NEWS: Document set extended-prompt and gdb.prompt library

2011-08-15  Phil Muldoon  <pmuldoon@redhat.com>

        * gdb.python/python.exp: Add extended-prompt tests.

2011-08-15  Phil Muldoon  <pmuldoon@redhat.com>

        * gdb.texinfo (Prompt): Add set/show extended-prompt
        documentation
        (Basic Python): Add prompt_hook anchor.
        (Python modules): Reword module text for reflect multiple modules.
        (gdb.prompt): Document gdb.prompt module.

--

diff --git a/gdb/NEWS b/gdb/NEWS
index 089e6ce..255a22e 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -23,6 +23,14 @@
   ** A prompt subsitution hook (prompt_hook) is now available to the
      Python API.
 
+  ** A new command set/show extended-prompt has been added.
+
+  ** A new Python module, gdb.prompt has been added to the GDB Python
+     modules library.  This module provides functionality for
+     escape sequentions in prompts (used by set/show
+     extended-prompt).  These escape sequences are replaced by their
+     corresponding value.
+
   ** Python commands and convenience-functions located in
     'data-directory'/python/gdb/command and
     'data-directory'/python/gdb/function are now automatically loaded
diff --git a/gdb/data-directory/Makefile.in b/gdb/data-directory/Makefile.in
index 11cf2e6..c04aea4 100644
--- a/gdb/data-directory/Makefile.in
+++ b/gdb/data-directory/Makefile.in
@@ -55,8 +55,10 @@ PYTHON_FILES = \
 	gdb/__init__.py \
 	gdb/types.py \
 	gdb/printing.py \
+	gdb/prompt.py \
 	gdb/command/__init__.py \
-	gdb/command/pretty_printers.py
+	gdb/command/pretty_printers.py \
+	gdb/command/prompt.py
 
 FLAGS_TO_PASS = \
 	"prefix=$(prefix)" \
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b477cf3..af34e38 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19620,6 +19620,35 @@ Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
 @end table
 
+Versions of @value{GDBN} that ship with Python scripting enabled have
+prompt extensions.  The commands for interacting with these extensions
+are:
+
+@table @code
+@kindex set extended-prompt
+@item set extended-prompt @var{prompt}
+Set an extended prompt that allows for substitutions.
+@xref{gdb.prompt}, for a list of escape sequences that can be used for
+substitution.  Any escape sequences specified as part of the prompt
+string are replaced with the corresponding strings each time the prompt
+is displayed.
+
+For example:
+
+@smallexample
+set extended-prompt Current working directory: \w (gdb)
+@end smallexample
+
+Note that when an extended-prompt is set, it takes control of the
+@var{prompt_hook} hook.  @xref{prompt_hook}, for further information.
+
+@kindex show extended-prompt
+@item show extended-prompt
+Prints the extended prompt.  Any escape sequences specified as part of
+the prompt string with @code{set extended-prompt}, are replaced with the
+corresponding strings each time the prompt is displayed.
+@end table
+
 @node Editing
 @section Command Editing
 @cindex readline
@@ -21176,6 +21205,8 @@ provided, it is decoded the way that @value{GDBN}'s inbuilt
 @end defun
 
 @defop Operation {@value{GDBN}} prompt_hook current_prompt
+@anchor{prompt_hook}
+
 If @var{prompt_hook} is callable, @value{GDBN} will call the method
 assigned to this operation before a prompt is displayed by
 @value{GDBN}.
@@ -23887,11 +23918,12 @@ top of the source tree to the source search path.
 @subsection Python modules
 @cindex python modules
 
-@value{GDBN} comes with a module to assist writing Python code.
+@value{GDBN} comes with several modules to assist writing Python code.
 
 @menu
 * gdb.printing::       Building and registering pretty-printers.
 * gdb.types::          Utilities for working with types.
+* gdb.prompt::         Utilities for prompt value substitution.
 @end menu
 
 @node gdb.printing
@@ -23959,6 +23991,59 @@ Return @code{True} if @var{type}, assumed to be a type with fields
 Return a Python @code{dictionary} type produced from @var{enum_type}.
 @end table
 
+@node gdb.prompt
+@subsubsection gdb.prompt
+@cindex gdb.prompt
+
+This module provides a method for prompt value-substitution.
+
+@table @code
+@item substitute_prompt (@var{string})
+Return @var{string} with escape sequences substituted by values.  Some
+escape sequences take arguments.  You can specify arguments inside
+``@{@}'' immediately following the escape sequence.
+
+The escape sequences you can pass to this function are:
+
+@table @code
+@item \\
+Substitute a backslash.
+@item \e
+Substitute an ESC character.
+@item \f
+Substitute the selected frame; an argument names a frame parameter.
+@item \n
+Substitute a newline.
+@item \p
+Substitute a parameter's value; the argument names the parameter.
+@item \r
+Substitute a carriage return.
+@item \t
+Substitute the selected thread; an argument names a thread parameter.
+@item \v
+Substitute the version of GDB.
+@item \w
+Substitute the current working directory.
+@item \[
+Begin a sequence of non-printing characters.
+@item \]
+End a sequence of non-printing characters.
+@end table
+
+For example:
+
+@smallexample
+substitute_prompt (``frame: \f,
+                   print arguments: \p@{print frame-arguments@}'')
+@end smallexample
+
+@exdent will return the string:
+
+@smallexample
+"frame: main, print arguments: scalars"
+@end smallexample
+@end table
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters
diff --git a/gdb/python/lib/gdb/command/prompt.py b/gdb/python/lib/gdb/command/prompt.py
index e69de29..35e522e 100644
--- a/gdb/python/lib/gdb/command/prompt.py
+++ b/gdb/python/lib/gdb/command/prompt.py
@@ -0,0 +1,66 @@
+# Extended prompt.
+# Copyright (C) 2011 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""GDB command for working with extended prompts."""
+
+import gdb
+import gdb.prompt
+
+class _ExtendedPrompt(gdb.Parameter):
+
+    """Set the extended prompt.
+
+Usage: set extended-prompt VALUE
+
+Substitutions are applied to VALUE to compute the real prompt.
+
+The currently defined substitutions are:
+
+"""
+    # Add the prompt library's dynamically generated help to the
+    # __doc__ string.
+    __doc__ = __doc__ + gdb.prompt.prompt_help()
+
+    set_doc = "Set the extended prompt."
+    show_doc = "Show the extended prompt."
+
+    def __init__(self):
+        super(_ExtendedPrompt, self).__init__("extended-prompt",
+                                              gdb.COMMAND_SUPPORT,
+                                              gdb.PARAM_STRING_NOESCAPE)
+        self.value = ''
+        self.hook_set = False
+
+    def get_show_string (self, pvalue):
+        if self.value is not '':
+           return "The extended prompt is: " + self.value
+        else:
+           return "The extended prompt is not set."
+
+    def get_set_string (self):
+        if self.hook_set == False:
+           gdb.prompt_hook = self.before_prompt_hook
+           self.hook_set = True
+        return ""
+
+    def before_prompt_hook(self, current):
+        if self.value is not '':
+            newprompt = gdb.prompt.substitute_prompt(self.value)
+            return newprompt.replace('\\', '\\\\')
+        else:
+            return None
+
+_ExtendedPrompt()
diff --git a/gdb/python/lib/gdb/prompt.py b/gdb/python/lib/gdb/prompt.py
index e69de29..296df3a 100644
--- a/gdb/python/lib/gdb/prompt.py
+++ b/gdb/python/lib/gdb/prompt.py
@@ -0,0 +1,149 @@
+# Extended prompt utilities.
+# Copyright (C) 2011 Free Software Foundation, Inc.
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+""" Extended prompt library functions."""
+
+import gdb
+import os
+
+def _prompt_pwd(ignore):
+    "The current working directory."
+    return os.getcwdu()
+
+def _prompt_object_attr(func, what, attr, nattr):
+    """Internal worker for fetching GDB attributes."""
+    if attr is None:
+        attr = nattr
+    try:
+        obj = func()
+    except gdb.error:
+        return '<no %s>' % what
+    if hasattr(obj, attr):
+        result = getattr(obj, attr)
+        if callable(result):
+            result = result()
+        return result
+    else:
+        return '<no attribute %s on current %s>' % (attr, what)
+
+def _prompt_frame(attr):
+    "The selected frame; an argument names a frame parameter."
+    return _prompt_object_attr(gdb.selected_frame, 'frame', attr, 'name')
+
+def _prompt_thread(attr):
+    "The selected thread; an argument names a thread parameter."
+    return _prompt_object_attr(gdb.selected_thread, 'thread', attr, 'num')
+
+def _prompt_version(attr):
+    "The version of GDB."
+    return gdb.VERSION
+
+def _prompt_esc(attr):
+    "The ESC character."
+    return '\033'
+
+def _prompt_bs(attr):
+    "A backslash."
+    return '\\'
+
+def _prompt_n(attr):
+    "A newline."
+    return '\n'
+
+def _prompt_r(attr):
+    "A carriage return."
+    return '\r'
+
+def _prompt_param(attr):
+    "A parameter's value; the argument names the parameter."
+    return gdb.parameter(attr)
+
+def _prompt_noprint_begin(attr):
+    "Begins a sequence of non-printing characters."
+    return '\001'
+
+def _prompt_noprint_end(attr):
+     "Ends a sequence of non-printing characters."
+     return '\002'
+
+prompt_substitutions = {
+    'e': _prompt_esc,
+    '\\': _prompt_bs,
+    'n': _prompt_n,
+    'r': _prompt_r,
+    'v': _prompt_version,
+    'w': _prompt_pwd,
+    'f': _prompt_frame,
+    't': _prompt_thread,
+    'p': _prompt_param,
+    '[': _prompt_noprint_begin,
+    ']': _prompt_noprint_end
+}
+
+def prompt_help():
+    """Generate help dynamically from the __doc__ strings of attribute
+    functions."""
+
+    result = ''
+    keys = prompt_substitutions.keys()
+    keys.sort()
+    for key in keys:
+        result += '  \\%s\t%s\n' % (key, prompt_substitutions[key].__doc__)
+    result += """
+A substitution can be used in a simple form, like "\\f".
+An argument can also be passed to it, like "\\f{name}".
+The meaning of the argument depends on the particular substitution."""
+    return result
+
+def substitute_prompt(prompt):
+    "Perform substitutions on PROMPT."
+
+    result = ''
+    plen = len(prompt)
+    i = 0
+    while i < plen:
+        if prompt[i] == '\\':
+            i = i + 1
+            if i >= plen:
+                break
+            cmdch = prompt[i]
+
+            if cmdch in prompt_substitutions:
+                cmd = prompt_substitutions[cmdch]
+
+                if i + 1 < plen and prompt[i + 1] == '{':
+                    j = i + 1
+                    while j < plen and prompt[j] != '}':
+                        j = j + 1
+                    # Just ignore formatting errors.
+                    if j >= plen or prompt[j] != '}':
+                        arg = None
+                    else:
+                        arg = prompt[i + 2 : j]
+                        i = j
+                else:
+                    arg = None
+                result += str(cmd(arg))
+            else:
+                # Unrecognized escapes are turned into the escaped
+                # character itself.
+                result += prompt[i]
+        else:
+            result += prompt[i]
+
+        i = i + 1
+
+    return result
diff --git a/gdb/testsuite/gdb.python/python.exp b/gdb/testsuite/gdb.python/python.exp
index 832afc0..4da3c88 100644
--- a/gdb/testsuite/gdb.python/python.exp
+++ b/gdb/testsuite/gdb.python/python.exp
@@ -275,3 +275,29 @@ gdb_test_multiple "end" "end programming" {
 	pass "end programming"
     }
 }
+
+gdb_py_test_multiple "prompt substitution readline" \
+  "python" "" \
+  "import gdb.command.prompt" "" \
+  "end" ""
+
+gdb_test_multiple "set extended-prompt one two three " \
+    "set basic extended prompt" {
+    -re "\[\r\n\]one two three $" {
+	pass "set basic extended prompt"
+    }
+}
+
+gdb_test_multiple "set extended-prompt \\w " \
+    "set extended prompt working directory" {
+    -re "\[\r\n\].*gdb.*testsuite.* $" {
+	pass "set extended prompt working directory"
+    }
+}
+
+gdb_test_multiple "set extended-prompt some param \\p{python print-stack} " \
+    "set extended prompt parameter" {
+    -re "\[\r\n\]some param True $" {
+	pass "set extended prompt parameter"
+    }
+}

Re: [python] [patch] set/show extended-prompt

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 15 Aug 2011 15:02:44 +0100
> 
> > This needs a NEWS entry.
> 
> Thanks, I have added Matt Rice's non-printing character suggestion.  So
> that needs to be approved.  I've also added a NEWS entry, and removed
> the white-spaces from the ChangeLog (bizarre, not sure how that
> happened).
> 
> I've updated the documentation to reflect the required changes too.
> 
> OK?

Yes, but I have one more wish, if I may:

> +@item \[
> +Begin a sequence of non-printing characters.
> +@item \]
> +End a sequence of non-printing characters.

It would be useful to tell something regarding the display of the
non-printing characters themselves, and how to specify them in the
string.

Thanks.

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Eli Zaretskii <eliz@gnu.org> writes:

>> +@item \[
>> +Begin a sequence of non-printing characters.
>> +@item \]
>> +End a sequence of non-printing characters.
>
> It would be useful to tell something regarding the display of the
> non-printing characters themselves, and how to specify them in the
> string.
>
> Thanks.

Updated (doc-only) patch.  What do you think?

Cheers,

Phil

--

diff --git a/gdb/NEWS b/gdb/NEWS
index 089e6ce..255a22e 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -23,6 +23,14 @@
   ** A prompt subsitution hook (prompt_hook) is now available to the
      Python API.
 
+  ** A new command set/show extended-prompt has been added.
+
+  ** A new Python module, gdb.prompt has been added to the GDB Python
+     modules library.  This module provides functionality for
+     escape sequentions in prompts (used by set/show
+     extended-prompt).  These escape sequences are replaced by their
+     corresponding value.
+
   ** Python commands and convenience-functions located in
     'data-directory'/python/gdb/command and
     'data-directory'/python/gdb/function are now automatically loaded
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b477cf3..bdaea3d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19620,6 +19620,35 @@ Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth.
 Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}}
 @end table
 
+Versions of @value{GDBN} that ship with Python scripting enabled have
+prompt extensions.  The commands for interacting with these extensions
+are:
+
+@table @code
+@kindex set extended-prompt
+@item set extended-prompt @var{prompt}
+Set an extended prompt that allows for substitutions.
+@xref{gdb.prompt}, for a list of escape sequences that can be used for
+substitution.  Any escape sequences specified as part of the prompt
+string are replaced with the corresponding strings each time the prompt
+is displayed.
+
+For example:
+
+@smallexample
+set extended-prompt Current working directory: \w (gdb)
+@end smallexample
+
+Note that when an extended-prompt is set, it takes control of the
+@var{prompt_hook} hook.  @xref{prompt_hook}, for further information.
+
+@kindex show extended-prompt
+@item show extended-prompt
+Prints the extended prompt.  Any escape sequences specified as part of
+the prompt string with @code{set extended-prompt}, are replaced with the
+corresponding strings each time the prompt is displayed.
+@end table
+
 @node Editing
 @section Command Editing
 @cindex readline
@@ -21176,6 +21205,8 @@ provided, it is decoded the way that @value{GDBN}'s inbuilt
 @end defun
 
 @defop Operation {@value{GDBN}} prompt_hook current_prompt
+@anchor{prompt_hook}
+
 If @var{prompt_hook} is callable, @value{GDBN} will call the method
 assigned to this operation before a prompt is displayed by
 @value{GDBN}.
@@ -23887,11 +23918,12 @@ top of the source tree to the source search path.
 @subsection Python modules
 @cindex python modules
 
-@value{GDBN} comes with a module to assist writing Python code.
+@value{GDBN} comes with several modules to assist writing Python code.
 
 @menu
 * gdb.printing::       Building and registering pretty-printers.
 * gdb.types::          Utilities for working with types.
+* gdb.prompt::         Utilities for prompt value substitution.
 @end menu
 
 @node gdb.printing
@@ -23959,6 +23991,62 @@ Return @code{True} if @var{type}, assumed to be a type with fields
 Return a Python @code{dictionary} type produced from @var{enum_type}.
 @end table
 
+@node gdb.prompt
+@subsubsection gdb.prompt
+@cindex gdb.prompt
+
+This module provides a method for prompt value-substitution.
+
+@table @code
+@item substitute_prompt (@var{string})
+Return @var{string} with escape sequences substituted by values.  Some
+escape sequences take arguments.  You can specify arguments inside
+``@{@}'' immediately following the escape sequence.
+
+The escape sequences you can pass to this function are:
+
+@table @code
+@item \\
+Substitute a backslash.
+@item \e
+Substitute an ESC character.
+@item \f
+Substitute the selected frame; an argument names a frame parameter.
+@item \n
+Substitute a newline.
+@item \p
+Substitute a parameter's value; the argument names the parameter.
+@item \r
+Substitute a carriage return.
+@item \t
+Substitute the selected thread; an argument names a thread parameter.
+@item \v
+Substitute the version of GDB.
+@item \w
+Substitute the current working directory.
+@item \[
+Begin a sequence of non-printing characters.  These sequences are
+typically used with the ESC character, and are not counted in the string
+length.  Example,: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a
+blue-colored ``(gdb)'' prompt where the length is three.
+@item \]
+End a sequence of non-printing characters.
+@end table
+
+For example:
+
+@smallexample
+substitute_prompt (``frame: \f,
+                   print arguments: \p@{print frame-arguments@}'')
+@end smallexample
+
+@exdent will return the string:
+
+@smallexample
+"frame: main, print arguments: scalars"
+@end smallexample
+@end table
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters

Re: [python] [patch] set/show extended-prompt

[Eli Zaretskii]

> From: Phil Muldoon <pmuldoon@redhat.com>
> Cc: tromey@redhat.com, gdb-patches@sourceware.org
> Date: Tue, 16 Aug 2011 12:18:17 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> +@item \[
> >> +Begin a sequence of non-printing characters.
> >> +@item \]
> >> +End a sequence of non-printing characters.
> >
> > It would be useful to tell something regarding the display of the
> > non-printing characters themselves, and how to specify them in the
> > string.
> >
> > Thanks.
> 
> Updated (doc-only) patch.  What do you think?

Thanks, I'm happy now.

Re: [python] [patch] set/show extended-prompt

[Phil Muldoon]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Phil Muldoon <pmuldoon@redhat.com>
>> Cc: tromey@redhat.com, gdb-patches@sourceware.org
>> Date: Tue, 16 Aug 2011 12:18:17 +0100
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> +@item \[
>> >> +Begin a sequence of non-printing characters.
>> >> +@item \]
>> >> +End a sequence of non-printing characters.
>> >
>> > It would be useful to tell something regarding the display of the
>> > non-printing characters themselves, and how to specify them in the
>> > string.
>> >
>> > Thanks.
>> 
>> Updated (doc-only) patch.  What do you think?
>
> Thanks, I'm happy now.

So committed, thanks.

Cheers,

Phil

Re: [python] [patch] set/show extended-prompt

[Tom Tromey]

>>>>> "Phil" == Phil Muldoon <pmuldoon@redhat.com> writes:

Phil> Thanks, I have added Matt Rice's non-printing character suggestion.  So
Phil> that needs to be approved.  I've also added a NEWS entry, and removed
Phil> the white-spaces from the ChangeLog (bizarre, not sure how that
Phil> happened).

The code bits are ok.  Thanks.

Tom