Introduce @deprecated (#7113)

Author: ggcampinho

lib/elixir/lib/module.ex

@@ -104,6 +104,17 @@ defmodule Module do
   Multiple uses of `@compile` will accumulate instead of overriding
   previous ones. See the "Compile options" section below.
 
+  ### `@deprecated`
+
+  Provides the deprecation reason for a function. For example:
+
+      defmodule Keyword do
+        @deprecated "Use Kernel.length/1 instead"
+        def size(keyword) do
+          length(keyword)
+        end
+      end
+
   ### `@doc` (and `@since`)
 
   Provides documentation for the function or macro that follows the
@@ -1177,22 +1188,29 @@ defmodule Module do
   @doc false
   # Used internally to compile documentation.
   # This function is private and must be used only internally.
-  def compile_doc(env, kind, name, args, _guards, _body) do
+  def compile_definition_attributes(env, kind, name, args, _guards, _body) do
     module = env.module
     table = data_table_for(module)
     arity = length(args)
     pair = {name, arity}
 
+    # Docs must come first as they read the impl callback
+    compile_doc(table, pair, env, kind, args)
+    compile_deprecated(table, pair)
+    compile_impl(table, name, env, kind, args)
+    :ok
+  end
+
+  defp compile_doc(table, pair, env, kind, args) do
     {line, doc} = get_doc_info(table, env)
 
     # TODO: Store @since alongside the docs
     _ = get_since_info(table)
 
     add_doc(table, line, kind, pair, args, doc, env)
-    :ok
   end
 
-  defp add_doc(_module, line, kind, {name, arity}, _args, doc, env)
+  defp add_doc(_table, line, kind, {name, arity}, _args, doc, env)
        when kind in [:defp, :defmacrop] do
     if doc do
       error_message =
@@ -1217,12 +1235,14 @@ defmodule Module do
     end
   end
 
-  @doc false
-  # Used internally to check the validity of arguments to @impl.
-  # This function is private and must be used only internally.
-  def compile_impl(env, kind, name, args, _guards, _body) do
-    %{module: module, line: line, file: file} = env
-    table = data_table_for(module)
+  defp compile_deprecated(table, pair) do
+    if reason = get_deprecated_info(table) do
+      :ets.insert(table, {{:deprecated, pair}, reason})
+    end
+  end
+
+  defp compile_impl(table, name, env, kind, args) do
+    %{line: line, file: file} = env
 
     case :ets.take(table, :impl) do
       [{:impl, value, _, _}] ->
@@ -1236,8 +1256,6 @@ defmodule Module do
       [] ->
         :ok
     end
-
-    :ok
   end
 
   defp args_count([{:\\, _, _} | tail], total, defaults) do
@@ -1686,6 +1704,12 @@ defmodule Module do
             "the version a function, macro, type or callback was added, got: #{inspect(value)}"
   end
 
+  defp preprocess_attribute(:deprecated, value) when not is_binary(value) do
+    raise ArgumentError,
+          "@deprecated expects a string with the reason for the deprecation, " <>
+            "got: #{inspect(value)}"
+  end
+
   defp preprocess_attribute(_key, value) do
     value
   end
@@ -1707,6 +1731,13 @@ defmodule Module do
     :ets.take(table, :since)
   end
 
+  defp get_deprecated_info(table) do
+    case :ets.take(table, :deprecated) do
+      [{:deprecated, reason, _, _}] -> reason
+      [] -> nil
+    end
+  end
+
   defp data_table_for(module) do
     :elixir_module.data_table(module)
   end

lib/elixir/lib/protocol.ex

@@ -309,7 +309,7 @@ defmodule Protocol do
   end
 
   defp beam_protocol(protocol) do
-    chunk_ids = [:abstract_code, :attributes, :compile_info, 'ExDc']
+    chunk_ids = [:abstract_code, :attributes, :compile_info, 'ExDc', 'ExDp']
     opts = [:allow_missing_chunks]
 
     case :beam_lib.chunks(beam_file(protocol), chunk_ids, opts) do
@@ -318,12 +318,13 @@ defmodule Protocol do
           {:abstract_code, {_raw, abstract_code}},
           {:attributes, attributes},
           {:compile_info, compile_info},
-          {'ExDc', docs}
+          {'ExDc', docs},
+          {'ExDp', deprecated}
         ] = entries
 
         case attributes[:protocol] do
           [fallback_to_any: any] ->
