MODULE

        lfe_comp

MODULE SUMMARY

        Lisp Flavoured Erlang (LFE) compiler

DESCRIPTION

        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.

EXPORTS

file(FileName) -> CompRet

        Is the same as file(FileName, [report]).

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}

        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.

        The currently recognised options are:

        binary
                Return the binary of the module and do not save it in
                a file.

        to_exp
                Print a listing of the macro expanded LFE code in the
                file <File>.expand. No object file is produced. Mainly
                useful for debugging and interest.

        to_lint
                Print a listing of the macro expanded and linted LFE
                code in the files <Module>.lint. No object files are
                produced. Mainly useful for debugging and interest.

        to_core0
        to_core
                Print a listing of the Core Erlang code before/after
                being optimised in the files <Module>.core. No object
                files are produced. Mainly useful for debugging and
                interest.

        to_kernel
                Print a listing of the Kernel Erlang code in the files
                <Module>.kernel. No object files are produced. Mainly
                useful for debugging and interest.

        to_asm
                Print a listing of the Beam code in the files
                <Module>.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.

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

        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
                Causes the compiler to print a lot of debug
                information.

        warnings_as_errors
                Causes warnings to be treated as errors.

        If the binary option is given then options that produce
        listing files will cause the internal formats for that
        compiler pass to be returned.

        Both Warnings and Errors have the following format:

        [{FileName,[ErrorInfo]}]

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

forms(Forms) -> CompRet

        Is the same as forms(Forms, [report]).

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}

        Compile the forms as an LFE module returning a binary. This
        function takes the same options as lfe_comp:file/1/2. When
        generating Errors and Warnings the "line number" is the index
        of the form in which the error occured.

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 which is returned from all IO modules. It has the
        following format:

        {ErrorLine,Module,ErrorDescriptor}
    
        A string describing the error is obtained with the following call:

        Module:format_error(ErrorDescriptor)
