[draft] guidelines for "elm-format approved" IDE integrations
avh4 opened this issue · 8 comments
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 #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.
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.
@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.
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?
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.
I've installed elm-format
on windows 10
as described in the readme
and checked the format on save
option.
If I open a file in atom
and change the format so its incorrect then hit save, nothing changes. I've also set show error notifications on save
and I get a message elm-format exited with code null
. So elm-format
is being called. However, the file is not reformatted.
If I run elm-format
from the command line the file is formatted correctly (I can see it get "refreshed" in atom
) so elm-format
exists on the path
.
I've set the binary path
in the package settings to the location I downloaded and installed elm-format
. Which I added to the path
.
Any idea why it works correctly from the command line
but not from within atom
?
@Rolograaf Looks like I didn't have atom-beautify
or at least I didn't have Beautify On Save
checked in the Elm
setting.
Working great now, thanks for the help.
In atom-elm-format
we're always formatting the buffer (using --stdin
) and not the file. We're also saving the cursor position. Would that qualify for a green checkmark under "formatting"? :)