Merge branch 'bjorn/asn1/deprecations/OTP-11731'

* bjorn/asn1/deprecations/OTP-11731:
  Remove or de-emphasize references to the deprecated asn1rt module
  Deprecate asn1 functions

lib/asn1/doc/src/asn1_ug.xml

@@ -205,16 +205,13 @@ ok
         is saved in the <c>People.asn1db</c> file, the
         generated Erlang code is compiled using the Erlang compiler and
         loaded into  the Erlang runtime system. Now there is a user interface
-        of encode/2 and decode/2 in the module People, which is invoked by:
+        for <c>encode/2</c> and <c>decode/2</c> in the module People,
+	which is invoked by:
                 <br></br>
 <c><![CDATA['People':encode(<Type name>,<Value>),]]></c>        <br></br>
 
         or        <br></br>
-<c><![CDATA['People':decode(<Type name>,<Value>),]]></c>        <br></br>
-
-        Alternatively one can use the <c><![CDATA[asn1rt:encode(<Module name> ,<Type name>,<Value>)]]></c> and <c><![CDATA[asn1rt:decode(< Module name>,<Type name>,<Value>)]]></c> calls.
-        However, they are not as efficient as the previous methods since they
-        result in an additional <c>apply/3</c> call.</p>
+<c><![CDATA['People':decode(<Type name>,<Value>),]]></c></p>
       <p>Assume there is a network
         application which receives instances of the  ASN.1 defined
         type Person,  modifies and sends them back again:</p>
@@ -241,16 +238,14 @@ receive
         encoding-rules. 
                 <br></br>
 The encoder and the decoder can also be run from
-        the shell. The following  dialogue with the shell illustrates
-        how the functions   
-        <c>asn1rt:encode/3</c> and <c>asn1rt:decode/3</c> are used.</p>
+        the shell.</p>
       <pre>
 2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input>
 {'Person',"Some Name",roving,50}
-3> <input>{ok,Bin} = asn1rt:encode('People','Person',Rockstar).</input>
+3> <input>{ok,Bin} = 'People':encode('Person',Rockstar).</input>
 {ok,&lt;&lt;243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
       2,1,50&gt;&gt;}
-4> <input>{ok,Person} = asn1rt:decode('People','Person',Bin).</input>
+4> <input>{ok,Person} = 'People':decode('Person',Bin).</input>
 {ok,{'Person',"Some Name",roving,50}}
 5>      </pre>
     </section>
@@ -279,11 +274,8 @@ The encoder and the decoder can also be run from
           (including the compiler).</p>
       </item>
       <item>
-        <p>The module <c>asn1rt</c> which provides the run-time functions. 
-          However, it is preferable to use the generated <c>encode/2</c> and 
-          <c>decode/2</c> functions in each module, ie. 
-          Module:encode(Type,Value), in favor of the <c>asn1rt</c> 
-          interface.</p>
+        <p>The module <c>asn1rt_nif</c> which provides the run-time functions
+	for the ASN.1 decoder for the BER back-end.</p>
       </item>
     </list>
     <p>The reason for the division  of the interface into  compile-time 
@@ -384,25 +376,9 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes).      </pre>
 
     <section>
       <title>Run-time Functions</title>
-      <p>A brief description of the major functions is given here. For a
-        complete description of each function see
-        <seealso marker="asn1rt"> the Asn1 Reference Manual</seealso>, the <c>asn1rt</c> module.</p>
-      <p>The generic run-time encode and decode functions can be invoked as below:</p>
-      <pre>
-asn1rt:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
-asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes).      </pre>
-      <p>Or, preferable like:</p>
-      <pre>
-'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
-'H323-MESSAGES':decode('SomeChoiceType',Bytes).      </pre>
-      <p>The asn1 nif is enabled in two occasions: encoding of
-        asn1 values when the asn1 spec is compiled with <c>per</c> and
-        or decode of encoded asn1 values when the asn1 spec is
-        compiled with <c>ber</c>. In
-        those cases the nif will be loaded automatically at the first call
-        to <c>encode</c>/<c>decode</c>. If one doesn't want the performance
-        overhead of the nif being loaded at the first call it is possible
-        to load the nif separately by loading the <c>asn1rt_nif</c> module.</p>
+      <p>When an ASN.1 specification is compiled with the <c>ber</c>
+      option, the module <c>asn1rt_nif</c> module and the NIF library in
+      <c>asn1/priv_dir</c> will be needed at run-time.</p>
       <p>By invoking the function <c>info/0</c> in a generated module, one
         gets information about which compiler options were used.</p>
     </section>
@@ -414,8 +390,8 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes).      </pre>
         a line number indicating where in the source file the error 
         was detected. If no errors are found, an Erlang ASN.1 module will
         be created as default.</p>
-      <p>The run-time encoders and decoders (in the <c>asn1rt</c> module) do
-        execute within a catch and returns <c>{ok, Data}</c> or
+      <p>The run-time encoders and decoders execute within a catch and
+      returns <c>{ok, Data}</c> or
         <c>{error, {asn1, Description}}</c> where
         <c>Description</c> is
         an Erlang term describing the error. </p>