-            {:ok, {protocol, any, abstract_code}, {compile_info, docs}}
+            {:ok, {protocol, any, abstract_code}, {compile_info, docs, deprecated}}
 
           _ ->
             {:error, :not_a_protocol}
@@ -497,14 +498,14 @@ defmodule Protocol do
   end
 
   # Finally compile the module and emit its bytecode.
-  defp compile(protocol, code, {compile_info, docs}) do
+  defp compile(protocol, code, {compile_info, docs, deprecated}) do
     opts = Keyword.take(compile_info, [:source])
     opts = if Code.compiler_options()[:debug_info], do: [:debug_info | opts], else: opts
     {:ok, ^protocol, binary, _warnings} = :compile.forms(code, [:return | opts])
 
     case docs do
       :missing_chunk -> {:ok, binary}
-      _ -> {:ok, :elixir_erl.add_beam_chunks(binary, [{"ExDc", docs}])}
+      _ -> {:ok, :elixir_erl.add_beam_chunks(binary, [{"ExDc", docs}, {"ExDp", deprecated}])}
     end
   end
 

lib/elixir/src/elixir_erl.erl

@@ -21,11 +21,11 @@ debug_info(elixir_v1, _Module, none, _Opts) ->
   {error, missing};
 debug_info(elixir_v1, _Module, {elixir_v1, Map, _Specs}, _Opts) ->
   {ok, Map};
-debug_info(erlang_v1, _Module, {elixir_v1, Map, Specs}, _Opts) ->
-  {Prefix, Forms, _, _} = dynamic_form(Map),
+debug_info(erlang_v1, Module, {elixir_v1, Map, Specs}, _Opts) ->
+  {Prefix, Forms, _, _} = dynamic_form(Map, deprecated_chunk_from_beam(Module)),
   {ok, Prefix ++ Specs ++ Forms};
-debug_info(core_v1, _Module, {elixir_v1, Map, Specs}, Opts) ->
-  {Prefix, Forms, _, _} = dynamic_form(Map),
+debug_info(core_v1, Module, {elixir_v1, Map, Specs}, Opts) ->
+  {Prefix, Forms, _, _} = dynamic_form(Map, deprecated_chunk_from_beam(Module)),
   #{compile_opts := CompileOpts} = Map,
 
   %% Do not rely on elixir_erl_compiler because we don't
@@ -39,6 +39,25 @@ debug_info(core_v1, _Module, {elixir_v1, Map, Specs}, Opts) ->
 debug_info(_, _, _, _) ->
   {error, unknown_format}.
 
+%% `ExDp` chunk from beam
+
+deprecated_chunk_from_beam(Module) ->
+  Chunk = binary_to_list(<<"ExDp">>),
+  Beam = abstract_code_beam(Module),
+
+  {elixir_deprecated_v1, Deprecated} =
+    case beam_lib:chunks(Beam, [Chunk]) of
+      {ok, {Module, [{Chunk, DeprecatedBin}]}} -> binary_to_term(DeprecatedBin);
+      _ -> {elixir_deprecated_v1, []}
+    end,
+  Deprecated.
+
+abstract_code_beam(Module) ->
+  case code:get_object_code(Module) of
+    {Module, Beam, _} -> Beam;
+    error -> Module
+  end.
+
 %% Builds Erlang AST annotation.
 
 get_ann(Opts) when is_list(Opts) ->
