diff options
Diffstat (limited to 'lib/stdlib/doc/src/epp.xml')
| -rw-r--r-- | lib/stdlib/doc/src/epp.xml | 241 |
1 files changed, 159 insertions, 82 deletions
diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml index df7bf883fc..1dc0161398 100644 --- a/lib/stdlib/doc/src/epp.xml +++ b/lib/stdlib/doc/src/epp.xml @@ -1,23 +1,24 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</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/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - 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. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -27,165 +28,241 @@ <docno>1</docno> <approved>Kenneth Lundin</approved> <checked></checked> - <date>97-01-31</date> + <date>1997-01-31</date> <rev>B</rev> - <file>epp.sgml</file> + <file>epp.xml</file> </header> <module>epp</module> - <modulesummary>An Erlang Code Preprocessor</modulesummary> + <modulesummary>An Erlang code preprocessor.</modulesummary> <description> - <p>The Erlang code preprocessor includes functions which are used - by <c>compile</c> to preprocess macros and include files before - the actual parsing takes place.</p> + <p>The Erlang code preprocessor includes functions that are used by the + <seealso marker="compiler:compile"><c>compile</c></seealso> + module to preprocess macros and include files before + the parsing takes place.</p> + <p>The Erlang source file <marker - id="encoding"><em>encoding</em></marker> is selected by a + id="encoding"/><em>encoding</em> is selected by a comment in one of the first two lines of the source file. The - first string that matches the regular expression + first string matching the regular expression <c>coding\s*[:=]\s*([-a-zA-Z0-9])+</c> selects the encoding. If - the matching string is not a valid encoding it is ignored. The - valid encodings are <c>Latin-1</c> and <c>UTF-8</c> where the - case of the characters can be chosen freely. Examples:</p> - <pre> -%% coding: utf-8 -%% For this file we have chosen encoding = Latin-1 + the matching string is not a valid encoding, it is ignored. The + valid encodings are <c>Latin-1</c> and <c>UTF-8</c>, where the + case of the characters can be chosen freely.</p> + + <p><em>Examples:</em></p> + + <pre> +%% coding: utf-8</pre> + + <pre> +%% For this file we have chosen encoding = Latin-1</pre> + + <pre> %% -*- coding: latin-1 -*-</pre> </description> + <datatypes> <datatype> <name name="macros"></name> </datatype> <datatype> <name name="epp_handle"></name> - <desc><p>Handle to the epp server.</p></desc> + <desc><p>Handle to the <c>epp</c> server.</p></desc> </datatype> <datatype> <name name="source_encoding"></name> </datatype> </datatypes> + <funcs> <func> - <name name="open" arity="2"/> - <name name="open" arity="3"/> - <fsummary>Open a file for preprocessing</fsummary> + <name name="close" arity="1"/> + <fsummary>Close the preprocessing of the file associated with <c>Epp</c>. + </fsummary> + <desc> + <p>Closes the preprocessing of a file.</p> + </desc> + </func> + + <func> + <name name="default_encoding" arity="0"/> + <fsummary>Return the default encoding of Erlang source files.</fsummary> + <desc> + <p>Returns the default encoding of Erlang source files.</p> + </desc> + </func> + + <func> + <name name="encoding_to_string" arity="1"/> + <fsummary>Return a string representation of an encoding.</fsummary> + <desc> + <p>Returns a string representation of an encoding. The string + is recognized by + <seealso marker="#read_encoding/1"><c>read_encoding/1,2</c></seealso>, + <seealso marker="#read_encoding_from_binary/1"> + <c>read_encoding_from_binary/1,2</c></seealso>, and + <seealso marker="#set_encoding/1"><c>set_encoding/1,2</c></seealso> + as a valid encoding.</p> + </desc> + </func> + + <func> + <name name="format_error" arity="1"/> + <fsummary>Format an error descriptor.</fsummary> + <desc> + <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns + a string that + describes the error or warning. This function is usually + called implicitly when processing an <c>ErrorInfo</c> + structure (see section + <seealso marker="#errorinfo">Error Information</seealso>).</p> + </desc> + </func> + + <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 specified in + <c><anno>Options</anno></c>, the return value is + <c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead + of <c>{ok, <anno>Epp</anno>}</c>.</p> </desc> </func> + <func> - <name name="close" arity="1"/> - <fsummary>Close the preprocessing of the file associated with <c>Epp</c></fsummary> + <name name="open" arity="2"/> + <fsummary>Open a file for preprocessing.</fsummary> <desc> - <p>Closes the preprocessing of a file.</p> + <p>Equivalent to + <c>epp:open([{name, FileName}, {includes, IncludePath}])</c>.</p> </desc> </func> + <func> - <name name="parse_erl_form" arity="1"/> - <fsummary>Return the next Erlang form from the opened Erlang source file</fsummary> + <name name="open" arity="3"/> + <fsummary>Open a file for preprocessing.</fsummary> <desc> - <p>Returns the next Erlang form from the opened Erlang source file. - The tuple <c>{eof, <anno>Line</anno>}</c> is returned at end-of-file. The first - form corresponds to an implicit attribute <c>-file(File,1).</c>, where - <c>File</c> is the name of the file.</p> + <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}, + {macros, PredefMacros}])</c>.</p> </desc> </func> + <func> - <name name="parse_file" arity="3"/> - <fsummary>Preprocess and parse an Erlang source file</fsummary> + <name name="parse_erl_form" arity="1"/> + <fsummary>Return the next Erlang form from the opened Erlang source file. + </fsummary> + <type name="warning_info"/> <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> + <p>Returns the next Erlang form from the opened Erlang source file. + Tuple <c>{eof, <anno>Line</anno>}</c> is returned at the end of the + file. The first form corresponds to an implicit attribute + <c>-file(File,1).</c>, where <c>File</c> is the file name.</p> </desc> </func> + <func> - <name name="default_encoding" arity="0"/> - <fsummary>Return the default encoding of Erlang source files</fsummary> + <name name="parse_file" arity="2"/> + <fsummary>Preprocess and parse an Erlang source file.</fsummary> <desc> - <p>Returns the default encoding of Erlang source files.</p> + <p>Preprocesses and parses an Erlang source file. + Notice that tuple <c>{eof, <anno>Line</anno>}</c> returned at the + end of the file is included as a "form".</p> + <p>If <c>extra</c> is specified in + <c><anno>Options</anno></c>, the return value is + <c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead + of <c>{ok, [<anno>Form</anno>]}</c>.</p> </desc> </func> + <func> - <name name="encoding_to_string" arity="1"/> - <fsummary>Return a string representation of an encoding</fsummary> + <name name="parse_file" arity="3"/> + <fsummary>Preprocess and parse an Erlang source file.</fsummary> <desc> - <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> + <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath}, + {macros, PredefMacros}])</c>.</p> </desc> </func> + <func> <name name="read_encoding" arity="1"/> <name name="read_encoding" arity="2"/> - <fsummary>Read the encoding from a file</fsummary> + <fsummary>Read the encoding from a file.</fsummary> <desc> <p>Read the <seealso marker="#encoding">encoding</seealso> from a file. Returns the read encoding, or <c>none</c> if no - valid encoding was found.</p> - <p>The option <c>in_comment_only</c> is <c>true</c> by + valid encoding is found.</p> + <p>Option <c>in_comment_only</c> is <c>true</c> by default, which is correct for Erlang source files. If set to - <c>false</c> the encoding string does not necessarily have to + <c>false</c>, the encoding string does not necessarily have to occur in a comment.</p> </desc> </func> + <func> <name name="read_encoding_from_binary" arity="1"/> <name name="read_encoding_from_binary" arity="2"/> - <fsummary>Read the encoding from a binary</fsummary> + <fsummary>Read the encoding from a binary.</fsummary> <desc> <p>Read the <seealso marker="#encoding">encoding</seealso> from a binary. Returns the read encoding, or <c>none</c> if no - valid encoding was found.</p> - <p>The option <c>in_comment_only</c> is <c>true</c> by + valid encoding is found.</p> + <p>Option <c>in_comment_only</c> is <c>true</c> by default, which is correct for Erlang source files. If set to - <c>false</c> the encoding string does not necessarily have to + <c>false</c>, the encoding string does not necessarily have to occur in a comment.</p> </desc> </func> + <func> <name name="set_encoding" arity="1"/> - <fsummary>Read and set the encoding of an IO device</fsummary> + <fsummary>Read and set the encoding of an I/O 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 + an I/O device and sets the encoding of the device + accordingly. The position of the I/O 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 default encoding.</p> + encoding can be read from the I/O device, the encoding of the + I/O device is set to the default encoding.</p> <p>Returns the read encoding, or <c>none</c> if no valid - encoding was found.</p> + encoding is found.</p> </desc> </func> + <func> - <name name="format_error" arity="1"/> - <fsummary>Format an error descriptor</fsummary> + <name name="set_encoding" arity="2"/> + <fsummary>Read and set the encoding of an I/O device.</fsummary> <desc> - <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns - a string which - describes the error or warning. This function is usually - called implicitly when processing an <c>ErrorInfo</c> - structure (see below).</p> + <p>Reads the <seealso marker="#encoding">encoding</seealso> from + an I/O device and sets the encoding of the device + accordingly. The position of the I/O device referenced by + <c><anno>File</anno></c> is not affected. If no valid + encoding can be read from the I/O device, the encoding of the + I/O device is set to the + <seealso marker="#encoding">encoding</seealso> specified by + <c><anno>Default</anno></c>.</p> + <p>Returns the read encoding, or <c>none</c> if no valid + encoding is found.</p> </desc> </func> </funcs> <section> <title>Error Information</title> - <p>The <c>ErrorInfo</c> mentioned above is the standard - <c>ErrorInfo</c> structure which is returned from all IO - modules. It has the following format: - </p> + <marker id="errorinfo"/> + <p><c>ErrorInfo</c> is the standard <c>ErrorInfo</c> structure that is + returned from all I/O modules. The format is as follows:</p> <code type="none"> - {ErrorLine, Module, ErrorDescriptor} </code> - <p>A string which describes the error is obtained with the following call: - </p> +{ErrorLine, Module, ErrorDescriptor}</code> + <p>A string describing the error is obtained with the following call:</p> <code type="none"> - Module:format_error(ErrorDescriptor) </code> +Module:format_error(ErrorDescriptor)</code> </section> <section> <title>See Also</title> - <p><seealso marker="erl_parse">erl_parse(3)</seealso></p> + <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso></p> </section> </erlref> |