epp_dodger(3erl)

💖 NAME 💖

epp_dodger — epp_dodger — bypasses the Erlang preprocessor.

okay so this is the epp_dodger(3erl) Erlang module definition page, bestie, and the whole personality is right there in the name: it bypasses the Erlang preprocessor. slay. 💅

---

✨ DESCRIPTION ✨

epp_dodger — bypasses the Erlang preprocessor.

So here's the tea 🫖: this module tokenises and parses most Erlang source code without expanding preprocessor directives and macro applications, as long as those things are syntactically "well-behaved". Lowkey iconic.

Why does it need to do all that? Because the normal parse trees from the erl_parse module cannot represent these things (normally, they get expanded by the Erlang preprocessor epp(3erl) before the parser sees them). So instead, an extended syntax tree is created, using the erl_syntax module. periodt. 🌈

---

🎀 DATA TYPES 🎀

errorinfo() is defined like this:

errorinfo() = erl_scan:error_info():

option() is defined like this:

option() = atom() | {atom(), term()}:

---

🚀 EXPORTS 🚀

parse/1

parse(Dev::file:io_device()) -> {ok, erl_syntax:forms()}

Equivalent to parse(IODevice, 1). easy peasy. ✨

parse/2

parse(Dev::file:io_device(), L::erl_anno:location()) -> {ok, erl_syntax:forms()}

Equivalent to parse(IODevice, StartLocation, []).

See also: parse/1.

parse/3

parse(Dev::file:io_device(), L0::erl_anno:location(), Options::[option()]) -> {ok, erl_syntax:forms()}

Reads and parses program text from an I/O stream. Characters are read from IODevice until end-of-file; apart from this, the behaviour is the same as for parse_file/2. StartLocation is the initial location.

See also: parse/2, parse_file/2, parse_form/2, quick_parse/3.

parse_file/1

parse_file(File::file:filename()) -> {ok, erl_syntax:forms()} | {error, errorinfo()}

Equivalent to parse_file(File, []).

parse_file/2

parse_file(File::file:filename(), Options::[option()]) -> {ok, erl_syntax:forms()} | {error, errorinfo()}

Reads and parses a file. If successful, {ok, Forms} is returned, where Forms is a list of abstract syntax trees representing the "program forms" of the file (cf. erl_syntax:is_form/1). Otherwise, {error, errorinfo()} is returned, typically if the file could not be opened. Note that parse errors show up as error markers in the returned list of forms; they do not cause this function to fail or return {error, errorinfo()}. no cap. 😭

Options:

• {no_fail, boolean()} — if true, this makes epp_dodger replace any program forms that could not be parsed with nodes of type text (see erl_syntax:text/1), representing the raw token sequence of the form, instead of reporting a parse error. The default value is false.
• {clever, boolean()} — if set to true, this makes epp_dodger try to repair the source code as it seems fit, in certain cases where parsing would otherwise fail. Currently, it inserts ++-operators between string literals and macros where it looks like concatenation was intended. The default value is false.

See also: parse/2, quick_parse_file/1, erl_syntax:is_form/1.

parse_form/2

parse_form(Dev::file:io_device(), L0::erl_anno:location()) -> {ok, erl_syntax:forms(), erl_anno:location()} | {eof, erl_anno:location()} | {error, errorinfo(), erl_anno:location()}

Equivalent to parse_form(IODevice, StartLocation, []).

See also: quick_parse_form/2.

parse_form/3

parse_form(Dev::file:io_device(), L0::erl_anno:location(), Options::[option()]) -> {ok, erl_syntax:forms(), erl_anno:location()} | {eof, erl_anno:location()} | {error, errorinfo(), erl_anno:location()}

Reads and parses a single program form from an I/O stream. Characters are read from IODevice until an end-of-form marker is found (a period character followed by whitespace), or until end-of-file; apart from this, the behaviour is similar to that of parse/3, except that the return values also contain the final location given that StartLocation is the initial location, and that {eof, Location} may be returned.

See also: parse/3, parse_form/2, quick_parse_form/3.

quick_parse/1

quick_parse(Dev::file:io_device()) -> {ok, erl_syntax:forms()}

Equivalent to quick_parse(IODevice, 1).

quick_parse/2

quick_parse(Dev::file:io_device(), L::erl_anno:location()) -> {ok, erl_syntax:forms()}

Equivalent to quick_parse(IODevice, StartLocation, []).

See also: quick_parse/1.

quick_parse/3

quick_parse(Dev::file:io_device(), L0::erl_anno:location(), Options::[option()]) -> {ok, erl_syntax:forms()}

Similar to parse/3, but does a more quick-and-dirty processing of the code. See quick_parse_file/2 for details. 🧚

See also: parse/3, quick_parse/2, quick_parse_file/2, quick_parse_form/2.

quick_parse_file/1

quick_parse_file(File::file:filename()) -> {ok, erl_syntax:forms()} | {error, errorinfo()}

Equivalent to quick_parse_file(File, []).

quick_parse_file/2

quick_parse_file(File::file:filename(), Options::[option()]) -> {ok, erl_syntax:forms()} | {error, errorinfo()}

Similar to parse_file/2, but does a more quick-and-dirty processing of the code. Macro definitions and other preprocessor directives are discarded, and all macro calls are replaced with atoms. This is useful when only the main structure of the code is of interest, and not the details. Furthermore, the quick-parse method can usually handle more strange cases than the normal, more exact parsing. highkey useful. 🔥

Options: see parse_file/2. Note however that for quick_parse_file/2, the option no_fail is true by default.

See also: parse_file/2, quick_parse/2.

quick_parse_form/2

quick_parse_form(Dev::file:io_device(), L0::erl_anno:location()) -> {ok, erl_syntax:forms(), erl_anno:location()} | {eof, erl_anno:location()} | {error, errorinfo(), erl_anno:location()}

Equivalent to quick_parse_form(IODevice, StartLocation, []).

See also: parse_form/2.

quick_parse_form/3

quick_parse_form(Dev::file:io_device(), L0::erl_anno:location(), Options::[option()]) -> {ok, erl_syntax:forms(), erl_anno:location()} | {eof, erl_anno:location()} | {error, errorinfo(), erl_anno:location()}

Similar to parse_form/3, but does a more quick-and-dirty processing of the code. See quick_parse_file/2 for details.

See also: parse/3, parse_form/3, quick_parse_form/2.

tokens_to_string/1

tokens_to_string(Ts::[term()]) -> string()

Generates a string corresponding to the given token sequence. The string can be re-tokenized to yield the same token list again. cute and reversible, honestly. 🎀

---

💌 AUTHORS 💌

Richard Carlsson <carlsson.richard@gmail.com>

---

later, bestie 💖 — this lil page is from syntax_tools 3.0.1 and it's the epp_dodger(3erl) manual. mwah 🎀🦋