Deprecate "use Gettext" for backends and improve docs (#392)

Author: whatyouhide

lib/gettext.ex

@@ -85,7 +85,7 @@ defmodule Gettext.Backend do
 
   For example, if something like this is called:
 
-      MyApp.Gettext.gettext("Hello %{name}, your favorite color is %{color}", name: "Jane", color: "blue")
+      gettext("Hello %{name}, your favorite color is %{color}", name: "Jane", color: "blue")
 
   and our `it/LC_MESSAGES/default.po` looks like this:
 

lib/gettext/backend.ex

@@ -61,8 +61,6 @@ defmodule Gettext.Compiler do
         Gettext.ExtractorAgent.add_backend(__MODULE__)
       end
 
-      unquote(macros())
-
       # These are the two functions we generate inside the backend.
 
       @impl Gettext.Backend
@@ -99,12 +97,12 @@ defmodule Gettext.Compiler do
     end)
   end
 
-  defp macros() do
+  def generate_macros(_env) do
     quote unquote: false do
       defmacro dpgettext_noop(domain, msgctxt, msgid) do
-        domain = Gettext.Compiler.expand_to_binary(domain, "domain", __MODULE__, __CALLER__)
-        msgid = Gettext.Compiler.expand_to_binary(msgid, "msgid", __MODULE__, __CALLER__)
-        msgctxt = Gettext.Compiler.expand_to_binary(msgctxt, "msgctxt", __MODULE__, __CALLER__)
+        domain = Gettext.Compiler.expand_to_binary(domain, "domain", __CALLER__)
+        msgid = Gettext.Compiler.expand_to_binary(msgid, "msgid", __CALLER__)
+        msgctxt = Gettext.Compiler.expand_to_binary(msgctxt, "msgctxt", __CALLER__)
 
         if Gettext.Extractor.extracting?() do
           Gettext.Extractor.extract(
@@ -143,12 +141,10 @@ defmodule Gettext.Compiler do
       end
 
       defmacro dpngettext_noop(domain, msgctxt, msgid, msgid_plural) do
-        domain = Gettext.Compiler.expand_to_binary(domain, "domain", __MODULE__, __CALLER__)
-        msgid = Gettext.Compiler.expand_to_binary(msgid, "msgid", __MODULE__, __CALLER__)
-        msgctxt = Gettext.Compiler.expand_to_binary(msgctxt, "msgctxt", __MODULE__, __CALLER__)
-
-        msgid_plural =
-          Gettext.Compiler.expand_to_binary(msgid_plural, "msgid_plural", __MODULE__, __CALLER__)
+        domain = Gettext.Compiler.expand_to_binary(domain, "domain", __CALLER__)
+        msgid = Gettext.Compiler.expand_to_binary(msgid, "msgid", __CALLER__)
+        msgctxt = Gettext.Compiler.expand_to_binary(msgctxt, "msgctxt", __CALLER__)
+        msgid_plural = Gettext.Compiler.expand_to_binary(msgid_plural, "msgid_plural", __CALLER__)
 
         if Gettext.Extractor.extracting?() do
           Gettext.Extractor.extract(
@@ -309,7 +305,7 @@ defmodule Gettext.Compiler do
       end
 
       defmacro gettext_comment(comment) do
-        comment = Gettext.Compiler.expand_to_binary(comment, "comment", __MODULE__, __CALLER__)
+        comment = Gettext.Compiler.expand_to_binary(comment, "comment", __CALLER__)
         Gettext.Compiler.append_extracted_comment(comment)
         :ok
       end
@@ -320,9 +316,16 @@ defmodule Gettext.Compiler do
   Expands the given `msgid` in the given `env`, raising if it doesn't expand to
   a binary.
   """
-  @spec expand_to_binary(binary, binary, module, Macro.Env.t()) :: binary | no_return
-  def expand_to_binary(term, what, gettext_module, env)
+  @spec expand_to_binary(binary, binary, Macro.Env.t()) :: binary | no_return
+  def expand_to_binary(term, what, env)
       when what in ~w(domain msgctxt msgid msgid_plural comment) do
+    gettext_module =
+      if Module.open?(env.module) do
+        Module.get_attribute(env.module, :__gettext_backend__)
+      else
+        List.first(env.module.__info__(:attributes)[:__gettext_backend__])
+      end
+
     raiser = fn term ->
       raise ArgumentError, """
       Gettext macros expect message keys (msgid and msgid_plural),
@@ -337,7 +340,7 @@ defmodule Gettext.Compiler do
       module:
 
           string = "hello world"
-          Gettext.gettext(#{inspect(gettext_module)}, string)
+          Gettext.gettext(#{if(gettext_module, do: inspect(gettext_module), else: "backend")}, string)
       """
     end
 
@@ -355,6 +358,34 @@ defmodule Gettext.Compiler do
     end
   end
 
+  @doc """
+  Expands the given `term` to a compile-time atom in the given `env`.
+  """
+  @spec expand_backend(Macro.t(), Macro.Env.t()) :: module
+  def expand_backend(term, env) do
+    case Macro.expand(term, env) do
+      term when is_atom(term) and term not in [nil, false, true] ->
+        term
+
+      _other ->
+        raise ArgumentError, """
+        Gettext.Macros macros (that end with "_with_backend") expect the backend argument
+        to be an atom at compile-time, but the given term doesn't. This is what the macro
+        received:
+
+        #{inspect(term)}
+
+        Dynamic messages should be avoided as they limit Gettext's
+        ability to extract messages from your source code. If you are
+        sure you need dynamic lookup, you can use the functions in the Gettext
+        module:
+
+            string = "hello world"
+            Gettext.gettext(backend, string)
+        """
+    end
+  end
+
   @doc """
   Appends the given comment to the list of extracted comments in the process dictionary.
   """