Add support for OTP 27

[elbrujohalcon]

We need to check what changed in erl_syntax and epp_dodger, as usual, but we also need to add support for documentation attributes, sigils and triple-quoted-strings. Plus, maybe is enabled by default.

For reference: https://erlang.org/download/OTP-27.0-rc1.README

[elbrujohalcon]

We can also check if it's worth adding something to support the new shell formatting functionality offered by OTP27:

Tip

• Added support for adding a custom code formatter that formats your multi-line shell commands in your preferred formatting on submission. See shell:format_shell_func/ and shell:erl_pp_format_func/1.

Own Id: OTP-18848
Related Id(s): PR-7847

[elbrujohalcon]

Note

• The epp_dodger module can now handle the maybe and else keywords.

Own Id: OTP-18608
Related Id(s): GH-7266, PR-7267

[paulo-ferraz-oliveira]

I think OTP 27 (25?) breaks format for -else. in macros, probably because else is also part of maybe (?)

[elbrujohalcon]

Repeating this comment here, for visibility:

My original goal was to move us all the way to OTP27… But… OTP tools are terrible for parsing OTP27-compatible code.

Look a this module…

-module(otp27).
-moduledoc """
    New stuff introduced in OTP27.
""".

-export([single_line/0, attributes/0, external/0, markdown/0, false/0, sigils/0]).

-doc "Documentation in one line".
single_line() -> ok.

-doc "You can use".
-doc #{attributes => #{as => maps}}.
attributes() -> {as, maps}.

-doc {file, "external.md"}.
external() -> {in, a, file}.

-doc """
Can contain markdown...
# Title
## Subtitle
### Level 3
**bold**, _italic_
""".
markdown() -> ok.

-doc false.
false() -> false.

sigils() ->
    {
        ~"This is valid now",
        ~B[<<"This, too">>],
        ~b"This one, as well",
        ~"""
        This is a multi-line
                string that can have a quotation mark: "
        as the one in the previous row
        """,
        ~s|Confusingly enough, this is also a string|,
        'not a string,'
    }.

This is how epp_dodger + erl_prettypr would format it:

-module(otp27).

-moduledoc("    New stuff introduced in OTP27.").

-export([single_line/0,
         attributes/0,
         external/0,
         markdown/0,
         false/0,
         sigils/0]).

-doc("Documentation in one line").

single_line() -> ok.

-doc("You can use").

-doc(#{attributes => #{as => maps}}).

attributes() -> {as, maps}.

-doc({file, "external.md"}).

external() -> {in, a, file}.

-doc("Can contain markdown...\n# Title\n## "
     "Subtitle\n### Level 3\n**bold**, _italic_").

markdown() -> ok.

-doc(false).

false() -> false.

sigils() ->
    {<<"This is valid now"/utf8>>,
     <<"<<\"This, too\">>"/utf8>>,
     <<"This one, as well"/utf8>>,
     <<"This is a multi-line\n        string "
       "that can have a quotation mark: \"\nas "
       "the one in the previous row"/utf8>>,
     "Confusingly enough, this is also a string",
     'not a string,'}.

And this is how ktn_dodger + a slightly adjusted default_formatter would format it like this…

-module(otp27).

-moduledoc "    New stuff introduced in OTP27.".
-export([single_line/0, attributes/0, external/0, markdown/0, false/0, sigils/0]).

-doc "Documentation in one line".
single_line() ->
    ok.

-doc "You can use".
-doc #{attributes => #{as => maps}}.
attributes() ->
    {as, maps}.

-doc {file, "external.md"}.
external() ->
    {in, a, file}.

-doc "Can contain markdown...\n# Title\n## Subtitle\n### Level 3\n**bold**, _italic_".
markdown() ->
    ok.

-doc false.
false() ->
    false.

sigils() ->
    {<<"This is valid now"/utf8>>,
     <<"<<\"This, too\">>"/utf8>>,
     <<"This one, as well"/utf8>>,
     <<"""
        This is a multi-line
                string that can have a quotation mark: "
        as the one in the previous row
        """/utf8>>,
     "Confusingly enough, this is also a string",
     'not a string,'}.

That's because the parsers do not return information about…

• How sigils were written in the first place. They are all returned as binaries with utf8 strings in them.
• How heredoc strings were written in the first place. You can't distinguish between someone writing \n or using multiple lines to write the string.

[elbrujohalcon]

I'm seriously considering discontinuing this project specifically because of that. ☝🏻
I think it might be possible to adjust ktn_dodger to include all the missing information, but I'm not sure at all…

I'll open a discussion.