Make the scanned form of the io_lib format strings available for processing

This adds three new functions to io_lib - scan_format/2, unscan_format/1,
and build_text/1 - which expose the parsed form of the format control
sequences to make it possible to easily modify or filter the input to
io_lib:format/2. This can e.g. be used in order to replace unbounded-size
control sequences like ~w or ~p with corresponding depth-limited ~W and ~P
before doing the actual formatting.

2 files changed, 71 insertions, 2 deletions

diff --git a/lib/stdlib/doc/src/io.xml b/lib/stdlib/doc/src/io.xml
index a28180b42a..8ebfdb2e7f 100644
--- a/lib/stdlib/doc/src/io.xml
+++ b/lib/stdlib/doc/src/io.xml
@@ -505,7 +505,8 @@ ok
             <p>Writes the data with standard syntax in the same way as
               <c>~w</c>, but breaks terms whose printed representation
               is longer than one line into many lines and indents each
-              line sensibly. It also tries to detect lists of
+              line sensibly. Left justification is not supported.
+              It also tries to detect lists of
               printable characters and to output these as strings. The
               Unicode translation modifier is used for determining
               what characters are printable. For example:</p>
diff --git a/lib/stdlib/doc/src/io_lib.xml b/lib/stdlib/doc/src/io_lib.xml
index 3312b08064..2117d66381 100644
--- a/lib/stdlib/doc/src/io_lib.xml
+++ b/lib/stdlib/doc/src/io_lib.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2013</year>
+      <year>1996</year><year>2014</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -59,6 +59,35 @@
     <datatype>
       <name name="latin1_string"/>
     </datatype>
+    <datatype>
+      <name name="format_spec"/>
+      <desc><p>Description:</p>
+      <list type="bulleted">
+        <item><p><c>control_char</c> is the type of control
+          sequence: <c>$P</c>, <c>$w</c>, and so on;</p>
+        </item>
+        <item><p><c>args</c> is a list of the arguments used by the
+          control sequence, or an empty list if the control sequence
+          does not take any arguments;</p>
+        </item>
+        <item><p><c>width</c> is the field width;</p>
+        </item>
+        <item><p><c>adjust</c> is the adjustment;</p>
+        </item>
+        <item><p><c>precision</c> is the precision of the printed
+          argument;</p>
+        </item>
+        <item><p><c>pad_char</c> is the padding character;</p>
+        </item>
+        <item><p><c>encoding</c> is set to <c>true</c> if the translation
+          modifier <c>t</c> is present;</p>
+        </item>
+        <item><p><c>strings</c> is set to <c>false</c> if the modifier
+          <c>l</c> is present.</p>
+        </item>
+      </list>
+      </desc>
+    </datatype>
   </datatypes>
   <funcs>
     <func>
@@ -260,6 +289,45 @@
       </desc>
     </func>
     <func>
+      <name name="scan_format" arity="2"/>
+      <fsummary>Parse all control sequences in the format string</fsummary>
+      <desc>
+        <p>Returns a list corresponding to the given format string,
+          where control sequences have been replaced with
+          corresponding tuples. This list can be passed to <seealso
+          marker="#build_text/1">io_lib:build_text/1</seealso> to have
+          the same effect as <c>io_lib:format(Format, Args)</c>, or to
+          <seealso
+          marker="#unscan_format/1">io_lib:unscan_format/1</seealso>
+          in order to get the corresponding pair of <c>Format</c> and
+          <c>Args</c> (with every <c>*</c> and corresponding argument
+          expanded to numeric values).</p>
+        <p>A typical use of this function is to replace unbounded-size
+          control sequences like <c>~w</c> and <c>~p</c> with the
+          depth-limited variants <c>~W</c> and <c>~P</c> before
+          formatting to text, e.g. in a logger.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="unscan_format" arity="1"/>
+      <fsummary>Revert a pre-parsed format list to a plain character list
+                and a list of arguments</fsummary>
+      <desc>
+        <p>See <seealso
+          marker="#scan_format/2">io_lib:scan_format/2</seealso> for
+          details.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="build_text" arity="1"/>
+      <fsummary>Build the output text for a pre-parsed format list</fsummary>
+      <desc>
+        <p>See <seealso
+          marker="#scan_format/2">io_lib:scan_format/2</seealso> for
+          details.</p>
+      </desc>
+    </func>
+    <func>
       <name name="indentation" arity="2"/>
       <fsummary>Indentation after printing string</fsummary>
       <desc>