Contacts for Support

• @rupertlssmith on https://elmlang.slack.com
• @rupert on https://discourse.elm-lang.org

elm-syntax-dsl

Provides a DSL that makes it simpler to write code in Elm that generates Elm code; simpler than stil4m/elm-syntax on which this DSL is based.

Provides a pretty printer that prints out the abstract syntax tree constructed using the DSL as Elm source code, in a way that aims to be compatible with elm-format.

Simpler code generation as a DSL.

stil4m/elm-syntax uses a lot of records to capture parameters, and also wraps parts of the AST in Nodes that capture source code lines and rows corresponding to parts of the AST. This DSL inlines most of the records as function parameters.

stil4m/elm-syntax is spread across around 17 modules for the complete syntax. This makes working with it a little awkward because there are a lot of import statements to write. This DSL condenses everything into a single exposed module, which helps to get started with code generation more easily.

Any parts of the AST needing to be wrapped in nodes are automatically wrapped in nodes with zeroed out source code position information. As the purpose of this package is code generation of Elm from scratch, rather than the analysis or manipulation of existing Elm, it is ok to have the source code positional information zeroed out.

Automatic insertion of parenthesis.

Parenthesis are inserted into code automatically if they are required by the precedence rules of Elm syntax. Note that this is done at the Expression level, as expressions are built, rather than during pretty printing.

import Elm.CodeGen as CodeGen
import Elm.Pretty
import Pretty

expr =
    CodeGen.apply
        [ CodeGen.val "map"
        , CodeGen.construct "C" []
        , CodeGen.apply [ CodeGen.val "foo", CodeGen.val "arg" ]
        ]

result =
    Elm.Pretty.prettyExpression expr |> Pretty.pretty 120

Will print the result:

map C (foo arg)

Pretty printing stable under elm-format.

The pretty printer aims to be fully stable with respect to elm-format in the sense that running elm-format on the output should have no effect at all. The advantage of this is that if generated code moves to being edited by hand, there will not be a large white-space only diff created when elm-format is applied.

How to get the results as a String.

To print the Doc created by the pretty functions, the-sett/elm-pretty-printer is used:

import Elm.Pretty
import Pretty

-- Fit to a page width of 120 characters
elmAsString =
    Elm.Pretty.prepareLayout 120 someFile
        |> Pretty.pretty 120

Broken stuff in elm-syntax:

• Not all Elm files I tried seem to parse.
• Multi-line strings do something very weird and get jumbled up in order.
• End-line comments are deleted.

Unimplemented stuff:

• GLSL syntax.
• Any reformatting of comments.
• Re-formatting the module exposings to match @docs tags in comments.

Known deviations from elm-format:

• Float literals not getting a .0 added at the end.
• Type annotations on functions sometimes split onto next line without being broken themselves.

Testing it.

1. Put some .elm files in test/examples.
2. Create directories test/pre and test/post.
3. In test/ run npm start.
4. Diff /pre and /post to see how well it compares with elm-format.

Some other thoughts.

This could be used to create a command line tool elm-pretty. Needs to address the broken stuff first though. End-line comments is a deal breaker on elm-syntax too, so quite a bit of work to achieve this.

Due to the above, this is aimed at use for code generation purposes for the present.

Will always aim to be compatible with the latest elm-format, there is no point in introducing a new standard to compete with it. Any deviations from elm-format invariance please create issues or pull requests, which will be gratefully received.