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.

1 files changed, 37 insertions, 3 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>