lfe_comp(3)

💅 lfe_comp(3) — the LFE compiler, bestie edition

okay so this is the man page for lfe_comp, aka the Lisp Flavoured Erlang (LFE) compiler module, and honestly? it's kind of the main character of the whole LFE toolchain. 🎀

---

✨ NAME ✨

lfe_comp — Lisp Flavoured Erlang (LFE) compiler. that's it, that's the vibe. 💖

---

🌸 SYNOPSIS 🌸

bestie. listen. this module gives you an interface to the standard LFE compiler, and the compiler is lowkey iconic because it can handle files which contain multiple modules. multiple!! it can either generate new files that hold the object code, or return binaries which you can load directly. slay. ✨

---

🦋 EXPORTS 🦋

file(FileName) -> CompRet

literally just the same as file(FileName, [report]). no cap.

file(FileName, Options) -> CompRet

where:

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}

this compiles an LFE file, either writing the generated modules out to files or returning them as binaries. and like, the generated modules are already ready to be loaded into Erlang. iconic behaviour. 👑

the currently recognised options are (every single one, i'm not skipping anything):

• binary — return the binary of the module and do not save it in a file. it's giving "no physical form, just vibes". 🫶
• no_docs, no-docs — do not parse docstrings, and don't write the "LDoc" chunk in the binary of the module.
• to_expand, to-expand — print a listing of the macro expanded LFE code in the file .expand. no object file is produced. mainly useful for debugging and interest.
• to_lint, to-lint — 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.
• to_erlang, to-erlang — print a listing of the Erlang AST in the file .erl. no object files are produced. mainly useful for debugging and interest.
• to_core0, to-core0, to_core, to-core — 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.
• to_kernel, to-kernel — print a listing of the Kernel Erlang code in the files .kernel. no object files are produced. mainly useful for debugging and interest.
• to_asm, to-asm — print a listing of the Beam code in the files .S. no object files are produced. mainly useful for debugging and interest.
• {outdir,Dir}, [outdir,Dir] — save the generated files in directory Dir instead of the current directory. moving out, but make it compiler output. 📁
• {i,Dir}, [i,Dir] — add Dir to the list of directories to be searched when including a file.
• report — print the errors and warnings as they occur. very "keep me posted" of it.
• return — return an extra return field containing Warnings on success, or the errors and warnings in {error,Errors,Warnings} when there are errors.
• debug_print, debug-print — causes the compiler to print a lot of debug information. a LOT. it's giving yapper. 💀
• warnings_as_errors, warnings-as-errors — causes warnings to be treated as errors. harsh but fair.
• no_export_macros, no-export-macros — do not export macros from modules.

heads up bestie: if the binary option is given, then options that produce listing files will cause the internal formats for that compiler pass to be returned. so like, different delivery, same tea. 🍵

both Warnings and Errors have the following format:

[{FileName,[ErrorInfo]}]

ErrorInfo is described below (keep scrolling, it's right there 👇). 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. and as yet — fr fr — there is no extra information about included files. 😭

forms(Forms) -> CompRet

same as forms(Forms, [report]). obviously. 💅

forms(Forms, Options) -> CompRet

where:

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}

this compiles the Forms as an LFE module and returns a binary. it takes the same options as lfe_comp:file/1/2. and when generating Errors and Warnings, the “line number” is the index of the form in which the error occurred. different numbering, same drama. ✨

format_error(Error) -> Chars

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

---

🔥 ERROR INFORMATION 🔥

the ErrorInfo mentioned above is the standard ErrorInfo structure that gets returned from all IO modules. it looks like this:

{ErrorLine,Module,ErrorDescriptor}

and you get a string describing the error with the following call:

Module:format_error(ErrorDescriptor)

that's the whole thing. short, sweet, iconic. 💜

---

🌈 SEE ALSO 🌈

• lfe_gen(3)
• lfe_macro(3)

go read those too, iykyk. 👑

---

⭐ AUTHORS ⭐

Robert Virding.

---

okay that's the whole page, bestie 🎀 this one's from the 2008-2016 era, source/version lfe_comp(3) — like a little vintage handbag but make it compiler docs. mwah 💋