lfe / docs

Documentation site for LFE

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:

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

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

Running the Tests

To run the full suite of tests for LFE, simply use the following:

make tests

Installation

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

$ make install

By default this will create the programs lfe, lfec, lfedoc and lfescript in /usr/local/bin. This can be changed by defining the make variable PREFIX to point to the desired parent directory.

Note that the install target will also install the LFE man pages in the appropriate $(PREFIX)/share/man/man* directories. This can be changed by defining the make variable MANINSTDIR to point to the desired top man directory.

So:

$ make install PREFIX=/Users/rv/ MANINSTDIR=/Users/rv/man

will put the programs in /Users/rv/bin and the man pages in the /Users/rv/man/man* directories.

REPL

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

$ ./bin/lfe

Erlang/OTP 26 [erts-14.0.2] [source] [64-bit] [smp:10:10] [ds:10:10:10] [async-threads:1] [jit] [dtrace]

   ..-~.~_~---..
  (      \\     )    |   A Lisp-2+ on the Erlang VM
  |`-.._/_\\_.-':    |   Type (help) for usage info.
  |         g |_ \   |
  |        n    | |  |   Docs: http://docs.lfe.io/
  |       a    / /   |   Source: http://github.com/lfe/lfe
   \     l    |_/    |
    \   r     /      |   LFE v2.1.4 (abort with ^G)
     `-E___.-'

lfe>

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

$ lfe

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

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

or

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

Usage

The docs site 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:

