1 Introduction

1.5 The LFE REPL

1.5.1 Using the REPL

We covered basic REPL usage in the quick start. We'll provide some information about the REPL in the document you are currently reading :-) Starting the REPL

If you don't have LFE installed system-wide, you need to tell it (Erlang, really) where the LFE .beam files are. Here are the three ways to start up LFE in this case. The easiest is lfetool:

    $ lfetool repl lfe

If you're project was built with lfetool, then you'll have a make target called shell; calling this will first compile your source files and then call out to lfetool. Due to the compiling, this is a little slower way to start the REPL (though better for debugging!):

    $ make repl

The nice thing about both of these is that they automatically add your dependencies to ERL_LIBS so you have access to everything you need in the REPL itself.

Here are some more ways to start the REPL that don't take care of these niceties for you:

    $ ./bin/lfe -pa ./ebin
    LFE Shell V5.10.4 (abort with ^G)
    $ erl -user lfe_boot -pa /path/to/lfe/ebin
    LFE Shell V5.10.4 (abort with ^G)

You can also start an LFE REPL from the Erlang shell. First hop into erl:

    $ erl -pa /path/to/lfe/ebin
    Eshell V5.10.4  (abort with ^G)

then fire up LFE:

    1> lfe_shell:server().
    LFE Shell V5.10.4 (abort with ^G)

If you do have LFE installed system-wide, then starting the shell can be done in the ways listed below.

    $ lfe

You can also start the LFE REPL by passing options directly to erl. Again, assuming that you have LFE installed system-wide, from any directory you may do this:

    $ erl -user lfe_boot

Also, if you happen to be running an Erlang shell already, you can start the LFE REPL with the following:

14> lfe_shell:server().
LFE Shell V5.9.3.1 (abort with ^G)
> Running Commands

Once you're in the REPL, it's just a matter of entering code:

> (+ 1.5 3 4 5 6 7)

Unlike the Erlang shell, the LFE REPL supports defining functions:

> (defun exp (x y)
    (trunc (math:pow x y)))

Let's put that exp to use:

> (exp 2 6)

You could take the lambda route too:

> (set exp
    (lambda (x y)
        (trunc (math:pow x y))))

And, if you want to get nuts:

> (lists:map
    (lambda (z)
      (funcall exp (car z) (cadr z)))
    (list (list 1.5 0) (list 3 4) (list 5 6)))
(1 81 15625)
> Quitting the REPL

Just as there are multiple ways in which you can start the REPL, there are a couple ways you can leave it. You can jump into the JCL from the LFE prompt by hitting ^g and then entering q:

> ^g
User switch command
 --> q

or you can call the Erlang shell's quit function:

> (c:q)

Or simplest of all, the LFE exit command:

> (exit)

1.5.2 Special Functions

There are some functions specially defined in LFE for use from the REPL. These are listed below with information about their use.

  • (c File [Options]) - Compile and load an LFE file. Assumes default extension .lfe.

  • (l Module ...) - Load modules.

  • (m Module ...) - Print out module information, if no modules are given then print information about all modules.

  • (ec File [Options]) - Compile and load an Erlang file.

  • (slurp File) - Slurp in a source LFE file and makes all functions and macros defined in the file available in the shell. Only one file can be slurped at a time and slurping a new file removes all data about the previous one.

  • (unslurp) - Remove all function and macro definitions except the default ones.

  • (set Pattern Expr) - Evaluate Expr and match the result with Pattern binding variables in it. These variables can then be used in the shell and also rebound in another set.

  • (c:command-arg ...) - All the commands in the Erlang shell's Command Interface Module can be reached in this way.

1.5.3 Special Variables

LFE also provides some convenience variables similar to what Lisp has defined for +, ++, +++, , *, ***, and -. Additionally, LFE also provides the $ENV variable.

  • +/++/+++ - The three previous expressions input.
  • */**/*** - The values of the previous 3 expressions.
  • - - The current expression input.
  • $ENV - The current environment (accessible in the REPL as well as in macros).

These probably warrant some examples.

Let's say you had just entered the following in the REPL:

