OTP-8393 The new function shell:prompt_func/1 and the new application

          configuration parameter shell_prompt_func can be used for
          customizing the Erlang shell prompt.

2 files changed, 58 insertions, 16 deletions

diff --git a/lib/stdlib/doc/src/shell.xml b/lib/stdlib/doc/src/shell.xml
index b8fc64f45e..2a7c5b8c69 100644
--- a/lib/stdlib/doc/src/shell.xml
+++ b/lib/stdlib/doc/src/shell.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2009</year>
+      <year>1996</year><year>2010</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>shell</title>
@@ -739,6 +739,27 @@ loop(N) ->
        returns <c>{error,Reason}</c>.</item>
     </list>
   </section>
+
+  <section>
+    <title>Prompting</title>
+    <p>The default shell prompt function displays the name of the node
+      (if the node can be part of a distributed system) and the
+      current command number. The user can customize the prompt
+      function by calling
+      <c>shell:prompt_func/1</c> or by setting the application
+      configuration parameter <c>shell_prompt_func</c> for the
+      application STDLIB.</p>
+    <p>A customized prompt function is stated as a tuple
+      <c>{Mod,&nbsp;Func}</c>. The function is called as
+      <c>Mod:Func(L)</c>, where <c>L</c> is a list of key-value pairs
+      created by the shell. Currently there is only one pair:
+      <c>{history, N}</c>, where N is the current command number. The
+      function should return a list of characters or an atom. This
+      constraint is due to the Erlang I/O-protocol. Note that in
+      restricted mode the call <c>Mod:Func(L)</c> must be allowed or
+      the default shell prompt function will be called.</p>
+  </section>
+
   <funcs>
     <func>
       <name>history(N) -> integer()</name>
@@ -782,6 +803,19 @@ loop(N) ->
       </desc>
     </func>
     <func>
+      <name>prompt_func(PromptFunc) -> prompt_func()</name>
+      <fsummary>Sets the shell prompt</fsummary>
+      <type>
+        <v>PromptFunc = prompt_func()</v>
+        <v>prompt_func() = default | {Mod, Func}</v>
+        <v>Mod = Func = atom()</v>
+      </type>
+      <desc>
+        <p>Sets the shell prompt function to <c>PromptFunc</c>. The
+          previous prompt function is returned.</p>
+      </desc>
+    </func>
+    <func>
       <name>start_restricted(Module) -> ok | {error, Reason}</name>
       <fsummary>Exits a normal shell and starts a restricted shell.</fsummary>
       <type>
diff --git a/lib/stdlib/doc/src/stdlib_app.xml b/lib/stdlib/doc/src/stdlib_app.xml
index da046b8a8d..a615c1bf88 100644
--- a/lib/stdlib/doc/src/stdlib_app.xml
+++ b/lib/stdlib/doc/src/stdlib_app.xml
@@ -4,23 +4,21 @@
 <appref>
   <header>
     <copyright>
-      <year>2005</year>
-      <year>2007</year>
-      <holder>Ericsson AB, All Rights Reserved</holder>
+      <year>2005</year><year>2010</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-  The contents of this file are subject to the Erlang Public License,
-  Version 1.1, (the "License"); you may not use this file except in
-  compliance with the License. You should have received a copy of the
-  Erlang Public License along with this software. If not, it can be
-  retrieved online at http://www.erlang.org/.
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
 
-  Software distributed under the License is distributed on an "AS IS"
-  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-  the License for the specific language governing rights and limitations
-  under the License.
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
 
-  The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
 
     <title>STDLIB</title>
@@ -63,6 +61,16 @@
         <p>This parameter can be used to determine how many 
           commands are saved by the Erlang shell.</p>
       </item>
+      <tag><c>shell_prompt_func = {Mod, Func} | default</c></tag>
+      <item>
+        <p>where</p>
+        <list type="bulleted">
+          <item><c>Mod = atom()</c></item>
+          <item><c>Func = atom()</c></item>
+        </list>
+        <p>This parameter can be used to set a customized 
+          Erlang shell prompt function.</p>
+      </item>
       <tag><c>shell_saved_results = integer() >= 0</c></tag>
       <item>
         <p>This parameter can be used to determine how many