lib/asn1/doc/src/asn1ct.xml

@@ -61,7 +61,7 @@
 	and <c>uper_bin</c> options will still work, but will print a warning.
 	</p>
 	<p>Another change in R16 is that the generated <c>encode/2</c>
-	function (and <c>asn1rt:encode/3</c>) always returns a binary.
+	function always returns a binary.
 	The <c>encode/2</c> function for the BER back-end used to return
 	an iolist.</p>
       </note>
@@ -326,6 +326,8 @@ File3.asn        </pre>
           not always checked. Returns <c>{ok, Bytes}</c> if successful or
           <c>{error, Reason}</c> if an error occurred.
           </p>
+	<p>This function is deprecated.
+	Use <c>Module:encode(Type, Value)</c> instead.</p>
       </desc>
     </func>
     <func>
@@ -339,6 +341,8 @@ File3.asn        </pre>
       <desc>
         <p>Decodes <c>Type</c> from <c>Module</c> from the binary
           <c>Bytes</c>. Returns <c>{ok, Value}</c> if successful.</p>
+	<p>This function is deprecated.
+	Use <c>Module:decode(Type, Bytes)</c> instead.</p>
       </desc>
     </func>
     <func>

lib/asn1/doc/src/asn1rt.xml

@@ -34,9 +34,12 @@
   <module>asn1rt</module>
   <modulesummary>ASN.1 runtime support functions</modulesummary>
   <description>
-    <p>This module is the interface module for the ASN.1 runtime support functions.
-      To encode and decode ASN.1 types in runtime the functions in this module
-      should be used.</p>
+    <warning>
+      <p>
+	All functions in this module are deprecated and will be
+	removed in a future release.
+      </p>
+    </warning>
   </description>
 
   <funcs>
@@ -52,6 +55,7 @@
       <desc>
         <p>Decodes <c>Type</c> from <c>Module</c> from the binary <c>Bytes</c>.
           Returns <c>{ok,Value}</c> if successful.</p>
+	<p>Use <c>Module:decode(Type, Bytes)</c> instead of this function.</p>
       </desc>
     </func>
 
@@ -65,16 +69,13 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module 
-          <c>Module</c>. Returns a possibly nested list of bytes and or binaries 
-          if successful. To get as fast execution as possible the
-          encode function only performs rudimentary tests that the input 
-          <c>Value</c>
-          is a correct instance of <c>Type</c>. The length of strings is for example
-          not always checked. </p>
-	  <note>
-	  <p>Starting in R16, <c>Bytes</c> is always a binary.</p>
-	  </note>
+        <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1
+        module <c>Module</c>. Returns a binary if successful. To get
+        as fast execution as possible the encode function only
+        performs rudimentary tests that the input <c>Value</c> is a
+        correct instance of <c>Type</c>. The length of strings is, for
+        example, not always checked. </p>
+	<p>Use <c>Module:encode(Type, Value)</c> instead of this function.</p>
       </desc>
     </func>
 
@@ -90,6 +91,7 @@
         <p><c>info/1</c> returns the version of the asn1 compiler that was
           used to compile the module. It also returns the compiler options
           that was used.</p>
+	<p>Use <c>Module:info()</c> instead of this function.</p>
       </desc>
     </func>
 
@@ -106,6 +108,7 @@
           to a list of integers, where each integer represents one
           character as its unicode value. The function fails if the binary
           is not a properly encoded UTF8 string.</p>
+	<p>Use <seealso marker="stdlib:unicode#characters_to_list-1">unicode:characters_to_list/1</seealso> instead of this function.</p>
       </desc>
     </func>
 
@@ -121,6 +124,7 @@
         <p><c>utf8_list_to_binary/1</c> Transforms a list of integers,
           where each integer represents one character as its unicode
           value, to a UTF8 encoded binary.</p>
+	<p>Use <seealso marker="stdlib:unicode#characters_to_binary-1">unicode:characters_to_binary/1</seealso> instead of this function.</p>
       </desc>
     </func>
 

lib/asn1/src/asn1ct.erl

@@ -19,6 +19,10 @@
 %%
 %%
 -module(asn1ct).
+-deprecated([decode/3,encode/3]).
+-compile([{nowarn_deprecated_function,{asn1rt,decode,3}},
+	  {nowarn_deprecated_function,{asn1rt,encode,2}},
+	  {nowarn_deprecated_function,{asn1rt,encode,3}}]).
 
 %% Compile Time functions for ASN.1 (e.g ASN.1 compiler).
 

lib/asn1/src/asn1ct_value.erl

@@ -18,6 +18,7 @@
 %%
 %%
 -module(asn1ct_value).
+-compile([{nowarn_deprecated_function,{asn1rt,utf8_list_to_binary,1}}]).
 
 %%  Generate Erlang values for ASN.1 types.
 %%  The value is randomized within it's constraints

lib/asn1/src/asn1rt.erl

@@ -18,14 +18,13 @@
 %%
 %%
 -module(asn1rt).
