erl_prettypr(3)

📦

version 29.0.6 · 3 versions

💖 erl_prettypr — Erlang Module Definition (the `erl_prettypr(3)` page, bestie edition) 💖

okay so hi. this is erl_prettypr, and yes it's an Erlang module, and yes it's the one that makes your ugly abstract syntax trees look ✨pretty✨. it's literally called "pretty printing" and honestly? it ate.

🌸 NAME 🌸

erl_prettypr — pretty printing of abstract Erlang syntax trees. that's it, that's the whole job, and she does it flawlessly. 💅

🎀 DESCRIPTION 🎀

so bestie, this module is basically a front end to the pretty-printing library module prettypr, and its whole thing is text formatting of abstract syntax trees — the ones defined by the module erl_syntax. so like, erl_syntax builds the tree, and erl_prettypr dresses it up for the group chat. iconic division of labour, no cap. 🦋

🧚 DATA TYPES 🧚

clause_t() — it's one of these, exactly these:

case_expr | fun_expr | if_expr | maybe_expr | receive_expr |
try_expr |
{function, prettypr:document()} |
spec.

context() — defined as #ctxt{}. the vibes container, essentially.
hook() — defined as:

none | fun((syntaxTree(), _, _) -> prettypr:document()).

syntaxTree() — defined as erl_syntax:syntaxTree(), and like, that's an abstract syntax tree. see the erl_syntax module for details, babe. 🫶

🔥 FUNCTIONS 🔥

best(syntaxTree(), [term()]) -> empty | prettypr:document().

Creates a fixed "best" abstract layout for a syntax tree. 🌟

So this is basically layout/2's sibling, except that here, the final layout has already been selected with respect to the given options. and if no such layout could be produced? you get the atom empty. rip. 💀 for info on the options, go look at the format/2 function.

See also: best/1, format/2, layout/2, prettypr:best/3.

format(syntaxTree(), [term()]) -> string().

Prettyprint-formats an abstract Erlang syntax tree as text. this is the one you'll actually call, fr fr. ✨

for example, if you have a .beam file that has been compiled with debug_info, the following should print the source code for the module (as it looks in the debug info representation):

{ok,{_,[{abstract_code,{_,AC}}]}} =
        beam_lib:chunks("myfile.beam",[abstract_code]),
io:put_chars(erl_prettypr:format(erl_syntax:form_list(AC)))

Available options, and bestie I need you to read all of these, no skimming:

{hook, none | hook()} — unless the value is none, the given function is called for each node whose list of annotations is not empty. the default value is none.
{paper, integer()} — specifies the preferred maximum number of characters on any line, including indentation. the default value is 80.
{ribbon, integer()} — specifies the preferred maximum number of characters on any line, not counting indentation. the default value is 65.
{user, term()} — user-specific data for use in hook functions. the default value is undefined.
{encoding, epp:source_encoding()} — specifies the encoding of the generated file.

so a hook function (see the hook() type) gets passed the current syntax tree node, the context, and a continuation. and you can poke at / rearrange that context with functions like get_ctxt_user/1 and set_ctxt_user/2. the hook must return a "document" data structure (see layout/2 and best/2) — and you can build that thing partly or entirely by applying the continuation function. 🌈

for example, here's a trivial hook:

fun (Node, Ctxt, Cont) -> Cont(Node, Ctxt) end

which yields the same result as if no hook was given at all. basically the "i have nothing to add" hook. 🙈

the following one, however:

fun (Node, Ctxt, Cont) ->
    Doc = Cont(Node, Ctxt),
    prettypr:beside(prettypr:text("<b>"),
                    prettypr:beside(Doc,
                                    prettypr:text("</b>")))
end

will place the text of any annotated node (regardless of the annotation data) between HTML "boldface begin" and "boldface end" tags. slay, honestly. 💅

See also: erl_syntax, best/2, format/1, get_ctxt_user/1, layout/2, set_ctxt_user/2.

get_ctxt_hook(context()) -> hook().

Returns the hook function field of the prettyprinter context. the little peak behind the curtain. 👑