README.md

# LFE

LFE, Lisp Flavoured Erlang, is a lisp syntax front-end to the Erlang
compiler. Code produced with it is compatible with "normal" Erlang
code. An LFE evaluator and shell is also included.


## Building

To compile LFE, simple clone it and compile:

```shell
    $ git clone https://github.com/rvirding/lfe.git
    $ cd lfe
    $ make compile
```

LFE requires Erlang be installed on the system and that the ``erl`` binary is
in ``$PATH``.


## Installation

Should you wish to have LFE available system-wide, you can run
the following ``make`` target:

```shell
    $ make install
```

By default this will create the programs ``lfe``, ``lfec`` and
``lfescript`` in the same directory as the ``erl`` program. This can
changed by defining the make variable ``DESTBINDIR`` to point to the
desired directory. So:

```shell
    $ make install DESTBINDIR=/Users/rv/bin
```

will put the programs in ``/Users/rv/bin``.

Note that the installation target will also install the LFE man pages
in the appropriate ``/usr/local/man/man*`` directories.


## REPL

If you're running LFE from a git clone working dir, you can start the REPL
like so after compiling:

```shell
    $ ./bin/lfe
    Erlang 17 (erts-6.0) [source] [64-bit] [smp:8:8] ...

    LFE Shell V6.0 (abort with ^G)
    >
```

If you have installed LFE, then you may start the REPL from any location:

```shell
    $ lfe
    Erlang 17 (erts-6.0) [source] [64-bit] [smp:8:8] ...

    LFE Shell V6.0 (abort with ^G)
    >
```

Likewise, you may run an LFE shell script in the same style as shell scripts
with:

```shell
    $ ./bin/lfe script-name script-arg-1 ...
```

or

```shell
    $ lfe script-name script-arg-1 ...
```

## Usage

The [docs site](http://lfe.github.io/docs.html) has several places to explore
that will show you how to start using LFE. However, here's a quick taste:

* start up an LFE REPL as demonstrated above
* then, do something like this:
```cl
    > (* 2 (+ 1 2 3 4 5 6))
    42
    > (* 2 (lists:foldl #'+/2 0 (lists:seq 1 6)))
    42
```

## Docker Support

LFE now supports Docker. To get started, simply do the following, once you
have Docker set up on your machine:

```bash
$ docker pull lfex/lfe
```

Alternatively, you could build the image yourself:

```bash
$ cd lfe
$ docker build .
```

Here are a couple of simple usage examples:

```bash
$ docker run lfex/lfe
42

$ docker run -i -t lfex/lfe lfe
Erlang/OTP 18 [erts-7.0] [source-4d83b58] [64-bit] [smp:8:8] ...

LFE Shell V7.0 (abort with ^G)
>
```

That last command will dump you into the LFE REPL on a running container
of the ``lfex/lfe`` Docker image. For more information on using Docker
with LFE, be sure to read the
[tutorial](http://blog.lfe.io/tutorials/2014/12/07/1837-running-lfe-in-docker/).


## Documentation

* [Quick Start](https://lfe.gitbooks.io/quick-start/content/)
* LFE [user guide](doc/user_guide.txt)
* [version history](doc/source/version_history.md)

Files with more technical details:

* [lfescript.txt](doc/lfescript.txt)
* [lfe_shell.txt](doc/lfe_shell.txt)
* [lfe_macro.txt](doc/lfe_macro.txt)
* [lfe_lib.txt](doc/lfe_lib.txt)
* [lfe_io.txt](doc/lfe_io.txt)
* [lfe_gen.txt](doc/lfe_gen.txt)
* [lfe_comp.txt](doc/lfe_comp.txt)
* [lfe_bits.txt](doc/lfe_bits.txt)

If you would like to make changes to the LFE documentation and then regenerate
the docs, you'll want to read the instructions here:

* [Updating LFE Documentation](doc/source/updating_docs.md)