@@ -149,16 +168,17 @@ definition_scope(Meta, File) ->
 
 compile(#{module := Module} = Map) ->
   Data = elixir_module:data_table(Module),
-  {Prefix, Forms, Defmacro, Unreachable} = dynamic_form(Map),
+  Deprecated = get_deprecated(Data),
+  {Prefix, Forms, Defmacro, Unreachable} = dynamic_form(Map, Deprecated),
   Specs =
     case elixir_config:get(bootstrap) of
       true -> [];
       false -> specs_form(Map, Data, Defmacro, Unreachable, types_form(Data, []))
     end,
-  load_form(Map, Data, Prefix, Forms, Specs).
+  load_form(Map, Data, Prefix, Forms, Specs, Deprecated).
 
 dynamic_form(#{module := Module, line := Line, file := File, attributes := Attributes,
-               definitions := Definitions, unreachable := Unreachable}) ->
+               definitions := Definitions, unreachable := Unreachable}, Deprecated) ->
   {Def, Defmacro, Macros, Exports, Functions} =
     split_definition(Definitions, File, Unreachable, [], [], [], [], {[], []}),
 
@@ -167,7 +187,7 @@ dynamic_form(#{module := Module, line := Line, file := File, attributes := Attri
             {attribute, Line, module, Module},
             {attribute, Line, compile, no_auto_import}],
 
-  Forms0 = functions_form(Line, Module, Def, Defmacro, Exports, Functions),
+  Forms0 = functions_form(Line, Module, Def, Defmacro, Exports, Functions, Deprecated),
   Forms1 = attributes_form(Line, Attributes, Forms0),
   {Prefix, Forms1, Macros, Unreachable}.
 
@@ -263,12 +283,12 @@ is_macro(_)         -> false.
 
 % Functions
 
-functions_form(Line, Module, Def, Defmacro, Exports, Body) ->
-  {Spec, Info} = add_info_function(Line, Module, Def, Defmacro),
+functions_form(Line, Module, Def, Defmacro, Exports, Body, Deprecated) ->
+  {Spec, Info} = add_info_function(Line, Module, Def, Defmacro, Deprecated),
   [{attribute, Line, export, lists:sort([{'__info__', 1} | Exports])}, Spec, Info | Body].
 
-add_info_function(Line, Module, Def, Defmacro) ->
-  AllowedAttrs = [attributes, compile, functions, macros, md5, module],
+add_info_function(Line, Module, Def, Defmacro, Deprecated) ->
+  AllowedAttrs = [attributes, compile, functions, macros, md5, module, deprecated],
   AllowedArgs = lists:map(fun(Atom) -> {atom, Line, Atom} end, AllowedAttrs),
 
   Spec =
@@ -303,7 +323,8 @@ add_info_function(Line, Module, Def, Defmacro) ->
       macros_info(Defmacro),
       get_module_info(Module, attributes),
       get_module_info(Module, compile),
-      get_module_info(Module, md5)
+      get_module_info(Module, md5),
+      deprecated_info(Deprecated)
     ]},
 
   {Spec, Info}.
@@ -321,6 +342,9 @@ get_module_info(Module, Key) ->
   Call = remote(0, erlang, get_module_info, [{atom, 0, Module}, {atom, 0, Key}]),
   {clause, 0, [{atom, 0, Key}], [], [Call]}.
 
+deprecated_info(Deprecated) ->
+  {clause, 0, [{atom, 0, deprecated}], [], [elixir_erl:elixir_to_erl(Deprecated)]}.
+
 % Types
 
 types_form(Data, Forms) ->
@@ -442,8 +466,9 @@ attributes_form(Line, Attributes, Forms) ->
 
 % Loading forms
 
