Merge pull request #1096 from alco/iex-break-1089

Implement a break-trigger for incomplete expressions in IEx.

Author: José Valim

lib/iex/lib/iex/helpers.ex

@@ -6,7 +6,7 @@ defmodule IEx.Helpers do
   more joyful to work with.
 
   This message was triggered by invoking the helper
-  `h()`, usually referred as `h/0` (since it expects 0
+  `h()`, usually referred to as `h/0` (since it expects 0
   arguments).
 
   There are many other helpers available:
@@ -37,6 +37,36 @@ defmodule IEx.Helpers do
       h(Enum)
       h(Enum.reverse/1)
 
+
+  ## A note about expressions in IEx ##
+
+  IEx treats incomplete expressions in a special way, allowing one
+  to spill an expression over multiple lines. For example,
+
+      iex(1)> "ab
+      ...(1)> c"
+      "ab\nc"
+
+  In the example above, the shell will be expecting more input until it finds
+  the closing quote. Sometimes it is not obvious which character the shell is
+  expecting, and the user may find themselves trapped in the state of
+  incomplete expression with no ability to terminate it other than by exiting
+  the shell.
+
+  For such cases, there is a special break-trigger ("#iex:break") that when
+  encountered on a line by itself will force the shell to break out of any
+  pending expression and return to its normal state:
+
+      iex(1)> ["ab
+      ...(1)> c"
+      ...(1)> "
+      ...(1)> ]
+      ...(1)> #iex:break
+      ** (TokenMissingError) iex:1: incomplete expression
+          ...
+
+      iex(1)>
+
   """
 
   @doc """

lib/iex/lib/iex/server.ex

@@ -18,11 +18,12 @@ defmodule IEx.Server do
 
   defp do_loop(config) do
     counter = config.counter
-    code    = config.cache ++ io_get(config)
+    code    = config.cache
+    line    = io_get(config)
 
     new_config =
       try do
-        eval(code, counter, config)
+        eval(code, line, counter, config)
       rescue
         exception ->
           print_stacktrace System.stacktrace, fn ->
@@ -49,9 +50,24 @@ defmodule IEx.Server do
   # to re-raise it.
   #
   # Returns updated config.
-  defp eval(code, line, config) do
-    file = "iex"
-    case :elixir_translator.forms(code, line, file, []) do
+  #
+  # The first two clauses provide support for the break-trigger allowing to
+  # break out from a pending incomplete expression. See
+  # https://github.com/elixir-lang/elixir/issues/1089 for discussion.
+  #
+  @break_trigger '#iex:break\n'
+  defp eval(_, @break_trigger, _, config=IEx.Config[cache: '']) do
+    # do nothing
+    config
+  end
+
+  defp eval(_, @break_trigger, line_no, _) do
+    :elixir_errors.parse_error(line_no, "iex", 'incomplete expression', [])
+  end
+
+  defp eval(code_so_far, latest_input, line_no, config) do
+    code = code_so_far ++ latest_input
+    case :elixir_translator.forms(code, line_no, "iex", []) do
       { :ok, forms } ->
         { result, new_binding, scope } =
           :elixir.eval_forms(forms, config.binding, config.scope)
@@ -62,14 +78,14 @@ defmodule IEx.Server do
         update_history(config.cache(code).scope(nil))
         config.update_counter(&1+1).cache('').binding(new_binding).scope(scope)
 
-      { :error, { line, error, token } } ->
+      { :error, { line_no, error, token } } ->
         if token == [] do
           # Update config.cache so that IEx continues to add new input to
           # the unfinished expression in `code`
           config.cache(code)
         else
           # Encountered malformed expression
-          :elixir_errors.parse_error(line, file, error, token)
+          :elixir_errors.parse_error(line_no, "iex", error, token)
         end
     end
   end