diff options
Diffstat (limited to 'lib/asn1/doc')
| -rw-r--r-- | lib/asn1/doc/src/asn1_ug.xml | 120 | ||||
| -rw-r--r-- | lib/asn1/doc/src/asn1ct.xml | 55 |
2 files changed, 61 insertions, 114 deletions
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 6cb251c3e2..a0ab98cf7a 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -324,13 +324,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn are several places to search in. The compiler will always search the current directory first.</p> </item> - <tag><c>+compact_bit_string</c></tag> - <item> - <p>Gives the user the option to use a compact format of the BIT - STRING type to save memory space, typing space and - increase encode/decode performance, for details see - <seealso marker="#BIT STRING">BIT STRING </seealso>type section.</p> - </item> <tag><c>+der</c></tag> <item> <p>DER encoding rule. Only when using <c>-ber</c> option.</p> @@ -352,22 +345,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn list or a binary. Earlier versions of the compiler ignored those following bytes.</p> </item> - <tag><c>{inline,OutputName}</c></tag> - <item> - <p>Compiling with this option gives one output module - containing all asn1 run-time functionality. The asn1 specs - are provided in a target module <c>Module.set.asn</c> as - described in the <seealso marker="asn1ct#asn1set">reference manual</seealso>. The name of the resulting module - containing generated encode/decode functions and inlined - run-time functions will be <c>OutputName.erl</c>. The - merging/inlining of code is done by the <c>igor</c> module - of <c>syntax_tools</c>. By default the functions generated - from the first asn1 spec in the <c>.set.asn</c> are - exported, unless a <c>{export,[atom()]}</c> or - <c>{export_all,true}</c> option are provided. The list of - atoms are names of choosen asn1 specs from the - <c>.set.asn</c> file. See further examples of usage <seealso marker="#inlineExamples">below</seealso></p> - </item> <tag><c>+'Any Erlc Option'</c></tag> <item> <p>You may add any option to the Erlang compiler when @@ -454,21 +431,8 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre> any reason. Maybe you need to compile the same specs for different encoding/decoding standards.</item> <item>You want only one resulting module.</item> - <item>If it is crucial to have a minimal system. Using - <c>{inline,OutputModule}</c> includes all necessary run-time - functions of the asn1 application, but skips those modules not - used.</item> - <item>Upgrading issues: Even if you upgrade your Erlang system - you may want to continue running the old asn1 run-time - functionality.</item> - <item>Performance issues: If you have an asn1 system with a lot - of cross references you may gain in performance. Measurements - must be done for each case.</item> </list> - <p>You may choose either the plain multi file compilation that just - merges the chosen asn1 specs or the <c>{inline,OutputModule}</c> - that also includes the used asn1 run-time functionality.</p> - <p>For both cases you need to specify which asn1 specs you will + <p>You need to specify which asn1 specs you will compile in a module that must have the extension <c>.set.asn</c>. You chose name of the module and provide the names of the asn1 specs. For instance, if you have the specs @@ -482,17 +446,7 @@ File3.asn </pre> <code type="none"> ~> erlc MyModule.set.asn </code> <p>the result will be one merged module <c>MyModule.erl</c> with - the generated code from the three asn1 specs. But if you compile - with:</p> - <code type="none"> -~> erlc +"{inline,'OutputModule'}" MyModule.set.asn </code> - <p>the result will be a module <c>OutputModule.erl</c> that - contains all encode/decode functions for the three asn1 specs and - all used functions from the asn1 run-time modules, in this case - <c>asn1rt_ber_bin</c>. In the former case all encode/decode - functions are exported but in the latter only the encode/decode - functions of the first spec in the <c>.set.asn</c>, i.e. those - from <c>File1.asn</c>. + the generated code from the three asn1 specs. </p> </section> @@ -688,7 +642,7 @@ Day1 = saturday, <section> <marker id="BIT STRING"></marker> - <title>BIT STRING </title> + <title>BIT STRING</title> <p>The BIT STRING type can be used to model information which is made up of arbitrary length series of bits. It is intended to be used for a selection of flags, not for binary files. <br></br> @@ -699,56 +653,66 @@ Day1 = saturday, Bits1 ::= BIT STRING Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)} </pre> - <p>There are four different notations available for representation of + <p>There are five different notations available for representation of BIT STRING values in Erlang and as input to the encode functions.</p> <list type="ordered"> - <item>A list of binary digits (0 or 1).</item> - <item>A hexadecimal number (or an integer). This format should be - avoided, since it is easy to misinterpret a <c>BIT STRING</c> - value in this format. This format may be withdrawn in a future - release.</item> + <item>A bitstring. By default, a BIT STRING with no + symbolic names will be decoded to an Erlang bitstring.</item> <item>A list of atoms corresponding to atoms in the <c>NamedBitList</c> - in the BIT STRING definition.</item> + in the BIT STRING definition. A BIT STRING with symbolic + names will always be decoded to this format.</item> + <item>A list of binary digits (0 or 1). This format is always + accepted as input to the encode functions. A BIT STRING will + be decoded to this format if <em>legacy_bit_string</em> option + has been given. <em>This format may be withdrawn in a future + release.</em> + </item> <item>As <c>{Unused,Binary}</c> where <c>Unused</c> denotes how - many trailing zero-bits 0 to 7 that are unused in the least - significant byte in <c>Binary</c>. This notation is only - available when the ASN.1 files have been compiled with the - <em>+compact_bit_string</em> flag in the option list. In - this case it is possible to use all kinds of notation when - encoding. But the result when decoding is always in the - compact form. The benefit from this notation is a more - compact notation when one has large BIT STRINGs. The - encode/decode performance is also much better in the case of - large BIT STRINGs. </item> + many trailing zero-bits 0 to 7 that are unused in the least + significant byte in <c>Binary</c>. This format is always + accepted as input to the encode functions. A BIT STRING will + be decoded to this format if <em>compact_bit_string</em> has + been given. <em>This format may be withdrawn in a future + release.</em> + </item> + <item>A hexadecimal number (or an integer). This format should be + avoided, since it is easy to misinterpret a <c>BIT STRING</c> + value in this format. <em>This format may be withdrawn in a future + release.</em> + </item> </list> <note> - <p>Note that it is advised not to use the integer format of a - BIT STRING, see the second point above.</p> + <p>It is recommended to either use the bitstring format (for + BIT STRINGs with no symbolic names) or a list of symbolic + names (for BIT STRINGs with symbolic names). The other formats + should be avoided since they may be withdrawn in a future + release. + </p> </note> <pre> -Bits1Val1 = [0,1,0,1,1], +Bits1Val1 = <<0:1,1:1,0:1,1:1,1:1>>, Bits1Val2 = 16#1A, -Bits1Val3 = {3,<<0:1,1:1,0:1,1:1,1:1,0:3>>} +Bits1Val3 = {3,<<0:1,1:1,0:1,1:1,1:1,0:3>>}, +Bits1Val4 = [0,1,0,1,1] </pre> - <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c> and <c>Bits1Val3</c> - denote the same value.</p> + <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c>, <c>Bits1Val3</c>, + and <c>Bits1Val1</c> denote the same value.</p> <pre> Bits2Val1 = [gnu,punk], -Bits2Val2 = 2#1110, +Bits2Val2 = <<2#1110:4>>, Bits2Val3 = [bar,gnu,gnome], -Bits2Val4 = [0,1,1,1] </pre> - <p>The above <c>Bits2Val2</c>, <c>Bits2Val3</c> and <c>Bits2Val4</c> - also all denote the same value.</p> + <p><c>Bits2Val2</c> and <c>Bits2Val3</c> above denote the same value.</p> <p><c>Bits2Val1</c> is assigned symbolic values. The assignment means that the bits corresponding to <c>gnu</c> and <c>punk</c> i.e. bits 2 and 14 are set to 1 and the rest set to 0. The symbolic values appear as a list of values. If a named value appears, which is not specified in the type definition, a run-time error will occur.</p> <p>The compact notation equivalent to the empty BIT STRING is - <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is <c>[]</c> or + <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is + <c><![CDATA[<<>>]]></c>, <c>[]</c>, or <c>0</c>.</p> - <p>BIT STRINGS may also be sub-typed with for example a SIZE + <p>BIT STRINGS may also be sub-typed with, for example, a SIZE specification:</p> <pre> Bits3 ::= BIT STRING (SIZE(0..31)) </pre> diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index bb3c6a4f0f..b269276a92 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -64,8 +64,9 @@ <v>Asn1module = atom() | string()</v> <v>Options = [Option| OldOption]</v> <v>Option = ber | per | uper | der | compact_bit_string | + legacy_bit_string | noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | - asn1config | undec_rest | {inline, OutputName} | inline | + asn1config | undec_rest | {macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors</v> <v>OldOption = ber | per</v> <v>Reason = term()</v> @@ -154,22 +155,26 @@ File3.asn </pre> <tag><c>compact_bit_string</c></tag> <item> <p> - Makes it possible to use a compact notation for values - of the BIT STRING type in Erlang. The notation: + The BIT STRING type will be decoded to the "compact notation". + <em>This option is not recommended for new code.</em> </p> - <pre> -BitString = {Unused, Binary}, -Unused = integer(), -Binary = binary() - </pre> + <p>For details see + <seealso marker="asn1_ug#BIT STRING"> + BIT STRING type section in the Users Guide + </seealso>. + </p> + </item> + <tag><c>legacy_bit_string</c></tag> + <item> <p> - <c>Unused</c> must be a number in the range 0 to 7. It - tells how many bits in the least significant byte in - <c>Binary</c> that is unused. - For details see + The BIT STRING type will be decoded to the legacy + format, i.e. a list of zeroes and ones. + <em>This option is not recommended for new code.</em> + </p> + <p>For details see <seealso marker="asn1_ug#BIT STRING"> - BIT STRING type section in users guide - </seealso>. + BIT STRING type section in the Users Guide + </seealso>. </p> </item> <tag><c>{n2n, EnumTypeName}</c></tag> @@ -233,28 +238,6 @@ Binary = binary() list or a binary. Earlier versions of the compiler ignored those following bytes.</p> </item> - <tag><c>{inline, OutputName}</c></tag> - <item> - <p>Compiling with this option gives one output module - containing all asn1 run-time functionality. The asn1 specs - are provided in a target module Module.set.asn as described - <seealso marker="#asn1set">above</seealso>. The name of the - resulting module containing generated encode/decode functions - and in-lined run-time functions will be - <c>OutputName.erl</c>. The merging/in-lining of code is done - by the <c>igor</c> module of <c>syntax_tools</c>. By default - the functions generated from the first asn1 spec in the - <c>.set.asn</c> are exported, unless a - <c>{export, [atom()]}</c> or <c>{export_all, true}</c> option - are provided. The list of atoms are names of chosen asn1 - specs from the <c>.set.asn</c> file. </p> - </item> - <tag><c>inline</c></tag> - <item> - <p>It is also possible to use the sole argument <c>inline</c>. - It is as <c>{inline, OutputName}</c>, but the output file gets the - default name of the source <c>.set.asn</c> file.</p> - </item> <tag><c>{macro_name_prefix, Prefix}</c></tag> <item> <p>All macro names generated by the compiler are prefixed with |