1 Introduction

1.5 The LFE REPL

1.5.1 Using the REPL

We covered basic REPL usage in the quick start. That's the best place to go for an introduction to using the LFE REPL. Regardless (and for your convenience), we also provide some information about the REPL in the document you are currently reading :-)

1.5.1.1 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:

$ ./bin/lfe -pa ./ebin

or:

$ erl -user lfe_boot -pa /path/to/lfe/ebin

or:

$ erl -pa /path/to/lfe/ebin

followed by this from the Erlang shell:

14> lfe_shell:start().
LFE Shell V5.9.3.1 (abort with ^G)
<0.33.0>

>

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

Using the lfe command. Be sure to change directory to where you have saved (or cloned) the LFE source code. Then:

$ ./bin/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:start().
LFE Shell V5.9.3.1 (abort with ^G)
<0.33.0>

>

1.5.1.2 Running Commands

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

> (+ 1.5 3 4 5 6 7)
28
>

Note that you can't define modules, macros, functions or records from the REPL; you'll have to put those in a module file and compile or slurp the file from the REPL. You can, however, use lambda from the REPL:

> (set exp
    (lambda (x y)
      (trunc (: math pow x y))))
#Fun<lfe_eval.15.53503600>
>

Then, using the lambda you have just defined is as easy as this:

> (funcall exp 2 6)
64
>

Or, if you want to get nuts:

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

1.5.1.3 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)
ok
>
$

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)
3
> (: 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!")))
#Fun<lfe_eval.21.53503600>
>

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

> +++
(+ 1.5)
> +++
(: c memory)
> +++
(set my-func (lambda () (: io format '"Hello, Zaphod!")))
> ++
+++
> +
++
>

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:

> ***
3
> ***
(#(total 9976496)
 #(processes 1606688)
 #(processes_used 1606688)
 #(system 8369808)
 #(atom 153321)
 #(atom_used 147399)
 #(binary 1338096)
 #(code 3255239)
 #(ets 290544))
> ***
#Fun<lfe_eval.21.53503600>
> (funcall *)
Hello, Zaphod!
ok
>

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,'-']]' ...
ok
>

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
(#(variable *** ())
 #(variable ** ())
 #(variable * ())
 #(variable - ())
 #(variable +++ ())
 #(variable ++ ())
 #(variable + ()))
>

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

> $ENV
(#(variable my-func #Fun<lfe_eval.10.53503600>)
 #(variable asnwer 42)
 #(variable *** 42)
 #(variable
...

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

> (slurp '"examples/core-macros.lfe")
#(ok -no-mod-)
> $ENV
(#(function
   bq-expand
   2
   #(letrec
     (lambda (exp n)
...

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:

> (set filter-env
    (lambda (env)
      (: lists foreach
        (match-lambda
          (((tuple 'function func-name arity _))
           (: io format '"function: ~p/~p~n" (list func-name arity)))
          (((tuple 'macro macro-name _))
           (: io format '"macro: ~p~n" (list macro-name)))
          (((tuple 'variable var-name value))
           (: io format '"variable: ~p~n" (list var-name)))
          ((_)))
        env)))
#Fun<lfe_eval.21.53503600>

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:

> (funcall filter-env $ENV)
variable: 'my-var-4'
variable: 'my-var-3'
variable: 'my-var-2'
variable: 'my-var-1'
variable: filter
function: 'bq-expand'/2
macro: backquote
macro: 'orelse'
macro: 'andalso'
macro: 'cond'
macro: 'flet*'
macro: 'let*'
macro: 'list*'
macro: '?'
macro: ':'
macro: '++'
macro: cddr
macro: cdar
macro: cadr
macro: caar
variable: '***'
variable: '**'
variable: '*'
variable: '-'
variable: '+++'
variable: '++'
variable: '+'
ok
>

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.

1.5.4.1 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.

1.5.4.2 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!