lfe> (* 2 (+ 1 2 3 4 5 6))
42
lfe> (* 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:

$ docker pull lfex/lfe

Alternatively, you could build the image yourself:

$ cd lfe
$ docker build .

To bring up the LFE REPL:

$ docker run -it lfex/lfe

Documentation

• Quick Start
• LFE user guide
• version history

Files with more technical details:

• lfe.txt
• lfescript.txt
• lfe_bits.txt
• lfe_clj.txt
• lfe_comp.txt
• lfe_docs.txt
• lfe_gen.txt
• lfe_io.txt
• lfe_lib.txt
• lfe_macro.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

Join the Community

LFE on Slack, join by requesting an invite here

LFE Forum - Erlang Forums

Maintainers

Cutting Releases

Steps:

1. Update the version in src/lfe.app.src
2. Create the release tags
3. Create a release on Github
4. Publish to hex.pm

Once the app.src has been updated with the version for the release, you can create and push the tags (to Github) with the following:

make tags

That will create the number-only version as well as the "v"-prefixed version.

For now, the process of creating a release on Github is manual:

1. Go to https://github.com/lfe/lfe/releases
2. Click "Draft new release"
3. Select the correct tag from the drop-down "Choose a tag"
4. Click "Generate release notes"
5. Click "Publish release"

Lastly, to publish LFE to hex.pm, you need to have rebar3 installed on our system and an entry for the hex plugin in your system rebar.config file. With that in place, publish a new release to hex.pm requires only the following:

make hex-publish

docs's Issues

Identify good examples of API documentation

In the same vein as issue #36 (but with a less immediate need), we should build a list of top-notch programming language, framework, and library docs:

• what makes them good?
• how might a given approach be adopted to LFE?
  • how about third-party, community LFE libraries?

Some examples that come to mind:

• Python: nothing fancy, but rock-solid for nigh two decades
• OpenStack: Anne Gentle has done an amazing job with this massive, massive project
• Some bits of the Django docs, since I'm a firm believer in showing code in the docs (though this does introduce a phenomenal maintenance burden, unless you get clever with your docs infrastructure...)
• I've heard good things about MSDN, but maybe I need more familiarity with it before I see its greatness
• I hated Amazon's AWS API docs initially, but have grown quite fond of them over the years (and with improvements)

Please share your favourites!

Part of the Planning Epic.

Add a section for all data types

This section should go in the introductory chapter, right after the section on loading files. (The listing of functions should come after this, and then the "setting up a dev env" section.)

Show how to get characters from strings, etc., as well.

Add note about (processes) in the Processes Tutorial

Also, add a note about (: c i)

Copy Dorai's Math LFE Tutorial to Site

Dorai gave permission to copy this excellent tutorial:

• http://www.ccs.neu.edu/home/dorai/lfe-lessons/index.html#node_toc_start

New page URL:

• http://www.ccs.neu.edu/home/dorai/lfe-lessons/index.html

This will make a nice addition to the site!

Add more to processes tutorial

1. processes on multi-core apps

2. distributed processes

Provide a Riak client tutorial in LFE

https://github.com/basho/riak-erlang-client

Provide an LFE tutorial for creating domain specific languages

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

Create a docs style guide

This can just start with a sample of all the different things that are styled:

• terminal code
• terminal code with emphasis
• source code
• code in a paragraph
• tables
• alert boxes
• warning boxes
• numbered steps/instructions
• various LFE logos (small grey, small black, small color, large color, etc.)

It would just be a single page showcasing these things (and more), as a reminder to docs maintainers regarding the available styles and the prescribed way to do things.

Part of epic #96

Update "Contributing" Section with New Dev On-Boarding

There was a recent email to the list that went into this; it should be documented:
https://groups.google.com/d/msg/lisp-flavoured-erlang/f1mF360pUC4/EOjokdzUDmQJ

Part of epic #98

Devise a mechanism for versioning docs

Part of the Versioning Docs Epic

Add content for creating service/server projects in LFE

Add cons example in pattern matching section

Moved to: cnbbooks/lfe-manual#30

This page: http://docs.lfe.io/user-guide/diving/5.html

Re-style new docs2 site

The copy of the github developer docs site running on docs2.lfe.io is a mess right now, with only partial styling applied. We need to get this fixed up before eyes start bleeding ...

Backquote macro in LFE

This is from an email that Robert sent, and it's a great idea:

I was looking through some of the examples you refer to in the LFE page when I remembered that LFEs backquote macro even works with tuples . So you can use a tuple "pattern" which expands into code to build a tuple. For example:

`#(ok ,reply) ==> (tuple 'ok reply))

With that you could write the callbacks to the ping_pong server as:

(defun init (args)
  `#(ok ,(make-state pings 0)))

(defun handle_call (req from state)
  (let* ((new-count (+ (state-pings state) 1))
         (new-state (set-state-pings state new-count)))
    `#(reply #(pong ,new-count) ,new-state)))

It of course also works in patterns. This is clearer and more concise for those who know about it but I don't think that this is something to drop on the poor unsuspecting reader from the beginning, but a section on the backquote macro would be good to have somewhere.

Style Guide: Add Content to 6 Testing

Part of feature #100

IA and Structure

Tasks:

• Identify core site areas to highlight on simplified landing page
• Decide upon top-nav menu items
• Decide upon bottom-nav menu items
• Identify major documentation categories
• For each major category, identify subcategories
• Identify which categories have content that should be versioned

Our information architecture is basically non-existent. We need to create one.

Part of Milestone v3 #62

Missing list formatting in Processes Tutorial part 4

Tutorial: Lightweight Processes: 4 Process Communications

To demonstrate this, let's update our print-result function to do this: * pattern match for a process id as well as a message * write message about sending data to another process * actually send that data to the other process

Create a translation page for LFE

There are two interesting examples of this, one of which has a very nice visual presentation:

• http://hyperpolyglot.org/lisp
• https://kanaka.github.io/clojurescript/web/synonym.html

Suggested by Aleksandar Radulovic.

Add tutorial for rebar3 plugins

Moved here: cnbbooks/lfe-rebar3-command-reference#10

Creating and using them.

Part of epic #75

Java Interop: Add Content for JInterface Section

Gitbook Idea: "Errors in LFE, and What they Mean"

Have two sections for the book:

• Operations, and the errors you get with them, and
• An alphabetical list of errors and where they show up (maybe more of an index ...)

Link the "Classic docs" directly to the files in Robert's repo

Create some versioned docs using docs2

To figure out of the Github Documentation example site will work for LFE's versioned docs, a couple of example uses are needed. This will help determine if the Github approach will suit our needs. If so, this will allow us to close issue #38 :-)

To accomplish this:

• use the LFE user_guide.txt for the v0.6, v0.8, v0.9, and v0.9.1 releases
• identify the workflow necessary to create a versioned part of the site
• use that to create 4 versioned "areas", one for each of the above
• identify weak spots, difficulties, etc.

Create a basic tutorial for LFE

Based on some recent feedback in Twitter, @rvirding and I are brainstorming about ways in which we can address this lack (both short-term, as well as a more thorough long-term solution). Being a very small open source project with few resources, we have to be very practically minded about this :-) Also, we want to get something out to people as soon as possible, without agonizing over it for a year or two ... so the intended audience would probably be intermediate programmer with minimal experience with Erlang and/or Lisp.

More thoughts on this:

• this tutorial should mirror a good Erlang tutorial
• it wouldn't be a comprehensive/detailed tutorial (or workshop?) on LFE
• rather, it would assume a level of certain knowledge with both Lisps and Erlang itself.

We've created a separate ticket for a comprehensive tutorial (a "phase 2" of the basic tutorial developed in this ticket).

Part of epic #75

Split out LFE function docs

Right now, there's a listing of functions here:

• http://lfe.github.io/user-guide/funcode/2.html

This should be moved to the introductory section, right after the page on data types in LFE.. In its place should be several pages of functions -- description and usage examples for each. What are sections on that page right now should become separate pages.

Identify good examples of User Guide/Programming book organization

As we begin to iterate on the LFE docs, we need to think about the content we want to present to various types of end user, how that content should be organized, what content is missing from existing docs that would be nice to add, and what content we should remove or rework.

@bigos shared the following link:

• https://en.wikibooks.org/wiki/Haskell

And this is a great example of organizing content by experience level. It's not a very common approach, but I like it -- especially for an online resource.

We should also map out the topics covered in:

• Learn You Some Erlang
• Programming Erlang
• Erlang Programming
• Designing for Scalability with Erlang/OTP

Then, after compiling that list, we could divide the topics up across one or more levels of experience, as the Haskel wiki book has done...

At any rate, if you have a favorite programming book, please provide a link in the comments and why you liked it, and if you have the time, why you think LFE would benefit from something like that.

Thanks!

Part of the Planning Epic.

Interop: Java + Elixir

Convert Java Interop section to just "Interop" -- include Elixir and Joxa interop examples?

Add style guide links in "Contributing" page

Discuss $ENV somewhere in the docs

Need to find a good location for mentioning $ENV and demonstrating how to use it. Possibly in a section on debugging?

Add record matching in function heads in pattern matching section

Moved to: cnbbooks/lfe-manual#29

This page:

• http://docs.lfe.io/user-guide/diving/5.html

Example Erlang code:

handle_info(ping, #state {remote_pid = undefined} = State) ->
    gen_server:cast(self(), ping),
    {noreply, State};

handle_info(ping, State) ->
    {noreply, State};

handle_info({pong, Pid}, #state {remote_pid = undefined,
                                 waiters = Waiters} = State) ->
    ?INFO("connection to java node established, pid ~p", [Pid]),
    link(Pid),
    lists:foreach(fun(Waiter) ->
                          gen_server:cast(self(), {wait_for_login, Waiter})
                  end, Waiters),
    {noreply, State#state {waiters = [],
                           remote_pid = Pid}};

handle_info({pong, _}, State) ->
    {noreply, State};

handle_info({Port, {exit_status, Status}}, #state {ext_port_ref = Port} = State) ->
    ?ERROR("external java app exited with status ~p", [Status]),
    {stop, {error, {java_app_exit, Status}}, State};

handle_info({'EXIT', Pid, Reason}, #state {remote_pid = Pid} = State) ->
    ?ERROR("external java mbox exited with reason ~p", [Reason]),
    {stop, {error, {java_mbox_exit, Reason}}, State};

handle_info(_Info, State) ->
    ?ERROR("unhandled info, ~p", [_Info]),
    {noreply, State}.

Corresponding LFE code:

(defun handle_info
  (('ping (= (match-state remote-pid 'undefined) state))
    `#(noreply ,state))
  (('ping state)
   `#(noreply ,state))
  (((tuple 'pong pid) (= (match-state remote-pid 'undefined
                                      waiters waiters)
                         state))
   (INFO "Connection to java node established, pid: '~p'" (list pid))
   (link pid)
   (lists:foreach
     (lambda (x)
       (gen_server:cast (self) `#(wait-for-login x)))
     waiters)
   `#(noreply ,(make-state remote-pid pid
                           waiters waiters
                           ext-port-ref (state-ext-port-ref))))
  (((tuple 'pong _) state)
   `#(noreply ,state))
  (((tuple port (tuple 'exit-status status)) (= (match-state ext-port-ref ext-port)
                                                state)) (when (== port ext-port))
   (ERROR "External java app exited with status: '~p'" (list status))
   `#(stop #(error #(java-app-exit ,status)) ,state))
  (((tuple 'EXIT pid reason) (= (match-state remote-pid remote-pid)
                                state)) (when (== pid remote-pid))
   (ERROR "External java mbox exited with reason: '~p'" (list reason))
   `#(stop #(error #(java-mbox-exit ,reason)) ,state))
  ((info state)
   (ERROR "Unhandled info: '~p'" (list info))
   `#(noreply ,state)))

Add lfetool Book

Create a new site book (like the User Guide, the Cookbook, etc.) that does a thorough job explaining how to use (and maximize the use of) lfetool in developing LFE projects of all types.

Come up with a re-direct plan for existing docs

If we go with a whole new layout (versioned docs, etc.) for the new LFE docs site, we're going to need to put some redirections in place ...

Create an ETS tutorial

Moved to: cnbbooks/catalog#14

Be sure to include a section about working with a table across processes:

"The table identifier can be sent to other processes so that a table can be shared between different processes within a node."

(from http://www.erlang.org/doc/man/ets.html)

Add "History" section to main docs page

We should have history links for Lisp, Erlang, and LFE. The "LFE" page on http://lfe.io/ has two of the best sources for Lisp; this should be added to a "History" section on the docs main page.

Add the following for Erlang:

• http://webcem01.cem.itesm.mx:8005/erlang/cd/downloads/hopl_erlang.pdf
• http://www.cs.tut.fi/~popl/essays/erlang.pdf
• https://www.erlang-factory.com/upload/presentations/416/MikeWilliams.pdf
• http://www.infoq.com/interviews/williams-erlang
• https://www.youtube.com/watch?v=HCwRGHj5jOE

Style Guide: Add Content to 12 Pitfalls

Part of feature #100

Create a comprehensive LFE tutorial

Moved to: cnbbooks/catalog#14

Following up on the "Basic Tutorial" in issue #40, this ticket aims to take it to the next level with the following:

• providing an introduction to Lisps in general for folks that have no background there
• providing a gentler introduction to Erlang than that provided in the basic tutorial
• identifying holes or "weak spots" in the Basic Tutorial where new-comers have struggled, encountered ambiguities or difficulties, etc.
• examining good tutorials from other languages
• putting all of this together for a v2 of the tutorial

Part of epic #75

Contribute an LFE page to "Learn X in Y Minutes"

Examples

• Erlang: http://learnxinyminutes.com/docs/erlang/
• Common Lisp: http://learnxinyminutes.com/docs/common-lisp/
• Clojure: http://learnxinyminutes.com/docs/clojure/
• Clojure Macros: http://learnxinyminutes.com/docs/clojure-macros/
• Racket: http://learnxinyminutes.com/docs/racket/

Process

• Fork this: https://github.com/adambard/learnxinyminutes-docs
• Write
• Submit a PR

Suggested by Aleksandar Radulovic.

Part of epic #75

Add Cheatsheet

Best cheatsheet I've seen for a language so far:
http://jafingerhut.github.io/
Do one like that for LFE.

Part of epic #75

Create LFE web app(s) tutorial

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

Add more resources in the "Erlang" section

Update list comprehension sections to use new aliases

Add OTP Server Tutorial

Create an LFE relational database tutorial

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

Re-order the doc sections

Most pertinent stuff for LFE devs should be first.

Add Cookbook

Moved here: cnbbooks/catalog#2

This would be a whole new segment of the site, not just another section.

Part of epic #75

Java Interop: Finish Erjang Content

Add explanatory note at the top of the docs page

We've received some feed back on Twitter about the lack of a good LFE tutorial; that's got a new ticket (issue #40).

While that work is in progress, we need to do some "preventative medicine" by clearly setting expectations (a little of this was done in the README for Casting SPELs in LFE; we need a shorter version of that for our current docs).

So, at the top of the docs site, we need to do the following:

• Convert the section "Erlang Resources" to "Learning LFE"
• Add explanatory text saying that, until we have more and better beginners' materials, one needs to learn a bit of Lisp and some Erlang before tackling LFE
• Provide resources for both, with links
• Provide a note on "what's next", i.e., once that task has been accomplished, what the reader can do next

Both Quick Starts should have their introductions updated along these lines as well.

Style Guide: Add Content to 8.2 EVAL-WHEN-COMPILE

Part of feature #100

Style Guide: Add Content to 7.3 Objects and State

Part of feature #100

Create an LFE Cheat Sheet

Similar to the rightly-famous Clojure cheat sheet:

• https://jafingerhut.github.io/