From f3cee0e9f409c5850709f11ba15cec22d7387401 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Mon, 3 Mar 2014 13:50:23 +0100
Subject: epp: Make it possible to specify a default encoding

In the next commit, we will need a way to tell epp which the
default encoding should be for files that have no encoding comment.

We could add new open() and parse_file() functions with one
extra argument for the encoding, but there are already too many
variants.

To avoid having to add an additional argument to epp:open() and
epp:parse_file() each time new options are needed, introduce
epp:open/1 and epp:parse_file/2 that takes a property list with
options. Also support the new 'default_encoding' option for specifying
the default encoding for source files.

Thanks to Richard Carlsson for the idea and the implementation
of the new functionality in epp.erl.
---
 lib/stdlib/doc/src/epp.xml | 56 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 51 insertions(+), 5 deletions(-)

(limited to 'lib/stdlib/doc')

diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml
index cf33530395..50baad04a9 100644
--- a/lib/stdlib/doc/src/epp.xml
+++ b/lib/stdlib/doc/src/epp.xml
@@ -63,12 +63,30 @@
     </datatype>
   </datatypes>
   <funcs>
+    <func>
+      <name name="open" arity="1"/>
+      <fsummary>Open a file for preprocessing</fsummary>
+      <desc>
+        <p>Opens a file for preprocessing.</p>
+	<p>If <c>extra</c> is given in
+	<c><anno>Options</anno></c>, the return value will be
+	<c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead
+	of <c>{ok, <anno>Epp</anno>}</c>.</p>
+      </desc>
+    </func>
     <func>
       <name name="open" arity="2"/>
+      <fsummary>Open a file for preprocessing</fsummary>
+      <desc>
+        <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}])</c>.</p>
+      </desc>
+    </func>
+    <func>
       <name name="open" arity="3"/>
       <fsummary>Open a file for preprocessing</fsummary>
       <desc>
-        <p>Opens a file for preprocessing.</p>
+        <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath},
+	{macros, PredefMacros}])</c>.</p>
       </desc>
     </func>
     <func>
@@ -89,12 +107,24 @@
       </desc>
     </func>
     <func>
-      <name name="parse_file" arity="3"/>
+      <name name="parse_file" arity="2"/>
       <fsummary>Preprocess and parse an Erlang source file</fsummary>
       <desc>
         <p>Preprocesses and parses an Erlang source file.
-          Note that the tuple <c>{eof, <anno>Line</anno>}</c> returned at end-of-file is
-          included as a "form".</p>
+	Note that the tuple <c>{eof, <anno>Line</anno>}</c> returned
+	at end-of-file is included as a "form".</p>
+	<p>If <c>extra</c> is given in
+	<c><anno>Options</anno></c>, the return value will be
+	<c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead
+	of <c>{ok, [<anno>Form</anno>]}</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name name="parse_file" arity="3"/>
+      <fsummary>Preprocess and parse an Erlang source file</fsummary>
+      <desc>
+        <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath},
+	{macros, PredefMacros}])</c>.</p>
       </desc>
     </func>
     <func>
@@ -111,7 +141,7 @@
         <p>Returns a string representation of an encoding. The string
         is recognized by <c>read_encoding/1,2</c>,
         <c>read_encoding_from_binary/1,2</c>, and
-        <c>set_encoding/1</c> as a valid encoding.</p>
+        <c>set_encoding/1,2</c> as a valid encoding.</p>
       </desc>
     </func>
     <func>
@@ -156,6 +186,22 @@
           encoding was found.</p>
       </desc>
     </func>
+    <func>
+      <name name="set_encoding" arity="2"/>
+      <fsummary>Read and set the encoding of an IO device</fsummary>
+      <desc>
+        <p>Reads the <seealso marker="#encoding">encoding</seealso> from
+          an IO device and sets the encoding of the device
+          accordingly. The position of the IO device referenced by
+          <c><anno>File</anno></c> is not affected. If no valid
+          encoding can be read from the IO device the encoding of the
+          IO device is set to the
+	  <seealso marker="#encoding">encoding</seealso> given by
+	  <c><anno>Default</anno></c>.</p>
+        <p>Returns the read encoding, or <c>none</c> if no valid
+          encoding was found.</p>
+      </desc>
+    </func>
     <func>
       <name name="format_error" arity="1"/>
       <fsummary>Format an error descriptor</fsummary>
-- 
cgit v1.2.3