Tidy up and clean up quote API, closes #814

Author: José Valim

CHANGELOG.md

@@ -9,6 +9,7 @@
   * [Mix] Allow Mix projects to be generated with just one letter
 
 * deprecations
+  * [Kernel] Tidy up and clean `quote` API
   * [Kernel] Old `:local.(args)` syntax is deprecated
 
 # v0.8.0 (2013-01-28)

lib/elixir/include/elixir.hrl

@@ -33,9 +33,9 @@
 
 -record(elixir_quote, {
   line=0,
-  var_context=nil,
-  expand_aliases=true,
-  expand_imports=true,
+  vars_hygiene=nil,
+  aliases_hygiene=true,
+  imports_hygiene=true,
   unquote=true
 }).
 

lib/elixir/lib/kernel/special_forms.ex

@@ -355,15 +355,12 @@ defmodule Kernel.SpecialForms do
 
   ## Options
 
-  * `:hygiene` - When false, disables hygiene for variables, aliases and imports;
   * `:unquote` - When false, disables unquoting. Useful when you have a quote
                  inside another quote and want to control which quote is
                  able to unquote;
   * `:location` - When set to `:keep`, keeps the current line and file on quotes.
                   Read the Stacktrace information section below for more information;
-  * `:expand_aliases` - When false, do not expand aliases;
-  * `:expand_imports` - When false, do not expand imports;
-  * `:var_context` - The context for quoted variables. Defaults to the current module;
+  * `:hygiene` - Allows a developer to disable hygiene selectively;
 
   ## Macro literals
 
@@ -379,17 +376,15 @@ defmodule Kernel.SpecialForms do
 
   ## Hygiene
 
-  Elixir macros are hygienic. This means aliases and imports
-  defined inside the quoted often refer to the context that
-  defined the macro.
+  Elixir macros are hygienic via means of deferred resolution.
 
-  Furthermore, variables inside quote are also hygienic. That
-  said, a variable defined in a macro cannot affect the scope
-  where the macro is included.
+  This means aliases and imports defined inside the quoted refer
+  to the context that defined the macro and not the context
+  where the macro is expanded.
 
-  The option `hygiene` can turn off all the hygiene mechanisms
-  defined below. However, they can also be changed in a one by
-  one basis.
+  Furthermore, variables inside quote are also hygienic: a
+  variable defined in a macro cannot affect the variables where
+  the macro is expanded.
 
   ### Hygiene in variables
 
@@ -451,10 +446,9 @@ defmodule Kernel.SpecialForms do
       # Access the variable a from Hygiene1
       quote do: var!(a, Hygiene1) = 2
 
-  Another option is to set the `var_context` option, affecting
-  all variables in the block:
+  Hygiene for variables can be disabled overall as:
 
-      quote var_context: Hygiene1, do: a = 2
+      quote hygiene: [vars: false], do: x
 
   ### Hygiene in aliases
 
@@ -476,9 +470,9 @@ defmodule Kernel.SpecialForms do
   in the context the macro is expanded, the code above works
   because `D` was expanded when the quote was generated.
 
-  There are two ways to disable this behaviour. By giving
-  the `expand_aliases` equals to false to quote or by using
-  the `alias!` macro inside the quote:
+  There are two ways to disable this behaviour. By disabling
+  hygiene for aliases or by using the `alias!` macro inside
+  the quote:
 
       defmodule NoHygiene do
         defmacro interference do
@@ -536,7 +530,7 @@ defmodule Kernel.SpecialForms do
       Lazy.return_size #=> 2
 
   As in aliases, imports expansion can be explicitly disabled
-  via the `expand_imports` option.
+  via the `hygiene: [imports: false]` option.
 
   ## Stacktrace information
 

lib/elixir/lib/kernel/typespec.ex

@@ -583,7 +583,7 @@ defmodule Kernel.Typespec do
   # Handle access macro
   defp typespec({{:., meta, [Kernel, :access]}, meta1, [target, args]}, vars, caller) do
     access = {{:., meta, [Kernel, :access]}, meta1,
-              [target, args ++ [_: (quote hygiene: false, do: any)]]}
+              [target, args ++ [_: { :any, [], [] }]]}
     typespec(Macro.expand(access, caller), vars, caller)
   end
 

lib/elixir/src/elixir_errors.erl

