[draft] guidelines for "elm-format approved" IDE integrations

[avh4]

This is a draft of guidelines for IDEs and IDE plugins that want to officially integrate with elm-format.

The goal of elm-format is to make it as easy as possible to follow a standard, consistent style so that everyone can get the benefit of code that is easier to write, easier to read, and easier to maintain.

An "elm-format approved" plugin does the following:

• Formatting
  • When formatting a file, if the in-memory version of the file and the on-disk version of the file differ, then the plugin should format the in-memory version of the file. (Saving the file before formatting is also acceptable.)
  • When formatting a file, the cursor position and scroll position should be maintained.
    • Currently recommended: save the cursor index into the buffer before formatting, and set the cursor to the same index after formatting
    • Future: elm-format will provide additional information for translating cursor positions (see provide a way to maintain cursor locations across formats #149)
• Format on save
  • The default behavior should be to format any *.elm files on save when working on an Elm project if elm-format is found.
  • If linting or compilation is also triggered on save, elm-format should be run before linting or compiling.
• Configuration

  • If the path to elm-format has not be explicitly specified by the user, the plugin should automatically find elm-format if it is located on the $PATH, in /usr/local/bin/, or in node_modules/.bin/ relative to the current project.

    Is there an equivalent of /usr/local/bin/ for Windows?

    We should also add the path where npm install -g installs to, since this is the most common issue people have with plugin installation

  • If elm-format is not found, a message should be shown including a link to the elm-format installation instructions ( https://github.com/avh4/elm-format#installation- ). The message will be shown on the plugin settings screen if such a screen exists, and any time the user explicitly tries to format a file. The message may also be shown when the plugin is first installed or when saving an elm file.

• Error handling
  • If an error is displayed to the user due to the elm-format binary not being found, then the error should include a link to the elm-format installation instructions ( https://github.com/avh4/elm-format#installation- )
  • If the plugin runs both elm-format and compilation, compilation should be run regardless of whether or not elm-format reports an error.
  • The user should be shown errors reported by compilation in preference to any errors reported by elm-format. (If elm-format ever reports an error when normal compilation does not, please report this as a bug.)

An "elm-format approved" IDE comes with an "elm-format approved" plugin installed and enabled, or otherwise provides all the features of an "elm-format approved" plugin.

[Bogdanp]

The default behavior should be to format any *.elm files on save when working on an Elm project.

I think this should be opt in behavior rather than the default.

[avh4]

@Bogdanp Can you elaborate on why you think it should be opt-in? The goal for elm-format is to make it as easy as possible for people to follow the Elm style guide.

[Bogdanp]

I should have done that in my original comment :). Here are a few bullet points:

• IDEs and programming modes generally support multiple versions of a language. Running elm-format on Elm 0.15 source can fail with a syntax error, for example.
• If the plan is for elm-format to be included in the next release of the Elm platform this is probably a moot point, but users shouldn't have to install additional software before they can start using a programming mode.
• It constitutes surprising behavior for users that don't expect the programming mode to do that for them. I can't think of any IDE/mode/plugin that does that by default off the top of my head (obviously that doesn't mean they don't exist :P).

Re the first point, how will elm-format deal with any syntax changes to the language in 0.17 (assuming there will be such changes)? Will all elm-format users be forced to upgrade?

[avh4]

I updated the draft to hopefully clarify that if elm-format is not found, then the plugin doesn't need to constantly show error messages on save.

The 1.0 release is not going to be until a while after Elm 0.17 is released, so there won't be a stable release that supports Elm 0.16. But in the future, there will be separate elm-format versions for each Elm version. (For example, you will install one of elm-format-0.17-1.0.0 or elm-format-0.18-1.0.0 depending on which version of Elm you are using.) The only difference between those two elm-format versions will be which Elm syntax version is the default--both binaries will support both Elm versions, and there will be a --elm-version command line arg to override the default if desired. A plugin could either depend on the user to instal the correct elm-format version, or try to detect the Elm version and pass the command line argument.