lfe

.\" Automatically generated by Pandoc 2.11.2
.\"
.TH "lfe_comp" "3" "2008-2016" "" ""
.hy
.SH NAME
.PP
lfe_comp - Lisp Flavoured Erlang (LFE) compiler
.SH SYNOPSIS
.PP
This module provides an interface to the standard LFE compiler.
The compiler can handle files which contain multiple modules.
It can generate either new files which contain the object code, or
return binaries which can be loaded directly.
.SH EXPORTS
.PP
\f[B]file(FileName) -> CompRet\f[R]
.PP
Is the same as \f[C]file(FileName, [report]).\f[R]
.PP
\f[B]file(FileName, Options) -> CompRet\f[R]
.PP
where
.IP
.nf
\f[C]
CompRet = ModRet | BinRet | ErrRet
ModRet = {ok,[ModOk]} | {ok,[ModOk],Warnings}
ModOk  = {ok,ModuleName} | {ok,ModuleName,Warnings}
BinRet = {ok,[ModBin]} | {ok,[ModBin],Warnings}
ModBin = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}
ErrRet = error | {error,[ModErr],Errors,Warnings}
ModErr = {error,Errors,Warnings}
\f[R]
.fi
.PP
Compile an LFE file, either writing the generated modules to files or
returning them as binaries.
The generated modules are ready to be loaded into Erlang.
.PP
The currently recognised options are:
.IP \[bu] 2
\f[C]binary\f[R] - Return the binary of the module and do not save it in
a file.
.IP \[bu] 2
\f[C]no_docs\f[R], \f[C]no-docs\f[R] - Do not parse docstrings and write
the \f[C]\[dq]LDoc\[dq]\f[R] chunk in the binary of the module.
.IP \[bu] 2
\f[C]to_expand\f[R], \f[C]to-expand\f[R] - Print a listing of the macro
expanded LFE code in the file .expand.
No object file is produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]to_lint\f[R], \f[C]to-lint\f[R] - Print a listing of the macro
expanded and linted LFE code in the files .lint.
No object files are produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]to_erlang\f[R], \f[C]to-erlang\f[R] - Print a listing of the Erlang
AST in the file .erl.
No object files are produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]to_core0\f[R], \f[C]to-core0\f[R], \f[C]to_core\f[R],
\f[C]to-core\f[R] - Print a listing of the Core Erlang code before/after
being optimised in the files .core.
No object files are produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]to_kernel\f[R], \f[C]to-kernel\f[R] - Print a listing of the Kernel
Erlang code in the files .kernel.
No object files are produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]to_asm\f[R], \f[C]to-asm\f[R] - Print a listing of the Beam code in
the files .S.
No object files are produced.
Mainly useful for debugging and interest.
.IP \[bu] 2
\f[C]{outdir,Dir}\f[R], \f[C][outdir,Dir]\f[R] - Save the generated
files in director Dir instead of the current directory.
.IP \[bu] 2
\f[C]{i,Dir}\f[R], \f[C][i,Dir]\f[R] - Add dir to the list of
directories to be searched when including a file.
.IP \[bu] 2
\f[C]report\f[R] - Print the errors and warnings as they occur.
.IP \[bu] 2
\f[C]return\f[R] - Return an extra return field containing Warnings on
success or the errors and warnings in \f[C]{error,Errors,Warnings}\f[R]
when there are errors.
.IP \[bu] 2
\f[C]debug_print\f[R], \f[C]debug-print\f[R] - Causes the compiler to
print a lot of debug information.
.IP \[bu] 2
\f[C]warnings_as_errors\f[R], \f[C]warnings-as-errors\f[R] - Causes
warnings to be treated as errors.
.IP \[bu] 2
\f[C]no_export_macros\f[R], \f[C]no-export-macros\f[R] - Do not export
macros from modules.
.PP
If the binary option is given then options that produce listing files
will cause the internal formats for that compiler pass to be returned.
.PP
Both \f[C]Warnings\f[R] and \f[C]Errors\f[R] have the following format:
.IP
.nf
\f[C]
[{FileName,[ErrorInfo]}]
\f[R]
.fi
.PP
\f[C]ErrorInfo\f[R] is described below.
When generating Errors and Warnings the line number is the line of the
start of the form in which the error occurred.
The file name has been included here to be compatible with the Erlang
compiler.
As yet there is no extra information about included files.
.PP
\f[B]forms(Forms) -> CompRet\f[R]
.PP
Is the same as forms(Forms, [report]).
.PP
\f[B]forms(Forms, Options) -> CompRet\f[R]
.PP
where
.IP
.nf
\f[C]
Forms = [sexpr()]
CompRet = BinRet | ErrRet
BinRet = {ok,[ModBin]} | {ok,[ModBin],Warnings}
ModBin = {ok,ModuleName,Binary} | {ok,ModuleName,Binary,Warnings}
ErrRet = error | {error,[ModErr],Errors,Warnings}
ModErr = {error,Errors,Warnings}
\f[R]
.fi
.PP
Compile the forms as an LFE module returning a binary.
This function takes the same options as \f[C]lfe_comp:file/1/2\f[R].
When generating Errors and Warnings the \[lq]line number\[rq] is the
index of the form in which the error occurred.
.PP
\f[B]format_error(Error) -> Chars\f[R]
.PP
Uses an ErrorDescriptor and returns a deep list of characters which
describes the error.
This function is usually called implicitly when an ErrorInfo structure
is processed.
See below.
.SH ERROR INFORMATION
.PP
The \f[C]ErrorInfo\f[R] mentioned above is the standard
\f[C]ErrorInfo\f[R] structure which is returned from all IO modules.
It has the following format:
.PP
\f[B]{ErrorLine,Module,ErrorDescriptor}\f[R]
.PP
A string describing the error is obtained with the following call:
.IP
.nf
\f[C]
Module:format_error(ErrorDescriptor)
\f[R]
.fi
.SH SEE ALSO
.PP
\f[B]lfe_gen(3)\f[R], \f[B]lfe_macro(3)\f[R]
.SH AUTHORS
Robert Virding.