---
name: "epp"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/epp/3erl"
---

# epp(3erl)

An Erlang code preprocessor.

## NAME

epp - An Erlang code preprocessor.

## DESCRIPTION

The Erlang code preprocessor includes functions that are used by the *compile* module to preprocess macros and include files before the parsing takes place.

The Erlang source file *encoding* is selected by a comment in one of the first two lines of the source file. The first string matching the regular expression *coding\\s\*\[:=\]\\s\*(\[-a-zA-Z0-9\])+* selects the encoding. If the matching string is not a valid encoding, it is ignored. The valid encodings are *Latin-1* and *UTF-8*, where the case of the characters can be chosen freely.

*Examples:*

```
%% coding: utf-8
```

```
%% For this file we have chosen encoding = Latin-1
```

```
%% -*- coding: latin-1 -*-
```

## DATA TYPES

```
macros() =
    [atom() | {atom(), term()} | {atom(), term(), redefine}]
```

```
epp_handle() = pid()
```

Handle to the *epp* server.

```
source_encoding() = latin1 | utf8
```

```
warning_info() = {erl_anno:location(), module(), term()}
```

## EXPORTS

```
close(Epp) -> ok
```

Types:

Epp = epp\_handle()\

Closes the preprocessing of a file.

```
default_encoding() -> source_encoding()
```

Returns the default encoding of Erlang source files.

```
encoding_to_string(Encoding) -> string()
```

Types:

Encoding = source\_encoding()\

Returns a string representation of an encoding. The string is recognized by *read\_encoding/1,2*, *read\_encoding\_from\_binary/1,2*, and *set\_encoding/1,2* as a valid encoding.

```
format_error(ErrorDescriptor) -> io_lib:chars()
```

Types:

ErrorDescriptor = term()\

Takes an *ErrorDescriptor* and returns a string that describes the error or warning. This function is usually called implicitly when processing an *ErrorInfo* structure (see section Error Information).

```
open(Options) ->
        {ok, Epp} | {ok, Epp, Extra} | {error, ErrorDescriptor}
```

Types:

Options = \
\
     \[{default\_encoding, DefEncoding :: source\_encoding()} \|\
\
      {includes, IncludePath :: \[DirectoryName :: file:name()\]} \|\
\
      {source\_name, SourceName :: file:name()} \|\
\
      {deterministic, Enabled :: boolean()} \|\
\
      {macros, PredefMacros :: macros()} \|\
\
      {name, FileName :: file:name()} \|\
\
      {location, StartLocation :: erl\_anno:location()} \|\
\
      {fd, FileDescriptor :: file:io\_device()} \|\
\
      extra\]\
 Epp = epp\_handle()\
 Extra = \[{encoding, source\_encoding() \| none}\]\
 ErrorDescriptor = term()\

Opens a file for preprocessing.

If you want to change the file name of the implicit -file() attributes inserted during preprocessing, you can do with *{source\_name, SourceName}*. If unset it will default to the name of the opened file.

Setting *{deterministic, Enabled}* will additionally reduce the file name of the implicit -file() attributes inserted during preprocessing to only the basename of the path.

If *extra* is specified in *Options*, the return value is *{ok, Epp, Extra}* instead of *{ok, Epp}*.

The option *location* is forwarded to the Erlang token scanner, see *erl\_scan:tokens/3,4*.

```
open(FileName, IncludePath) ->
        {ok, Epp} | {error, ErrorDescriptor}
```

Types:

FileName = file:name()\
 IncludePath = \[DirectoryName :: file:name()\]\
 Epp = epp\_handle()\
 ErrorDescriptor = term()\

Equivalent to *epp:open(\[{name, FileName}, {includes, IncludePath}\])*.

```
open(FileName, IncludePath, PredefMacros) ->
        {ok, Epp} | {error, ErrorDescriptor}
```

Types:

FileName = file:name()\
 IncludePath = \[DirectoryName :: file:name()\]\
 PredefMacros = macros()\
 Epp = epp\_handle()\
 ErrorDescriptor = term()\

Equivalent to *epp:open(\[{name, FileName}, {includes, IncludePath}, {macros, PredefMacros}\])*.

```
parse_erl_form(Epp) ->
                  {ok, AbsForm} |
                  {error, ErrorInfo} |
                  {warning, WarningInfo} |
                  {eof, Location}
```

Types:

Epp = epp\_handle()\
 AbsForm = erl\_parse:abstract\_form()\
 Location = erl\_anno:location()\
 ErrorInfo = erl\_scan:error\_info() \| erl\_parse:error\_info()\
 WarningInfo = warning\_info()\

Returns the next Erlang form from the opened Erlang source file. Tuple *{eof, Location}* is returned at the end of the file. The first form corresponds to an implicit attribute *-file(File,1).*, where *File* is the file name.

```
parse_file(FileName, Options) ->
              {ok, [Form]} |
              {ok, [Form], Extra} |
              {error, OpenError}
```

Types:

FileName = file:name()\
 Options = \
\
     \[{includes, IncludePath :: \[DirectoryName :: file:name()\]} \|\
\
      {source\_name, SourceName :: file:name()} \|\
\
      {macros, PredefMacros :: macros()} \|\
\
      {default\_encoding, DefEncoding :: source\_encoding()} \|\
\
      {location, StartLocation :: erl\_anno:location()} \|\
\
      {reserved\_word\_fun, Fun :: fun((atom()) -\> boolean())} \|\
\
      {features, \[Feature :: atom()\]} \|\
\
      extra\]\
 Form = \
