Add handle_begin and handle_end to EEx

Elixir v1.5.0 attempted to repurpose the value of init
to use throughout the engine but such was a breaking change.

To address this problem, we added handle_begin and
handle_end which were designed exactly to handle inner
buffers.

This comes with the benefit that EEx.Engine can now have
any data structure as state and no longer only quoted
expressions.

Closes #6391.

Author: José Valim

lib/eex/lib/eex/compiler.ex

@@ -16,10 +16,10 @@ defmodule EEx.Compiler do
     trim = opts[:trim] || false
     case EEx.Tokenizer.tokenize(source, line, trim: trim) do
       {:ok, tokens} ->
-        state = %{engine: opts[:engine] || @default_engine, init: nil,
+        state = %{engine: opts[:engine] || @default_engine,
                   file: file, line: line, quoted: [], start_line: nil}
         init = state.engine.init(opts)
-        generate_buffer(tokens, init, [], %{state | init: init})
+        generate_buffer(tokens, init, [], state)
       {:error, line, message} ->
         raise EEx.SyntaxError, line: line, file: file, message: message
     end
@@ -42,15 +42,15 @@ defmodule EEx.Compiler do
   defp generate_buffer([{:start_expr, start_line, mark, chars} | rest], buffer, scope, state) do
     {contents, line, rest} = look_ahead_text(rest, start_line, chars)
     {contents, rest} =
-      generate_buffer(rest, state.init, [contents | scope],
+      generate_buffer(rest, state.engine.handle_begin(buffer), [contents | scope],
                       %{state | quoted: [], line: line, start_line: start_line})
     buffer = state.engine.handle_expr(buffer, IO.chardata_to_string(mark), contents)
     generate_buffer(rest, buffer, scope, state)
   end
 
   defp generate_buffer([{:middle_expr, line, '', chars} | rest], buffer, [current | scope], state) do
     {wrapped, state} = wrap_expr(current, line, buffer, chars, state)
-    generate_buffer(rest, state.init, [wrapped | scope], %{state | line: line})
+    generate_buffer(rest, state.engine.handle_begin(buffer), [wrapped | scope], %{state | line: line})
   end
 
   defp generate_buffer([{:middle_expr, line, modifier, chars} | t], buffer, scope, state) do
@@ -99,7 +99,7 @@ defmodule EEx.Compiler do
     key = length(state.quoted)
     placeholder = '__EEX__(' ++ Integer.to_charlist(key) ++ ');'
     {current ++ placeholder ++ new_lines ++ chars,
-     %{state | quoted: [{key, buffer} | state.quoted]}}
+     %{state | quoted: [{key, state.engine.handle_end(buffer)} | state.quoted]}}
   end
 
   # Look text ahead on expressions

lib/eex/lib/eex/engine.ex

@@ -2,19 +2,26 @@ defmodule EEx.Engine do
   @moduledoc ~S"""
   Basic EEx engine that ships with Elixir.
 
-  An engine needs to implement four functions:
+  An engine needs to implement six functions:
 
-    * `init(opts)` - returns the initial buffer
+    * `init(opts)` - called at the beginning of every text
+      and it must return the initial state.
 
-    * `handle_body(quoted)` - receives the final built quoted
-      expression, should do final post-processing and return a
-      quoted expression.
+    * `handle_body(state)` - receives the state of the document
+      and it must return a quoted expression.
 
-    * `handle_text(buffer, text)` - it receives the buffer,
+    * `handle_text(state, text)` - it receives the state,
       the text and must return a new quoted expression.
 
-    * `handle_expr(buffer, marker, expr)` - it receives the buffer,
-      the marker, the expr and must return a new quoted expression.
+    * `handle_expr(state, marker, expr)` - it receives the state,
+      the marker, the expr and must return a new state.
+
+    * `handle_begin(state)` - called every time there a new state
+      is needed with an empty buffer. Typically called for do/end
+      blocks, case expressions, anonymous functions, etc
+
+    * `handle_end(state)` - opposite of `handle_begin(state)` and
+      it must return quoted expression
 
       The marker is what follows exactly after `<%`. For example,
       `<% foo %>` has an empty marker, but `<%= foo %>` has `"="`
@@ -27,10 +34,14 @@ defmodule EEx.Engine do
   default implementations for the functions above.
   """
 
-  @callback init(opts :: keyword) :: Macro.t
-  @callback handle_body(quoted :: Macro.t) :: Macro.t
-  @callback handle_text(buffer :: Macro.t, text :: String.t) :: Macro.t
-  @callback handle_expr(buffer :: Macro.t, marker :: String.t, expr :: Macro.t) :: Macro.t
+  @type state :: term
+
+  @callback init(opts :: keyword) :: state
+  @callback handle_body(state) :: Macro.t
+  @callback handle_text(state, text :: String.t) :: state
+  @callback handle_expr(state, marker :: String.t, expr :: Macro.t) :: state
+  @callback handle_begin(state) :: state
+  @callback handle_end(state) :: Macro.t
 
   @doc false
   defmacro __using__(_) do
@@ -45,6 +56,14 @@ defmodule EEx.Engine do
         EEx.Engine.handle_body(quoted)
       end
 
+      def handle_begin(quoted) do
+        EEx.Engine.handle_begin(quoted)
+      end
+
+      def handle_end(quoted) do
+        EEx.Engine.handle_end(quoted)
+      end
+
       def handle_text(buffer, text) do
         EEx.Engine.handle_text(buffer, text)
       end
@@ -104,6 +123,20 @@ defmodule EEx.Engine do
     ""
   end
 
+  @doc """
+  Returns an empty string as the new buffer.
+  """
+  def handle_begin(_previous) do
+    ""
+  end
+
+  @doc """
+  End of the new buffer.
+  """
+  def handle_end(quoted) do
+    quoted
+  end
+
   @doc """
   The default implementation simply returns the given expression.
   """

lib/eex/test/eex_test.exs

@@ -436,25 +436,38 @@ defmodule EExTest do
     @behaviour EEx.Engine
 
     def init(_opts) do
-      ""
+      "INIT"
     end
 
     def handle_body(body) do
-      {:wrapped, body}
+      "BODY(#{body})"
+    end
+
+    def handle_begin(_) do
+      "BEGIN"
+    end
+
+    def handle_end(buffer) do
+      buffer <> ":END"
     end
 
     def handle_text(buffer, text) do
-      EEx.Engine.handle_text(buffer, text)
+      buffer <> ":TEXT(#{String.trim(text)})"
     end
 
-    def handle_expr(buffer, mark, expr) do
-      EEx.Engine.handle_expr(buffer, mark, expr)
+    def handle_expr(buffer, "=", expr) do
+      buffer <> ":EQUAL(#{Macro.to_string(expr)})"
     end
   end
 
   describe "custom engines" do
-    test "calls handle_body" do
-      assert {:wrapped, "foo"} = EEx.eval_string("foo", [], engine: TestEngine)
+    test "text" do
+      assert_eval "BODY(INIT:TEXT(foo))", "foo", [], engine: TestEngine
+    end
+
+    test "begin/end" do
+      assert_eval ~s[BODY(INIT:TEXT(foo):EQUAL(if() do\n  "BEGIN:TEXT(this):END"\nelse\n  "BEGIN:TEXT(that):END"\nend))],
+                  "foo <%= if do %>this<% else %>that<% end %>", [], engine: TestEngine
     end
   end