-load_form(#{line := Line, file := File, compile_opts := Opts} = Map, Data, Prefix, Forms, Specs) ->
-  {ExtraChunks, CompileOpts} = extra_chunks(Data, Line, debug_opts(Map, Specs, Opts)),
+load_form(#{line := Line, file := File, compile_opts := Opts} = Map,
+            Data, Prefix, Forms, Specs, Deprecated) ->
+  {ExtraChunks, CompileOpts} = extra_chunks(Data, Deprecated, Line, debug_opts(Map, Specs, Opts)),
   {_, Binary} = elixir_erl_compiler:forms(Prefix ++ Specs ++ Forms, File, CompileOpts),
   add_beam_chunks(Binary, ExtraChunks).
 
@@ -469,12 +494,17 @@ supports_debug_tuple() ->
     _ -> true
   end.
 
-extra_chunks(Data, Line, Opts) ->
+extra_chunks(Data, Deprecated, Line, Opts) ->
   Supported = supports_extra_chunks_option(),
-  case docs_chunk(Data, Line, elixir_compiler:get_opt(docs)) of
+  Chunks0 = lists:flatten([
+    docs_chunk(Data, Line, elixir_compiler:get_opt(docs)),
+    deprecated_chunk(Deprecated)
+  ]),
+
+  case Chunks0 of
     [] -> {[], Opts};
-    Chunks when Supported -> {[], [{extra_chunks, Chunks} | Opts]};
-    Chunks -> {Chunks, Opts}
+    Chunks1 when Supported -> {[], [{extra_chunks, Chunks1} | Opts]};
+    Chunks1 -> {Chunks1, Opts}
   end.
 
 supports_extra_chunks_option() ->
@@ -495,6 +525,10 @@ docs_chunk(Data, Line, true) ->
 docs_chunk(_, _, _) ->
   [].
 
+deprecated_chunk(Deprecated) ->
+  ChunkData = term_to_binary({elixir_deprecated_v1, Deprecated}, [compressed]),
+  [{<<"ExDp">>, ChunkData}].
+
 get_moduledoc(Line, Data) ->
   case ets:lookup_element(Data, moduledoc, 2) of
     nil -> {Line, nil};
@@ -513,6 +547,9 @@ get_type_docs(Data) ->
   lists:usort(ets:select(Data, [{{{typedoc, '$1'}, '$2', '$3', '$4'},
                                  [], [{{'$1', '$2', '$3', '$4'}}]}])).
 
+get_deprecated(Data) ->
+  lists:usort(ets:select(Data, [{{{deprecated, '$1'}, '$2'}, [], [{{'$1', '$2'}}]}])).
+
 %% Errors
 
 form_error(#{line := Line, file := File}, Error) ->

lib/elixir/src/elixir_module.erl

@@ -1,7 +1,6 @@
 -module(elixir_module).
--export([data_table/1, defs_table/1, is_open/1, delete_doc/6,
-         compile/4, expand_callback/6, format_error/1,
-         compiler_modules/0, delete_impl/6,
+-export([data_table/1, defs_table/1, is_open/1, delete_definition_attributes/6,
+         compile/4, expand_callback/6, format_error/1, compiler_modules/0,
          write_cache/3, read_cache/2]).
 -include("elixir.hrl").
 
@@ -32,13 +31,11 @@ defs_table(Module) ->
 is_open(Module) ->
   ets:lookup(elixir_modules, Module) /= [].
 
-delete_doc(#{module := Module}, _, _, _, _, _) ->
-  ets:delete(data_table(Module), doc),
-  ok.
-
-delete_impl(#{module := Module}, _, _, _, _, _) ->
-  ets:delete(data_table(Module), impl),
-  ok.
+delete_definition_attributes(#{module := Module}, _, _, _, _, _) ->
+  Data = data_table(Module),
+  ets:delete(Data, doc),
+  ets:delete(Data, deprecated),
+  ets:delete(Data, impl).
 
 write_cache(Module, Key, Value) ->
   ets:insert(data_table(Module), {{cache, Key}, Value}).
@@ -176,20 +173,11 @@ build(Line, File, Module, Lexical) ->
   Ref  = elixir_code_server:call({defmodule, self(),
                                  {Module, Data, Defs, Line, File}}),
 
-  DocsOnDefinition =
-      case elixir_compiler:get_opt(docs) of
-        true -> [{'Elixir.Module', compile_doc}];
-        _    -> [{elixir_module, delete_doc}]
-      end,
-
-  ImplOnDefinition =
-      case elixir_config:get(bootstrap) of
-        true -> [{elixir_module, delete_impl}];
-        _    -> [{'Elixir.Module', compile_impl}]
-      end,
-
-  %% Docs must come first as they read the impl callback.
-  OnDefinition = DocsOnDefinition ++ ImplOnDefinition,
+  OnDefinition =
+    case elixir_config:get(bootstrap) of
+      false -> [{'Elixir.Module', compile_definition_attributes}];
+      _ -> [{elixir_module, delete_definition_attributes}]
+    end,
 
   ets:insert(Data, [
     % {Key, Value, Accumulate?, UnreadLine}