\
     erl\_parse:abstract\_form() \|\
\
     {error, ErrorInfo} \|\
\
     {eof, Location}\
 Location = erl\_anno:location()\
 ErrorInfo = erl\_scan:error\_info() \| erl\_parse:error\_info()\
 Extra = \[{encoding, source\_encoding() \| none}\]\
 OpenError = file:posix() \| badarg \| system\_limit\

Preprocesses and parses an Erlang source file. Notice that tuple *{eof, Location}* returned at the end of the file is included as a "form".

If you want to change the file name of the implicit -file() attributes inserted during preprocessing, you can do with *{source\_name, SourceName}*. If unset it will default to the name of the opened file.

If *extra* is specified in *Options*, the return value is *{ok, \[Form\], Extra}* instead of *{ok, \[Form\]}*.

The option *location* is forwarded to the Erlang token scanner, see *erl\_scan:tokens/3,4*.

```
parse_file(FileName, IncludePath, PredefMacros) ->
              {ok, [Form]} | {error, OpenError}
```

Types:

FileName = file:name()\
 IncludePath = \[DirectoryName :: file:name()\]\
 Form = \
\
     erl\_parse:abstract\_form() \|\
\
     {error, ErrorInfo} \|\
\
     {eof, Location}\
 PredefMacros = macros()\
 Location = erl\_anno:location()\
 ErrorInfo = erl\_scan:error\_info() \| erl\_parse:error\_info()\
 OpenError = file:posix() \| badarg \| system\_limit\

Equivalent to *epp:parse\_file(FileName, \[{includes, IncludePath}, {macros, PredefMacros}\])*.

```
read_encoding(FileName) -> source_encoding() | none
```

```
read_encoding(FileName, Options) -> source_encoding() | none
```

Types:

FileName = file:name()\
 Options = \[Option\]\
 Option = {in\_comment\_only, boolean()}\

Read the encoding from a file. Returns the read encoding, or *none* if no valid encoding is found.

Option *in\_comment\_only* is *true* by default, which is correct for Erlang source files. If set to *false*, the encoding string does not necessarily have to occur in a comment.

```
read_encoding_from_binary(Binary) -> source_encoding() | none
```

```
read_encoding_from_binary(Binary, Options) ->
                             source_encoding() | none
```

Types:

Binary = binary()\
 Options = \[Option\]\
 Option = {in\_comment\_only, boolean()}\

Read the encoding from a binary. Returns the read encoding, or *none* if no valid encoding is found.

Option *in\_comment\_only* is *true* by default, which is correct for Erlang source files. If set to *false*, the encoding string does not necessarily have to occur in a comment.

```
scan_erl_form(Epp) ->
                 {ok, Tokens} |
                 {error, ErrorInfo} |
                 {warning, WarningInfo} |
                 {eof, Line}
```

Types:

Epp = epp\_handle()\
 Tokens = erl\_scan:tokens()\
 Line = erl\_anno:line()\
 ErrorInfo = erl\_scan:error\_info() \| erl\_parse:error\_info()\
 WarningInfo = warning\_info()\

Returns the raw tokens of the next Erlang form from the opened Erlang source file. A tuple *{eof, Line}* is returned at the end of the file. The first form corresponds to an implicit attribute *-file(File,1).*, where *File* is the file name.

```
scan_file(FileName, Options) ->
             {ok, [Form], Extra} | {error, OpenError}
```

Types:

FileName = file:name()\
 Options = \
\
     \[{includes, IncludePath :: \[DirectoryName :: file:name()\]} \|\
\
      {source\_name, SourceName :: file:name()} \|\
\
      {macros, PredefMacros :: macros()} \|\
\
      {default\_encoding, DefEncoding :: source\_encoding()}\]\
 Form = erl\_scan:tokens() \| {error, ErrorInfo} \| {eof, Loc}\
 Loc = erl\_anno:location()\
 ErrorInfo = erl\_scan:error\_info()\
 Extra = \[{encoding, source\_encoding() \| none}\]\
 OpenError = file:posix() \| badarg \| system\_limit\

Preprocesses an Erlang source file returning a list of the lists of raw tokens of each form. Notice that the tuple *{eof, Line}* returned at the end of the file is included as a "form", and any failures to scan a form are included in the list as tuples *{error, ErrorInfo}*.

```
set_encoding(File) -> source_encoding() | none
```

Types:

File = io:device()\

Reads the encoding from an I/O device and sets the encoding of the device accordingly. The position of the I/O device referenced by *File* is not affected. If no valid encoding can be read from the I/O device, the encoding of the I/O device is set to the default encoding.

Returns the read encoding, or *none* if no valid encoding is found.

```
set_encoding(File, Default) -> source_encoding() | none
```

Types:

Default = source\_encoding()\
 File = io:device()\

Reads the encoding from an I/O device and sets the encoding of the device accordingly. The position of the I/O device referenced by *File* is not affected. If no valid encoding can be read from the I/O device, the encoding of the I/O device is set to the encoding specified by *Default*.

Returns the read encoding, or *none* if no valid encoding is found.

## ERROR INFORMATION

*ErrorInfo* is the standard *ErrorInfo* structure that is returned from all I/O modules. The format is as follows:

```
{ErrorLine, Module, ErrorDescriptor}
```

A string describing the error is obtained with the following call:

```
Module:format_error(ErrorDescriptor)
```

## SEE ALSO

*[erl\_parse(3erl)](/erl_parse/3erl.md)*