diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/diameter/doc/src/diameter_make.xml | 78 | ||||
| -rw-r--r-- | lib/diameter/doc/src/seealso.ent | 2 |
2 files changed, 68 insertions, 12 deletions
diff --git a/lib/diameter/doc/src/diameter_make.xml b/lib/diameter/doc/src/diameter_make.xml index 2e69fca1ae..c8c0f2fbc7 100644 --- a/lib/diameter/doc/src/diameter_make.xml +++ b/lib/diameter/doc/src/diameter_make.xml @@ -64,19 +64,48 @@ interface.</p> <funcs> <func> -<name>codec(File :: iolist() | binary(), [Opt]) -> ok | {ok, Ret} | {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. +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> can have the following types.</p> +<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 | beam</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>, <c>.hrl</c> and <c>.beam</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 returned in the <c>Out</c> list in the +order specified. +Format options default to <c>erl</c> and <c>hrl</c> (in this order) if +unspecified.</p> + +<p> +The <c>parsed</c> format is an internal representation that can be +passed to &format; and &flatten;, while the <c>forms</c> format is +only intended for debugging purposes. +Output for the <c>erl</c> and <c>hrl</c> formats are returned as +iolists, while the <c>beam</c> format returns a <c>{module(), +binary()}</c> tuple.</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> @@ -93,14 +122,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 erl and hrl source as two iolists rather than writing them to -the filesystem.</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> @@ -118,7 +148,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, "-"} @@ -147,6 +177,34 @@ The <c>&dict_name;</c> of a literal input dictionary defaults to </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> + </funcs> <!-- ===================================================================== --> @@ -155,11 +213,7 @@ The <c>&dict_name;</c> of a literal input dictionary defaults to <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 --> |