aboutsummaryrefslogtreecommitdiffstats
path: root/lib/diameter/doc/src
diff options
context:
space:
mode:
authorAnders Svensson <[email protected]>2013-12-02 09:42:34 +0100
committerAnders Svensson <[email protected]>2013-12-02 09:42:34 +0100
commit2b8c7d30e6c24ebc4c8d78c16d8033ff0d6c106e (patch)
tree8cb99cd58347852794fcc495fcc6548af4a80c01 /lib/diameter/doc/src
parent2bc1b1c962adf7849abb5a8399706aad708c5969 (diff)
parent2eb76ba556b8775cffc94eac26b448eac70af267 (diff)
downloadotp-2b8c7d30e6c24ebc4c8d78c16d8033ff0d6c106e.tar.gz
otp-2b8c7d30e6c24ebc4c8d78c16d8033ff0d6c106e.tar.bz2
otp-2b8c7d30e6c24ebc4c8d78c16d8033ff0d6c106e.zip
Merge branch 'anders/diameter/dictionary_make/OTP-11348' into maint
* anders/diameter/dictionary_make/OTP-11348: Return compilable forms instead of beam Document diameter_make:format/1 and diameter_make:flatten/1 Fix diameter_make:flatten/1 Modify type that currently causes dialyzer woe Simplify and extend diameter_make interface Add diameter_make:flatten/1, remove reformat/1 Adapt compiler suite to diameter_make Remove dead code from codec suite Extend diameter_make:codec/2 Don't pollute process dictionary in diameter_codegen:from_dict/4 Make forms a separate output from diameter_codegen Remove last remnants of "spec" Write as last step in code generation Change extensions for debug output: .spec/forms -> .D/F
Diffstat (limited to 'lib/diameter/doc/src')
-rw-r--r--lib/diameter/doc/src/diameter_make.xml92
-rw-r--r--lib/diameter/doc/src/seealso.ent2
2 files changed, 84 insertions, 10 deletions
diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml
index ec71251be1..68780b1e05 100644
--- a/lib/diameter/doc/src/diameter_make.xml
+++ b/lib/diameter/doc/src/diameter_make.xml
@@ -1,5 +1,7 @@
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
+ <!ENTITY compile_forms2
+ '<seealso marker="compiler:compile#forms-2">compile:forms/2</seealso>'>
<!ENTITY filename
'<seealso marker="kernel:file#type-name">file:name()</seealso>'>
<!ENTITY dictionary
@@ -64,16 +66,47 @@ interface.</p>
<funcs>
<func>
-<name>codec(Path::string(), [Opt]) -> ok | {error, Reason}</name>
+<name>codec(File :: iolist() | binary(), [Opt]) -> ok
+ | {ok, [Out]}
+ | {error, Reason}</name>
<fsummary>Compile a dictionary file into Erlang source.</fsummary>
<desc>
<p>
-Compile a single dictionary file to Erlang source.
-<c>Opt</c> can have the following types.</p>
+Compile a single dictionary file.
+The input <c>File</c> can be either a path or a literal dictionary,
+the occurrence of newline (ascii NL) or carriage return (ascii CR)
+identifying the latter.
+<c>Opt</c> determines the format of the results and whether they are
+written to file or returned, and can have the following types.</p>
<taglist>
+<tag><c>parse | forms | erl | hrl</c></tag>
+<item>
+<p>
+Specifies an output format.
+Whether the output is returned or written to file depends on whether
+or not option <c>return</c> is specified.
+When written to file, the resulting file(s) will have extensions
+<c>.D</c>, <c>.F</c>, <c>.erl</c>, and <c>.hrl</c>
+respectively, basenames defaulting to <c>dictionary</c> if the input
+dictionary is literal and does not specify <c>&dict_name;</c>.
+When returned, results are in the order of the corresponding format
+options.
+Format options default to <c>erl</c> and <c>hrl</c> (in this order) if
+unspecified.</p>
+
+<p>
+The <c>parse</c> format is an internal representation that can be
+passed to &flatten; and &format;, while the <c>forms</c> format can be
+passed to &compile_forms2;.
+The <c>erl</c> and <c>hrl</c> formats are returned as
+iolists.</p>
+<!-- That codec/2 can take the parsed format is undocumented, and
+ options name and inherits have no effect in this case. -->
+</item>
+
<tag><c>{include, string()}</c></tag>
<item>
<p>
@@ -90,7 +123,15 @@ Multiple <c>include</c> options can be specified.</p>
<item>
<p>
Write generated source to the specified directory.
-Defaults to the current working directory.</p>
+Defaults to the current working directory.
+Has no effect if option <c>return</c> is specified.</p>
+</item>
+
+<tag><c>return</c></tag>
+<item>
+<p>
+Return results in a <c>{ok, [Out]}</c> tuple instead of writing to
+file and returning <c>ok</c>.</p>
</item>
<tag><c>{name|prefix, string()}</c></tag>
@@ -108,7 +149,7 @@ Transform the input dictionary before compilation, appending
<c>&dict_inherits;</c> of the specified string.</p>
<p>
-Two forms of <c>@inherits</c> have special meaning:</p>
+Two forms have special meaning:</p>
<pre>
{inherits, "-"}
@@ -127,6 +168,41 @@ Multiple <c>inherits</c> options can be specified.</p>
</taglist>
+<p>
+Note that a dictionary's <c>&dict_name;</c>, together with the
+<c>outdir</c> option, determine the output paths when the
+<c>return</c> option is not specified.
+The <c>&dict_name;</c> of a literal input dictionary defaults to
+<c>dictionary</c>.</p>
+
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>format(Parsed) -> iolist()</name>
+<fsummary>Format a parsed dictionary.</fsummary>
+<desc>
+<p>
+Turns a parsed dictionary, as returned by &codec;, back into the
+dictionary format.</p>
+</desc>
+</func>
+
+<!-- ===================================================================== -->
+
+<func>
+<name>flatten(Parsed) -> term()</name>
+<fsummary>Flatten a parsed dictionary.</fsummary>
+<desc>
+
+<p>
+Reconstitute a parsed dictionary, as returned by &codec;, without
+using <c>&dict_inherits;</c>.
+That is, construct an equivalent dictionary in which all AVP's are
+definined in the dictionary itself.
+The return value is also a parsed dictionary.</p>
</desc>
</func>
@@ -138,11 +214,7 @@ Multiple <c>inherits</c> options can be specified.</p>
<title>BUGS</title>
<p>
-All options are string-valued.
-In particular, it is not currently possible to specify
-an &dict_inherits; module as an atom(), or a path as an arbitrary
-&filename;</p>
-
+Unrecognized options are silently ignored.</p>
</section>
<!-- ===================================================================== -->
diff --git a/lib/diameter/doc/src/seealso.ent b/lib/diameter/doc/src/seealso.ent
index 76b9823f79..d3305853af 100644
--- a/lib/diameter/doc/src/seealso.ent
+++ b/lib/diameter/doc/src/seealso.ent
@@ -115,6 +115,8 @@ significant.
<!-- diameter_make -->
<!ENTITY make_codec '<seealso marker="diameter_make#codec-2">diameter_make:codec/2</seealso>'>
+<!ENTITY make_format '<seealso marker="diameter_make#format-1">diameter_make:format/1</seealso>'>
+<!ENTITY make_flatten '<seealso marker="diameter_make#flatten-1">diameter_make:flatten/1</seealso>'>
<!-- diameter_transport -->