> (+ 1.5 1.5)
> (c:memory)
(#(total 10026672)
 #(processes 1656528)
 #(processes_used 1656528)
 #(system 8370144)
 #(atom 153321)
 #(atom_used 147399)
 #(binary 1338560)
 #(code 3255239)
 #(ets 290544))
> (set my-func (lambda () (io:format "Hello, Zaphod!~n")))

Then you can get the previous expressions you input with the following commands:

> +++
(+ 1.5 1.5)
> +++
> +++
(set my-func (lambda () (io:format "Hello, Zaphod!~n")))
> ++
> +

Most of us will actually use the arrow keys, thanks to the readline library. However, the classic, pre-readline approach is still available, should you choose to use it.

Similarly, you can get the results returned by using the variabels from the second bullet item. If you're following along in the REPL, go ahead and re-enter the commands we typed above to reset the last three items in your command history. Then do the following:

> ***
> ***
(#(total 9976496)
 #(processes 1606688)
 #(processes_used 1606688)
 #(system 8369808)
 #(atom 153321)
 #(atom_used 147399)
 #(binary 1338096)
 #(code 3255239)
 #(ets 290544))
> ***
> (funcall *)
Hello, Zaphod!

There's another, called the "dash" varibale. It is bound to the actual expression that is currently being evaluated. Here's an example of this being used:

> (io:format "Evaluating the expression '~p' ...~n" (list -))
Evaluating the expression '[':',io,format,
                            [quote,"Evaluating the expression '~p' ...~n"],
                            [list,'-']]' ...

We've saved one of the more archane special variables to last: $ENV. When you first start up a shell, the $ENV variable holds pristine state data:

> $ENV

We can define a few variables and then check them out with another display of the environment:

> (set my-var 42)
> $ENV
   #(my-var 42)

If you slurp a file in the REPL, your environment will be updated with all the definitions in that file:

> (slurp "../lfe/examples/joes-fav.lfe")
#(ok joes-fav)
> $ENV
  (#(MODULE #(macro (match-lambda (((list) $ENV) `'joes-fav))))

There is, as you might have guessed, much more to that ellided output (for that particular example, nearly all the rest of it is macro definitions).

Making use of $ENV can be very helpful when debugging include files, loading Erlang header files, or when creating macros. Furthermore, when spending a great deal of time in the REPL prototyping code for a project, it can be quite useful to refresh one's memory as to what functions and variables are currently available in $ENV.

Looking at the output for $ENV can be a bit overwhelming, however. As you might imagine, there is an easy answer to this: filter it! The following makes use of the Erlang lists module as well as patterns in an anonymous function, both of which will be covered in more detail later. This will prevent most nested variables from being displayed:

> (defun filter-env (env)
      (lambda (section)
            ((`#(* ,_)))
            ((`#(** ,_)))
            ((`#(*** ,_)))
            ((`#(+ ,_)))
            ((`#(++ ,_)))
            ((`#(+++ ,_)))
            ((`#(- ,_)))
            ((`#(,name ,value))
              (lfe_io:format "~s: ~p~n" `(,name ,value)))
            ((x) (filter-env `#(env ,x))))
      (lists:nthtail 1 (tuple_to_list env))))

Now, as one hacks away in the REPL, slurping away at various modules, getting a list of what's defined in the current environment is a piece of cake:

> (filter-env $ENV)
my-var: 42
my-func: #Fun<lfe_eval.23.86468545>
script-args: ()
script-name: "lfe"
MODULE: #(macro (match-lambda (((list) $ENV) `'joes-fav)))
c: #(macro (lambda (args $ENV) `(: lfe_shell c ,@args)))
ec: #(macro (lambda (args $ENV) `(: lfe_shell ec ,@args)))
exit: #(function (#(0 #(dynamic_expr (lambda () (: lfe_shell exit))))))
factorial: #(function

1.5.4 Getting Out of Trouble

Every once in a while you may find that you do something which causes the REPL to crash, presenting you with something that looks like this:

      =ERROR REPORT==== 17-Feb-2013::15:39:33 ===

You don't have to quit and restart the REPL, if you don't want to! There are a couple of steps that you can take instead. Interrupting a Shell Process

When you get an error as seen above, type ^g. This will put you into JCL (Job Control Language) mode. At the JCL prompt, type ? to see a list of options:

    User switch command
     --> ?
      c [nn]            - connect to job
      i [nn]            - interrupt job
      k [nn]            - kill job
      j                 - list all jobs
      s [shell]         - start local shell
      r [node [shell]]  - start remote shell
      q        - quit erlang
      ? | h             - this message

Let's see what's running:

    --> j
      1* {lfe_shell,start,[]}

Our shell process is still alive, though not responding. Let's interrupt it and then connect to it again:

    --> i 1
    --> c 1
    exception error: function_clause
     in (: lists sublist #(error interrupted) 1)
     in (lfe_scan string 4)
     in (lfe_io scan_and_parse 3)


Once we interrupted the job, our error messages were printed to the REPL and we were placed back at the LFE prompt. Starting a New Shell

Sometimes, though, there is no shell process any more. Here's how to start up a new shell process if the one that you're using dies:

    --> s lfe_shell
    --> j
          2* {lfe_shell,start,[]}
    --> c 2
    LFE Shell V5.9.3.1 (abort with ^G)

And you're back up!