+-deprecated(module).
 
 %% Runtime functions for ASN.1 (i.e encode, decode)
 
 -export([encode/2,encode/3,decode/3,load_driver/0,unload_driver/0,info/1]).
 
 -export([utf8_binary_to_list/1,utf8_list_to_binary/1]).
-
--deprecated([load_driver/0,unload_driver/0]).
 
 encode(Module,{Type,Term}) ->
     encode(Module,Type,Term).

lib/eldap/src/eldap.erl

@@ -743,7 +743,7 @@ request(S, Data, ID, Request) ->
 send_request(S, Data, ID, Request) ->
     Message = #'LDAPMessage'{messageID  = ID,
 			     protocolOp = Request},
-    {ok,Bytes} = asn1rt:encode('ELDAPv3', 'LDAPMessage', Message),
+    {ok,Bytes} = 'ELDAPv3':encode('LDAPMessage', Message),
     case do_send(S, Data, Bytes) of
 	{error,Reason} -> throw({gen_tcp_error,Reason});
 	Else           -> Else
@@ -762,7 +762,7 @@ do_recv(S, #eldap{using_tls=true, timeout=Timeout}, Len) ->
 recv_response(S, Data) ->
     case do_recv(S, Data, 0) of
 	{ok, Packet} ->
-	    case asn1rt:decode('ELDAPv3', 'LDAPMessage', Packet) of
+	    case 'ELDAPv3':decode('LDAPMessage', Packet) of
 		{ok,Resp} -> {ok,Resp};
 		Error     -> throw(Error)
 	    end;

lib/megaco/src/binary/megaco_binary_encoder_lib.erl

@@ -66,7 +66,7 @@ version_of(_EC, Binary, 3, [AsnModV1, AsnModV2, AsnModV3])
 version_of([], _Binary, Err) ->
     {error, {decode_failed, lists:reverse(Err)}};
 version_of([AsnMod|AsnMods], Binary, Errs) when is_atom(AsnMod) ->
-    case (catch asn1rt:decode(AsnMod, 'MegacoMessage', Binary)) of
+    case (catch AsnMod:decode('MegacoMessage', Binary)) of
 	{ok, M} ->
 	    V = (M#'MegacoMessage'.mess)#'Message'.version,
 	    {ok, V};
@@ -82,14 +82,14 @@ version_of([AsnMod|AsnMods], Binary, Errs) when is_atom(AsnMod) ->
 
 encode_message([native], MegaMsg, AsnMod, _TransMod, binary) 
   when is_record(MegaMsg, 'MegacoMessage') ->
-    asn1rt:encode(AsnMod, 'MegacoMessage', MegaMsg);
+    AsnMod:encode('MegacoMessage', MegaMsg);
 encode_message(EC, MegaMsg, AsnMod, TransMod, binary) 
   when is_list(EC) andalso is_record(MegaMsg, 'MegacoMessage') ->
     case (catch TransMod:tr_message(MegaMsg, encode, EC)) of
 	{'EXIT', Reason} ->
 	    {error, Reason};
 	MegaMsg2 ->
-	    asn1rt:encode(AsnMod, 'MegacoMessage', MegaMsg2)
+	    AsnMod:encode('MegacoMessage', MegaMsg2)
     end;
 encode_message(EC, MegaMsg, AsnMod, TransMod, io_list) ->
     case encode_message(EC, MegaMsg, AsnMod, TransMod, binary) of
@@ -276,7 +276,7 @@ decode_message_dynamic(_EC, _BadBin, _Mods, _Type) ->
 
 
 decode_message(EC, Bin, AsnMod, TransMod, _) ->
-    case asn1rt:decode(AsnMod, 'MegacoMessage', Bin) of
+    case AsnMod:decode('MegacoMessage', Bin) of
 	{ok, MegaMsg} ->
 	    case EC of
 		[native] ->

lib/stdlib/src/otp_internal.erl

@@ -577,6 +577,24 @@ obsolete_1(wxCursor, new, 3) ->
 obsolete_1(wxCursor, new, 4) ->
     {deprecated,"deprecated function not available in wxWidgets-2.9 and later"};
 
+%% Added in OTP 17.
+obsolete_1(asn1ct, decode,3) ->
+    {deprecated,"deprecated; use Mod:decode/2 instead"};
+obsolete_1(asn1ct, encode, 3) ->
+    {deprecated,"deprecated; use Mod:encode/2 instead"};
+obsolete_1(asn1rt, decode,3) ->
+    {deprecated,"deprecated; use Mod:decode/2 instead"};
+obsolete_1(asn1rt, encode, 2) ->
+    {deprecated,"deprecated; use Mod:encode/2 instead"};
+obsolete_1(asn1rt, encode, 3) ->
+    {deprecated,"deprecated; use Mod:encode/2 instead"};
+obsolete_1(asn1rt, info, 1) ->
+    {deprecated,"deprecated; use Mod:info/0 instead"};
+obsolete_1(asn1rt, utf8_binary_to_list, 1) ->
+    {deprecated,{unicode,characters_to_list,1}};
+obsolete_1(asn1rt, utf8_list_to_binary, 1) ->
+    {deprecated,{unicode,characters_to_binary,1}};
+
 obsolete_1(_, _, _) ->
     no.