NAME

lfe_guide - Lisp Flavoured Erlang User Guide

SYNOPSIS

Note: {{ ... }} is used to denote optional syntax.

LITERALS AND SPECIAL SYNTACTIC RULES

Supported forms

Patterns

Written as normal data expressions where symbols are variables and use quote to match explicit values. Binaries and tuples have special syntax.

{ok,X}                  -> (tuple 'ok x)
error                   -> 'error
{yes,[X|Xs]}            -> (tuple 'yes (cons x xs))
<<34,U:16,F/float>>     -> (binary 34 (u (size 16)) (f float))
[P|Ps]=All              -> (= (cons p ps) all)
    

Repeated variables are supported in patterns and there is an automatic comparison of values.

_ as the “don’t care” variable is supported. This means that the symbol _, which is a perfectly valid symbol, can never be bound through pattern matching.

Aliases are defined with the (= pattern1 pattern2) pattern. As in Erlang patterns they can be used anywhere in a pattern.

CAVEAT The lint pass of the compiler checks for aliases and if they are possible to match. If not an error is flagged. This is not the best way. Instead there should be a warning and the offending clause removed, but later passes of the compiler can’t handle this yet.

Guards

Wherever a pattern occurs (in let, case, receive, lc, etc.) it can be followed by an optional guard which has the form (when test ...). Guard tests are the same as in vanilla Erlang and can contain the following guard expressions:

(quote e)
(cons gexpr gexpr)
(car gexpr)
(cdr gexpr)
(list gexpr ...)
(tuple gexpr ...)
(tref gexpr gexpr)
(binary ...)
(map ...)
(msiz ...) (map-size ...)
(mref ...) (map-get ...)
(mset ...) (map-set ...)
(mupd ...) (map-update ...)
(record ...)                - Also the macro versions
(is-record ...)
(record-index ...)
(record-field ...)
(is-struct ...)
(struct-field ...)
(type-test e)               - Type tests
(guard-bif ...)             - Guard BIFs, arithmetic,


                              boolean and comparison operators
    

An empty guard, (when), always succeeds as there is no test which fails. This simplifies writing macros which handle guards.

Comments in Function Definitions

Inside functions defined with defun LFE permits optional comment strings in the Common Lisp style after the argument list. So we can have:

(defun max (x y)


  "The max function."


  (if (>= x y) x y))
    

Optional comments are also allowed in match style functions after the function name and before the clauses:

(defun max


  "The max function."


  ((x y) (when (>= x y)) x)


  ((x y) y))
    

This is also possible in a similar style in local functions defined by flet and fletrec:

(defun foo (x y)


  "The max function."


  (flet ((m (a b)


           "Local comment."


           (if (>= a b) a b)))


    (m x y)))
    

Variable Binding and Scoping

Variables are lexically scoped and bound by lambda, match-lambda and let forms. All variables which are bound within these forms shadow variables bound outside but other variables occurring in the bodies of these forms will be imported from the surrounding environments.No variables are exported out of the form. So for example the following function:

(defun foo (x y z)


  (let ((x (zip y)))


    (zap x z))


  (zop x y))
    

The variable y in the call (zip y) comes from the function arguments. However, the x bound in the let will shadow the x from the arguments so in the call (zap x z) the x is bound in the let while the z comes from the function arguments. In the final (zop x y) both x and y come from the function arguments as the let does not export x.

Function Binding and Scoping

Functions are lexically scoped and bound by the top-level defun and by the macros flet and fletrec. LFE is a Lisp-2 so functions and variables have separate namespaces and when searching for function both name and arity are used. This means that when calling a function which has been bound to a variable using (funcall func-var arg ...) is required to call lambda/match-lambda bound to a variable or used as a value.

Unqualified functions shadow as stated above which results in the following order within a module, outermost to innermost:

•

Predefined Erlang BIFs

•

Predefined LFE BIFs

•

Imports

•

Top-level defines

•

Flet/fletrec

•

Core forms, these can never be shadowed

This means that it is perfectly legal to shadow BIFs by imports, BIFs/imports by top-level functions and BIFs/imports/top-level by fletrecs. In this respect there is nothing special about BIFs, they just behave as predefined imported functions, a whopping big (import (from erlang ...)). EXCEPT that we know about guard BIFs and expression BIFs. If you want a private version of spawn then define it, there will be no warnings.

CAVEAT This does not hold for the supported core forms. These can be shadowed by imports or redefined but the compiler will always use the core meaning and never an alternative. The compiler will warn when core forms are redefined but it is not an error.

Module definition

The basic forms for defining a module and extending its metadata and attributes are:

(define-module name meta-data attributes)
(extend-module meta-data attributes)
    

The valid meta data is (type typedef ...), (opaque typedef ...), (spec function-spec ...) and (record record-def ...). Each can take multiple definitions in one meta form.

Attributes declarations have the syntax (attribute value-1 ...) where the attribute value is a list off the values in the declaration

To simplify defining modules there is a predefined macro:

(defmodule name


  "This is the module documentation."


  (export (f 2) (g 1) ... )


  (export all)                          ;Export all functions


  (import (from mod (f1 2) (f2 1) ... )


          (rename mod ((g1 2) m-g1) ((g2 1) m-g2) ... ))


  (module-alias (really-long-module-name rlmn) ...)


  (attr-1 value-1 value-2)


  {meta meta-data ...)


  ... )
    

We can have multiple export and import attributes within module declaration. The (export all) attribute is allowed together with other export attributes and overrides them. Other attributes which are not recognized by the compiler are allowed and are simply passed on to the module and can be accessed with the module_info/0-1 functions.

In the import attribute the (from mod (f1 2) ...) means that the call (f1 'everything 42) will be converted by the compiler to (mod:f1 'everything 42)) while the (rename mod ((g2 2) m-g1) ...) means that the call (m-g1 'everything 42) will be converted to (mod:g1 'everything 42). The rename form can be used as compact way of indicating the imported function’s module. Note that when importing a module

•

the compiler does no checking on that module at all

•

in the rename above the functions g1/2 and g2/1 aren’t automatically imported, only the “renamed” functions.

•

we do not really see in the code that we are calling a function in another module

In the module-alias attribute the (really-long-module-name rlmn) declaration means that the call (lrmn:foo 'everything 42) will be converted by the compiler to (really-long-module-name:foo 'everything 42). This is often used to write short module names in the code when calling functions in modules with long names. It is in many ways better than using import as it does not hide that we are calling a function in another module.

Macros

Macro calls are expanded in both body and patterns. This can be very useful to have both make and match macros, but be careful with names.

A macro is function of two arguments which is a called with a list of the arguments to the macro call and the current macro environment. It can be either a lambda or a match-lambda. The basic forms for defining macros are:

(define-macro name meta-data lambda|match-lambda)
(let-macro ((name lambda|match-lambda)


  ...)
    

Macros are definitely NOT hygienic in any form. However, variable scoping and variable immutability remove most of the things that can cause unhygienic macros. It can be done but you are not going to do it by mistake. The only real issue is if you happen to be using a variable which has the same name as one which the macro generates, that can cause problems. The work around for this is to give variables created in the macro expansion really weird names like | - foo - | which no one in their right mind would use.

To simplify writing macros there are a number of predefined macros:

(defmacro name (arg ...) ...)
(defmacro name arg ...)
(defmacro name ((argpat ...) body) ...)
    

Defmacro can be used for defining simple macros or sequences of matches depending on whether the arguments are a simple list of symbols or can be interpreted as a list of pattern/body pairs. In the second case when the argument is just a symbol it will be bound to the whole argument list. For example:

(defmacro double (a) `(+ ,a ,a))
(defmacro my-list args `(list ,@args))
(defmacro andalso


  ((list e) `,e)


  ((cons e es) `(if ,e (andalso ,@es) 'false))


  (() `'true))
    

The macro definitions in a macrolet obey the same rules as defmacro.

The macro functions created by defmacro and macrolet automatically add the second argument with the current macro environment with the name $ENV. This allows explicit expansion of macros inside the macro and also manipulation of the macro environment. No changes to the environment are exported outside the macro.

User defined macros shadow the predefined macros so it is possible to redefine the built-in macro definitions. However, see the caveat below!

Yes, we have the backquote. It is implemented as a macro so it is expanded at macro expansion time.

Local functions that are only available at compile time and can be called by macros are defined using eval-when-compile:

(defmacro foo (x)


  ...


  (foo-helper m n)


  ...)
(eval-when-compile


  (defun foo-helper (a b)


    ...)


  )
    

There can be many eval-when-compile forms. Functions defined within an eval-when-compile are mutually recursive but they can only call other local functions defined in an earlier eval-when-compile and macros defined earlier in the file. Functions defined in eval-when-compile which are called by macros can defined after the macro but must be defined before the macro is used.

Scheme’s syntax rules are an easy way to define macros where the body is just a simple expansion. The are implemented the the module scm and are supported with scm:define-syntax and scm:let-syntax and the equivalent scm:defsyntax and scm:syntaxlet. Note that the patterns are only the arguments to the macro call and do not contain the macro name. So using them we would get:

(scm:defsyntax andalso


  (() 'true)


  ((e) e)


  ((e . es) (case e ('true (andalso . es)) ('false 'false))))
    

There is an include file “include/scm.lfe” which defines macros so the names don’t have to be prefixed with scm:.

CAVEAT While it is perfectly legal to define a Core form as a macro these will silently be ignored by the compiler.

Comments in Macro Definitions

Inside macros defined with defmacro LFE permits optional comment strings in the Common Lisp style after the argument list. So we can have:

(defmacro double (a)


  "Double macro."


  `(+ ,a ,a))
    

Optional comments are also allowed in match style macros after the macro name and before the clauses:

(defmacro my-list args


  "List of arguments."


  `(list ,@args))
(defmacro andalso


  "The andalso form."


  ((list e) `,e)


  ((cons e es) `(if ,e (andalso ,@es) 'false))


  (() `'true))
    

This is also possible in a similar style in local functions defined by macrolet:

(defun foo (x y)


  "The max function."


  (macrolet ((m (a b)


               "Poor macro definition."


               `(if (>= ,a ,b) ,a ,b)))


    (m x y)))
    

Records

Records are tuples with the record name as first element and the rest of the fields in order exactly like “normal” Erlang records. As with Erlang records the default default value is the atom `undefined'.

The basic forms for defining a record, creating, accessing and updating it are:

(define-record name (field | (field) |


                     (field default-value) |


                     (field default-value type) ...))
(record name field value field value ...)
(is-record record name)
(record-index name field)
(record-field record name field)
(record-update record name field value field value ...)
    

Note that the list of field/value pairs when making or updating a record is a flat list.

Note that the old make-record form has been deprecated and is replaced by record which better matches other constructors like tuple and map. It still exists but should not be used.

We will explain these forms with a simple example. To define a record we do:

(define-record person


               ((name "")


                (address "" (string))


                (age)))
    

which defines a record person with the fields name (default value ""), address (default value "" and type (string)) and age. To make an instance of a person record we do:

(record person name "Robert" age 54)
    

The record form is also used to define a pattern.

We can get the value of the address field in a person record and set it by doing (the variable robert references a person record):

(record-field robert person address)
(record-update robert person address "my home" age 55)
    

Note that we must include the name of the record when accessing it and there is no need to quote the record and field names as these are always literal atoms.

To simplify defining and using records there is a predefined macro:

(defrecord name


  (field) | field


  (field default-value)


  (field default-value type)


  ... )
    

This will create access macros for record creation and accessing and updating fields. The make-, match- and update- forms takes optional argument pairs field-name value to get non-default values. E.g. for

(defrecord person


  (name "")


  (address "" (string))


  (age))
    

the following will be generated:

(make-person {{field value}} ... )
(match-person {{field value}} ... )
(is-person r)
(fields-person)
(update-person r {{field value}} ... )
(person-name r)
(person-name)
(update-person-name r name)
(person-age r)
(person-age)
(update-person-age r age)
(person-address r)
(person-address)
(update-person-address r address)
    

•

(make-person name "Robert" age 54) - Will create a new person record with the name field set to “Robert”, the age field set to 54 and the address field set to the default ““.

•

(match-person name name age 55) - Will match a person with age 55 and bind the variable name to the name field of the record. Can use any variable name here.

•

(is-person john) - Test if john is a person record.

•

(person-address john) - Return the address field of the person record john.

•

(person-address) - Return the index of the address field of a person record.

•

(update-person-address john "back street") - Updates the address field of the person record john to “back street”.

•

(update-person john age 35 address "front street") - In the person record john update the age field to 35 and the address field to “front street”.

•

(fields-person) - Returns a list of fields for the record. This is useful for when using LFE with Mnesia, as the record field names don’t have to be provided manually in the create_table call.

•

(size-person) - Returns the size of the record tuple.

Note that the older now deprecated set- forms are still generated.

Structs

Structs in LFE are the same as Elixir structs and have been defined in the same way so to be truly compatible. This means that you can use structs defined in Elixr from LFE and structs defined in LFE from Elixir.

(define-struct (field | (field) |


                (field default-value) |


                (field default-value type) ...))
(struct name field value field value ...)
(is-struct struct)
(is-struct struct name)
(struct-field struct name field)
(struct-update struct name field value field value ...)
    

We will explain these forms with a simple example. To define a struct we do:

(define-struct ((name "")


                (address "" (string))


                (age)))
    

which defines a struct with the name of the current module with the fields name (default value ""), address (default value "" and type (string)) and age. To make an instance of struct we do:

(struct mod-name name "Robert" age 54)
    

The struct form is also used to define a pattern.

We can get the value of the address field in the struct and set it by doing (the variable robert references a struct):

(struct-field robert mod-name address)
(struct-update robert mod-name address "my home" age 55)
    

Note that a struct automatically gets the name of the module in which it is defined so that there can only be one struct defined in a module. This mirrors how structs are implemented in Elixir.

Note that we must include the name of the struct when accessing it and there is no need to quote the struct and field names as these are always literal atoms.

Binaries/bitstrings

A binary is

(binary seg ... )
    

where seg is

    byte


    string


    (val integer | float | binary | bitstring | bytes | bits |


         utf8 | utf-8 | utf16 | utf-16 | utf32 | utf-32


         (size n) (unit n)


         big-endian | little-endian | native-endian


         big | little | native


         signed | unsigned)
    

val can also be a string in which case the specifiers will be applied to every character in the string. As strings are just lists of integers these are also valid here. In a binary constant all literal forms are allowed on input but they will always be written as bytes.

Maps

A map is created with:

(map key value ... )
    

To access maps there are the following forms:

•

(map-size map) - Return the size of a map.

•

(map-get map key) - Return the value associated with the key in the map.

•

(map-set map key val ... ) - Set the keys in the map to values. This form can be used to update the values of existing keys and to add new keys.

•

(map-update map key val ... ) - Update the keys in the map to values. Note that this form requires all the keys to already exist in the map.

•

(map-remove map key ... ) - Remove the keys in the map.

There are also alternate short forms msiz, mref, mset, mupd and mrem based on the Maclisp array reference forms. They take the same arguments as their longer alternatives.

Core forms

ETS and Mnesia

LFE also supports match specifications and Query List Comprehensions. The syntax for a match specification is the same as for match-lambdas:

(ets-ms


  ((arg ... ) {{(when e ...)}} ...)             - Matches clauses


  ... )
    

For example:

(ets:select db (ets-ms


                 ([(tuple _ a b)] (when (> a 3)) (tuple 'ok b))))
    

It is a macro which creates the match specification structure which is used in ets:select and mnesia:select. For tracing instead of the ets-ms macro there is the trace-ms macro which is also used in conjunction with the dbg module. The same restrictions as to what can be done apply as for vanilla match specifications:

•

There is only a limited number of BIFs which are allowed

•

There are some special functions only for use with dbg

•

For ets/mnesia it takes a single parameter which must a tuple or a variable

•

For dbg it takes a single parameter which must a list or a variable

N.B. the current macro neither knows nor cares whether it is being used in ets/mnesia or in dbg. It is up to the user to get this right.

Macros, especially record macros, can freely be used inside match specs.

CAVEAT Some things which are known not to work in the current version are andalso, orelse and record updates.

Predefined LFE functions

The following more or less standard lisp functions are predefined:

(<arith_op> expr ...)
(<comp_op> expr ...)
    

The standard arithmetic operators, + - * /, and comparison operators, > >= < =< == /= =:= =/= , can take multiple arguments the same as their standard lisp counterparts. This is still experimental and implemented using macros. They do, however, behave like normal functions and evaluate ALL their arguments before doing the arithmetic/comparisons operations.

(acons key value list)
(pairlis keys values {{list}})
(assoc key list)
(assoc-if test list)
(assoc-if-not test list)
(rassoc value list)
(rassoc-if test list)
(rassoc-if-not test list)
    

The standard association list functions.

(subst new old tree)
(subst-if new test tree)
(subst-if-not new test tree)
(sublis alist tree)
    

The standard substitution functions.

(macroexpand-1 expr {{environment}})
    

If Expr is a macro call, does one round of expansion, otherwise returns Expr.

(macroexpand expr {{environment}})
    

Returns the expansion returned by calling macroexpand-1 repeatedly, starting with Expr, until the result is no longer a macro call.

(macroexpand-all expr {{environment}})
    

Returns the expansion from the expression where all macro calls have been expanded with macroexpand.

NOTE that when no explicit environment is given the macroexpand functions then only the default built-in macros will be expanded. Inside macros and in the shell the variable $ENV is bound to the current macro environment.

(eval expr {{environment}})
    

Evaluate the expression expr. Note that only the pre-defined lisp functions, erlang BIFs and exported functions can be called. Also no local variables can be accessed. To access local variables the expr to be evaluated can be wrapped in a let defining these.

For example if the data we wish to evaluate is in the variable expr and it assumes there is a local variable “foo” which it needs to access then we could evaluate it by calling:

(eval `(let ((foo ,foo)) ,expr))
    

Notes

•

NYI - Not Yet Implemented

•

N.B. - Nota bene (note well)

SEE ALSO

lfe(1), lfescript(1), lfe_cl(3)

AUTHORS

Robert Virding.