Merge pull request #1100 from alco/dot-iex

Add support for .iex files

Author: José Valim

CHANGELOG.md

@@ -1,6 +1,8 @@
 # v0.9.0.dev
 
 * enhancements
+  * [IEx] Add support for .iex files that are loaded during shell's boot process
+  * [IEx] Add `import_file/1` helper
 
 * bug fix
 

bin/iex

@@ -14,6 +14,8 @@ if [ $# -gt 0 ] && ([ $1 = "--help" ] || [ $1 = "-h" ]); then
   --name \"name\"     Makes and assigns a name to the distributed node
   --sname \"name\"    Makes and assigns a short name to the distributed node
   --remsh \"name\"    Connects to a node using a remote shell
+  --dot-iex \"path\"  Overrides default .iex file and uses path instead;
+                    path can be empty, then no file will be loaded
 
 ** Options marked with (*) can be given more than once
 ** Options given after the .exs file or -- are passed down to the executed code
@@ -33,4 +35,4 @@ readlink_f () {
 
 SELF=$(readlink_f "$0")
 SCRIPT_PATH=$(dirname "$SELF")
-ELIXIR_NO_CLI=1 exec "$SCRIPT_PATH"/elixir --no-halt --erl "-user Elixir-IEx-CLI" +iex "$@"
+ELIXIR_NO_CLI=1 exec "$SCRIPT_PATH"/elixir --no-halt --erl "-user Elixir-IEx-CLI" +iex "$@"

lib/elixir/lib/kernel/cli.ex

@@ -222,6 +222,12 @@ defmodule Kernel.CLI do
     { config, t }
   end
 
+  # This clause is here so that Kernel.CLI does not error out with "unknown
+  # option"
+  defp process_iex(["--dot-iex",_|t], config) do
+    process_iex t, config
+  end
+
   defp process_iex([opt,_|t], config) when opt in ["--remsh"] do
     process_iex t, config
   end

lib/elixir/src/elixir.erl

@@ -1,7 +1,8 @@
 -module(elixir).
 -behaviour(application).
 -export([main/1, start_cli/0,
-  scope_for_eval/1, eval/2, eval/3, eval/4,
+  scope_for_eval/1, scope_for_eval/2,
+  eval/2, eval/3, eval/4,
   eval_quoted/2, eval_quoted/3, eval_quoted/4,
   eval_forms/3, translate_forms/3]).
 -include("elixir.hrl").
@@ -46,37 +47,47 @@ start_cli() ->
 %% EVAL HOOKS
 
 scope_for_eval(Opts) ->
-  case lists:keyfind(file, 1, Opts) of
-    { file, RawFile } -> File = to_binary(RawFile);
-    false -> File = <<"nofile">>
+  scope_for_eval(#elixir_scope{
+    file = <<"nofile">>,
+    local = nil,
+    aliases = [],
+    requires = elixir_dispatch:default_requires(),
+    functions = elixir_dispatch:default_functions(),
+    macros = elixir_dispatch:default_macros()
+  }, Opts).
+
+scope_for_eval(Scope, Opts) ->
+  File = case lists:keyfind(file, 1, Opts) of
+    { file, RawFile } -> to_binary(RawFile);
+    false -> Scope#elixir_scope.file
   end,
 
-  case lists:keyfind(delegate_locals_to, 1, Opts) of
-    { delegate_locals_to, Local } -> Local;
-    false -> Local = nil
+  Local = case lists:keyfind(delegate_locals_to, 1, Opts) of
+    { delegate_locals_to, LocalOpt } -> LocalOpt;
+    false -> Scope#elixir_scope.local
   end,
 
-  case lists:keyfind(aliases, 1, Opts) of
-    { aliases, Aliases } -> Aliases;
-    false -> Aliases = []
+  Aliases = case lists:keyfind(aliases, 1, Opts) of
+    { aliases, AliasesOpt } -> AliasesOpt;
+    false -> Scope#elixir_scope.aliases
   end,
 
-  case lists:keyfind(requires, 1, Opts) of
-    { requires, List } -> Requires = ordsets:from_list(List);
-    false -> Requires = elixir_dispatch:default_requires()
+  Requires = case lists:keyfind(requires, 1, Opts) of
+    { requires, List } -> ordsets:from_list(List);
+    false -> Scope#elixir_scope.requires
   end,
 
-  case lists:keyfind(functions, 1, Opts) of
-    { functions, Functions } -> Functions;
-    false -> Functions = elixir_dispatch:default_functions()
+  Functions = case lists:keyfind(functions, 1, Opts) of
+    { functions, FunctionsOpt } -> FunctionsOpt;
+    false -> Scope#elixir_scope.functions
   end,
 
-  case lists:keyfind(macros, 1, Opts) of
-    { macros, Macros } -> Macros;
-    false -> Macros = elixir_dispatch:default_macros()
+  Macros = case lists:keyfind(macros, 1, Opts) of
+    { macros, MacrosOpt } -> MacrosOpt;
+    false -> Scope#elixir_scope.macros
   end,
 
-  #elixir_scope{
+  Scope#elixir_scope{
     file=File, local=Local,
     macros=Macros, functions=Functions,
     requires=Requires, aliases=Aliases }.