@@ -77,10 +77,10 @@ form_error(Meta, File, Module, Desc) ->
 
 %% Shows a deprecation message
 
-deprecation(Line, File, Message) -> deprecation(Line, File, Message, []).
+deprecation(Meta, File, Message) -> deprecation(Meta, File, Message, []).
 
-deprecation(Line, File, Message, Args) ->
-  io:format(file_format(Line, File, io_lib:format(Message, Args))).
+deprecation(Meta, File, Message, Args) ->
+  io:format(file_format(?line(Meta), File, io_lib:format(Message, Args))).
 
 %% Handle warnings and errors (called during module compilation)
 

lib/elixir/src/elixir_quote.erl

@@ -52,9 +52,9 @@ do_quote({ unquote, _Meta, [Expr] }, #elixir_quote{unquote=true}, S) ->
   elixir_translator:translate_each(Expr, S);
 
 do_quote({ 'alias!', _Meta, [Expr] }, Q, S) ->
-  do_quote(Expr, Q#elixir_quote{expand_aliases=false}, S);
+  do_quote(Expr, Q#elixir_quote{aliases_hygiene=false}, S);
 
-% do_quote({ '__aliases__', Meta, [H|_] = Aliases }, #elixir_quote{expand_aliases=true} = Q, S) when is_atom(H) and H /= 'Elixir' ->
+% do_quote({ '__aliases__', Meta, [H|_] = Aliases }, #elixir_quote{aliases_hygiene=true} = Q, S) when is_atom(H) and H /= 'Elixir' ->
 %   Line = ?line(Meta),
 %   { TAliases, SA } = do_quote(['Elixir'|Aliases], Q, S),
 % 
@@ -79,11 +79,11 @@ do_quote({ Left, Meta, nil }, Q, S) when is_atom(Left) ->
   Tuple = { tuple, Line, [
     { atom, Line, Left },
     meta(Meta, Q),
-    { atom, Line, Q#elixir_quote.var_context }
+    { atom, Line, Q#elixir_quote.vars_hygiene }
   ] },
   { Tuple, S };
 
-do_quote({ Name, Meta, ArgsOrAtom } = Tuple, #elixir_quote{expand_imports=true} = Q, S) when is_atom(Name) ->
+do_quote({ Name, Meta, ArgsOrAtom } = Tuple, #elixir_quote{imports_hygiene=true} = Q, S) when is_atom(Name) ->
   Arity = case is_atom(ArgsOrAtom) of
     true  -> 0;
     false -> length(ArgsOrAtom)

lib/elixir/src/elixir_translator.erl

@@ -244,13 +244,25 @@ translate_each({ quote, Meta, [T] }, S) when is_list(T) ->
         syntax_error(Meta, S#elixir_scope.file, "invalid args for quote")
     end,
 
-  Context = case lists:keyfind(var_context, 1, T) of
+  Hygiene = case lists:keyfind(hygiene, 1, T) of
+    { hygiene, true } ->
+      elixir_errors:deprecation(Meta, S#elixir_scope.file, "hygiene: true is deprecated, please set it to [] instead", []),
+      [];
+    { hygiene, List } when is_list(List) ->
+      List;
+    { hygiene, false } ->
+      elixir_errors:deprecation(Meta, S#elixir_scope.file, "hygiene: false is deprecated, please set it to [vars: false] instead", []),
+      [{vars,false}, {imports,false}, {aliases,false}];
+    false ->
+      []
+  end,
+
+  Vars = case lists:keyfind(var_context, 1, T) of
     { var_context, VarContext } ->
-      expand_var_context(Meta, VarContext,
-        "invalid argument given for var_context in quote", S);
+      expand_var_context(Meta, VarContext, "invalid argument given for var_context in quote", S);
     false ->
-      case lists:keyfind(hygiene, 1, T) of
-        { hygiene, false } -> nil;
+      case lists:keyfind(vars, 1, Hygiene) of
+        { vars, false } -> nil;
         _ ->
           case S#elixir_scope.module of
             nil -> 'Elixir';
@@ -259,20 +271,18 @@ translate_each({ quote, Meta, [T] }, S) when is_list(T) ->
       end
   end,
 
-  GetExpansion = fun(Key) ->
+  GetExpansion = fun(Key, New) ->
     case lists:keyfind(Key, 1, T) of
       { Key, Bool } when is_boolean(Bool) ->
+        elixir_errors:deprecation(Meta, S#elixir_scope.file, "the ~s option for quote is deprecated, please use hygiene: [~s: ~s] instead", [Key, New, Bool]),
         Bool;
       false ->
-        case lists:keyfind(hygiene, 1, T) of
-          { hygiene, Bool } when is_boolean(Bool) -> Bool;
-          false -> true
-        end
+        not(lists:keyfind(New, 1, Hygiene) == { New, false })
     end
   end,
 
-  Aliases = GetExpansion(expand_aliases),
-  Imports = GetExpansion(expand_imports),
+  Aliases = GetExpansion(aliases_hygiene, aliases),
+  Imports = GetExpansion(imports_hygiene, imports),
 
   { DefaultLine, DefaultFile } = case lists:keyfind(location, 1, T) of
     { location, keep }  -> { keep, keep };
@@ -314,8 +324,8 @@ translate_each({ quote, Meta, [T] }, S) when is_list(T) ->
     _ -> true
   end,
 
-  Q = #elixir_quote{var_context=Context, line=TLine, unquote=Unquote,
-        expand_aliases=Aliases, expand_imports=Imports},
+  Q = #elixir_quote{vars_hygiene=Vars, line=TLine, unquote=Unquote,
+        aliases_hygiene=Aliases, imports_hygiene=Imports},
 
   elixir_quote:quote(TExprs, Q, SL);
 
@@ -468,11 +478,11 @@ translate_each({ { '.', _, [Left, Right] }, Meta, Args } = Original, S) when is_
 
 %% Anonymous function calls
 
-translate_each({ { '.', Line, [Expr] }, Meta, Args } = Original, S) ->
+translate_each({ { '.', _, [Expr] }, Meta, Args } = Original, S) ->
   { TExpr, SE } = translate_each(Expr, S),
   case TExpr of
     { atom, _, Atom } ->
-      elixir_errors:deprecation(?line(Line), S#elixir_scope.file, "the :~s.() syntax is deprecated, please use ~s() instead", [Atom, Atom]),
+      elixir_errors:deprecation(Meta, S#elixir_scope.file, "the :~s.() syntax is deprecated, please use ~s() instead", [Atom, Atom]),
       translate_each({ Atom, Meta, Args }, S);
     _ ->
       case elixir_partials:handle(Original, S) of

lib/elixir/test/elixir/code_test.exs

@@ -61,8 +61,8 @@ defmodule CodeTest do
   end
 
   test :string_to_ast do
-    assert Code.string_to_ast("1 + 2") == { :ok, quote hygiene: false, line: 1, do: 1 + 2 }
-    assert Code.string_to_ast("1 + 2; 3 + 4") == { :ok, quote hygiene: false, line: 1, do: (1 + 2; 3 + 4) }
+    assert Code.string_to_ast("1 + 2") == { :ok, quote hygiene: [imports: false], line: 1, do: 1 + 2 }
+    assert Code.string_to_ast("1 + 2; 3 + 4") == { :ok, quote hygiene: [imports: false], line: 1, do: (1 + 2; 3 + 4) }
     assert { :error, _ } = Code.string_to_ast("a.1")
   end
 
@@ -72,7 +72,7 @@ defmodule CodeTest do
   end
 
   test :string_to_ast! do
-    assert Code.string_to_ast!("1 + 2") == quote hygiene: false, line: 1, do: 1 + 2
+    assert Code.string_to_ast!("1 + 2") == quote hygiene: [imports: false], line: 1, do: 1 + 2
 
     assert_raise SyntaxError, fn ->
       Code.string_to_ast!("a.1")

lib/elixir/test/elixir/kernel/quote_test.exs

@@ -90,7 +90,7 @@ defmodule Kernel.QuoteTest.VarHygiene do
   end
 
   defmacro no_hygiene do
-    quote [hygiene: false] do
+    quote [hygiene: [vars: false]] do
       a = 1
     end
   end

lib/elixir/test/elixir/module_test.exs

@@ -57,7 +57,7 @@ defmodule ModuleTest do
   Module.eval_quoted __MODULE__, contents, [], file: "sample.ex", line: 13
 
   defmacrop in_module(block) do
-    quote expand_aliases: false do
+    quote do
       defmodule Temp, unquote(block)
       :code.purge(Temp)
       :code.delete(Temp)