lib/iex/lib/iex.ex

@@ -1,10 +1,11 @@
-defrecord IEx.Config, binding: nil, cache: '', counter: 1, scope: nil, result: nil
+defrecord IEx.Config, binding: nil, cache: '', counter: 1, scope: nil,
+                      result: nil, dot_iex_path: nil
 
 defmodule IEx do
   @moduledoc %B"""
   Welcome to IEx.
 
-  This module is the main entry point Interactive Elixir and
+  This module is the main entry point for Interactive Elixir and
   in this documentation we will talk a bit about how IEx works.
 
   Notice some of the functionality described here will be available
@@ -20,11 +21,11 @@ defmodule IEx do
 
   ## The User Switch command
 
-  Besides the break command, one can type Ctrl+G to get the to
-  the user switch command. When reached, you can type `h` to
+  Besides the break command, one can type Ctrl+G to get to the
+  user switch command menu. When reached, you can type `h` to
   get more information.
 
-  In this switch, developers are able to create new shell and
+  In this menu, developers are able to start new shells and
   alternate in between them. Let's give it a try:
 
       User switch command
@@ -36,7 +37,7 @@ defmodule IEx do
 
       hello = :world
 
-  Now, let's rollback to the first shell:
+  Now, let's roll back to the first shell:
 
       User switch command
        --> c 1
@@ -46,23 +47,57 @@ defmodule IEx do
       hello
       ** (UndefinedFunctionError) undefined function: IEx.Helpers.hello/0
 
-  The command above fails because we have changed the shells
-  and they are isolated from each other, you can access the
-  variables defined in one in the other.
+  The command above fails because we have switched the shells.
+  Since shells are isolated from each other, you can't access the
+  variables defined in one shell from the other one.
 
-  The User Switch also allow developers to connect to remote
-  shells using r. Keep in mind that you can't connect to a
+  The user switch command menu also allows developers to connect to remote
+  shells using the "r" command. Keep in mind that you can't connect to a
   remote node if you haven't given a name to the current node
   (i.e. Process.is_alive? must return true).
 
+  ## The .iex file
+
+  When starting IEx, it will look for a local .iex file (located in the current
+  working directory), then a global one (located at ~/.iex) and will load the
+  first one it finds (if any). The code in the chosen .iex file will be
+  evaluated in the shell's context. So, for instance, any modules that are
+  loaded or variables that are bound in the .iex file will be available in the
+  shell after it has booted.
+
+  Sample contents of a local .iex file:
+
+      # source another .iex file
+      import_file "~/.iex"
+
+      # print something before the shell starts
+      IO.puts "hello world"
+
+      # bind a variable that'll be accessible in the shell
+      value = 13
+
+  Running the shell in the directory where the above .iex file is located
+  results in
+
+      $ iex
+      Erlang R15B03 (erts-5.9.3.1) [...]
+
+      hello world
+      Interactive Elixir (0.8.3.dev) - press Ctrl+C to exit (type h() ENTER for help)
+      iex(1)> value
+      13
+
+  It is possible to override the default loading sequence for .iex file by
+  supplying the --dot-iex option to iex. See `iex --help`.
+
   ## Expressions in IEx
 
   As an interactive shell, IEx evalutes expressions. This has some
-  interesting consequences worthy discussing.
+  interesting consequences that are worth discussing.
 
   The first one is that the code is truly evaluated and not compiled.
-  This means that, any benchmarking done in the shell is going to have
-  skewed results. So never run any profiling nor benchmark in the shell.
+  This means that any benchmarking done in the shell is going to have
+  skewed results. So never run any profiling nor benchmarks in the shell.
 
   Second of all, IEx alows you to break an expression into many lines,
   since this is common in Elixir. For example:
@@ -173,7 +208,8 @@ defmodule IEx do
 
     IEx.Config[
       binding: opts[:binding] || [],
-      scope: scope
+      scope: scope,
+      dot_iex_path: Keyword.get(opts, :dot_iex_path),
     ]
   end
 

lib/iex/lib/iex/cli.ex

@@ -19,7 +19,8 @@ defmodule IEx.CLI do
     else
       :user.start
       IO.puts "Warning: could not run smart terminal, falling back to dumb one"
-      IEx.start([], fn -> :elixir.start_cli end)
+      config = [dot_iex_path: find_dot_iex(:init.get_plain_arguments)]
+      IEx.start(config, fn -> :elixir.start_cli end)
     end
   end
 
@@ -37,12 +38,15 @@ defmodule IEx.CLI do
   end
 
   defp tty do
+    plain_args = :init.get_plain_arguments
+
+    config = [dot_iex_path: find_dot_iex(plain_args)]
     function = fn ->
-      IEx.start([], fn -> :elixir.start_cli end)
+      IEx.start(config, fn -> :elixir.start_cli end)
     end
 
     args =
-      if remote = get_remsh(:init.get_plain_arguments) do
+      if remote = get_remsh(plain_args) do
         unless is_alive do
           function = fn ->
             IO.puts(:stderr, "In order to use --remsh, you need to name the current node using --name or --sname. Aborting...")
@@ -60,6 +64,10 @@ defmodule IEx.CLI do
     :user_drv.start([:"tty_sl -c -e", args])
   end
 
+  defp find_dot_iex(['--dot-iex',h|_]), do: :unicode.characters_to_binary(h)
+  defp find_dot_iex([_|t]), do: find_dot_iex(t)
+  defp find_dot_iex([]), do: nil
+
   defp get_remsh(['--remsh',h|_]), do: list_to_atom(h)
   defp get_remsh([_|t]), do: get_remsh(t)
   defp get_remsh([]), do: nil

lib/iex/lib/iex/helpers.ex

@@ -25,6 +25,7 @@ defmodule IEx.Helpers do
   * `t/1` — prints type information
   * `v/0` - prints all commands and values
   * `v/1` - retrieves nth value from console
+  * `import_file/1` - evaluate the given file in the shell's context
 
   Help for functions in this module can be consulted
   directly from the command line, as an example, try:
@@ -54,7 +55,6 @@ defmodule IEx.Helpers do
 
       c "baz.ex"
       #=> [Baz]
-
   """
   def c(files, path // ".") do
     tuples = Kernel.ParallelCompiler.files_to_path List.wrap(files), path
@@ -111,7 +111,6 @@ defmodule IEx.Helpers do
       h receive/1
       h Enum.all?/2
       h Enum.all?
-
   """
   defmacro h({ :/, _, [{ { :., _, [mod, fun] }, _, [] }, arity] }) do
     quote do
@@ -154,7 +153,6 @@ defmodule IEx.Helpers do
       t(Enum)
       t(Enum.t/0)
       t(Enum.t)
-
   """
   defmacro t({ :/, _, [{ { :., _, [mod, fun] }, _, [] }, arity] }) do
     quote do
@@ -188,7 +186,6 @@ defmodule IEx.Helpers do
       s(Enum.all?/2)
       s(list_to_atom)
       s(list_to_atom/1)
-
   """
   defmacro s({ :/, _, [{ { :., _, [mod, fun] }, _, [] }, arity] }) do
     quote do
@@ -375,4 +372,30 @@ defmodule IEx.Helpers do
         representation
     end
   end
+
+  @doc """
+  Evaluates the contents of file at `path` as if it were directly typed into
+  the shell. `path` has to be a literal binary.
+
+  Leading `~` in `path` is automatically expanded.
+
+  ## Examples
+
+      # ~/file.exs
+      value = 13
+
+      # in the shell
+      iex(1)> import_file "~/file.exs"
+      13
+      iex(2)> value
+      13
+  """
+  defmacro import_file(path) when is_binary(path) do
+    path = Path.expand(path)
+    Code.string_to_ast! File.read!(path), file: path
+  end
+
+  defmacro import_file(_) do
+    raise ArgumentError, message: "import_file/1 expects a literal binary as its argument"
+  end
 end