Elmjutsu

A bag of tricks for developing with Elm.

https://atom.io/packages/elmjutsu

Setup

• Install Elm.
• Install language-elm (no need to install elm-oracle or goto).
• For Error Highlighting:
  • Install atom-ide-ui or linter + linter-ui-default.
  • With linter v2 API (linter 2.3.0 and above), tooltips are collapsed by default. You have to click expand buttons (">"), or bind linter-ui-default:expand-tooltip to some key and hold it to expand them.
  • When moving from atom-ide-ui to linter (and vice versa), you need to reload Atom for now.
• For Go to Definition:
  • Install atom-ide-ui or hyperclick (both optional).
• For Autocomplete:
  • Install autocomplete-plus (installed by default).
  • Install snippets (optional, installed by default).
• For Datatips:
  • Install atom-ide-ui (optional).
• Add your keybindings.

Features Overview

Note: Features marked with * are disabled by default. You may enable them in the Settings view.

• Error Highlighting

  • Always Compile Main
  • Set Main Paths
  • Set Compile Output Path
  • Report Warnings
  • Show Inferred Type Annotations
  • Compile With Debugger
  • Compile With Optimizations
  • Quick Fixes
  • Quick Fix File

• Autocomplete

  • Global Autocomplete *
  • Filtering suggestions
    • Fuzzy Filtering *
    • Regex Filtering
    • Type Filtering
  • Autocomplete Snippets *
  • Special Completions
  • Type-Aware Autocomplete *
  • Performance Tuning

• Navigation

  • Go to Definition
  • Go to Symbol
  • Find Usages
  • Go to Next Usage
  • Go to Previous Usage
  • Go Back

• Information

  • Datatips
  • Signature Help
  • Show Types in Tooltip *
  • Toggle Sidekick
    • Show the type and documentation for the symbol at cursor position in a panel.
  • Infer Type
  • Infer Types on the Fly *

• Imports Management

  • Add Import
  • Add Import As

• Package Management

  • Install Package
  • Uninstall Package

• Hot Reloading

• Refactoring

  • Rename Symbol
  • Surround with let
  • Lift to let
  • Lift to top-level

Feature Details

This package parses your projects' source files to extract information, and downloads documentation of 3rd-party Elm packages. The downloaded documentation files will be saved to the path set in Cache Directory in the Settings view. If Cache Directory is blank, a temporary directory will be used. Take note that most operating systems delete temporary directories at bootup or at regular intervals.

Error Highlighting

• This only works for Elm 0.19 onwards. It's recommended to disable linter-elm-make.
• Make sure that Elm Path is properly configured in the package settings. The default works for most cases.
• You can configure the Elm Test Path setting to use elm-test to check for compile errors in test files (.elm files inside the tests directory). NOTE: This only works with elm-test@beta (0.19-beta10) right now.
• If you are using Elm 0.18, it's better to disable this option by setting Run elm make to "never" and use linter-elm-make instead.
• If you want to change the appearance of the error messages, look into error-highlighting.less and copy the styles to your ~/.atom/styles.less (where ~/.atom is your Atom directory).

• Useful Commands
  • Atom IDE
    • Diagnostics: Go To Next Diagnostic
    • Diagnostics: Go To Previous Diagnostic
    • Diagnostics: Toggle Table
  • Linter v2
    • Linter Ui Default: Next
    • Linter Ui Default: Previous
    • Linter Ui Default: Toggle Active Editor
  • Linter v1
    • Linter: Next Error
    • Linter: Previous Error
    • Linter: Toggle

Always Compile Main

• If enabled, the main file(s) will always be compiled instead of the file being edited. The main files can be set using the Elmjutsu: Set Main Paths command. If not set, the linter will look for Main.elm files in the source directories. Take note that if this is enabled, modules unreachable from the main modules will not be linted.

• The main paths will be ignored if the project type is "package" (in elm.json).

• Disabled by default.

Elmjutsu: Set Main Paths

Sets the main paths of the project and saves them to elmjutsu-config.json.

Example:

{
  "mainPaths": ["Todo.elm", "Test.elm"]
}

The main paths are only relevant if Always Compile Main is enabled. See Always Compile Main.

Elmjutsu: Set Compile Output Path

Sets the output path of the project and saves it to elmjutsu-config.json. Defaults to "/dev/null" if not set.

Example:

{
  "outputPath": "main.js"
}

Report Warnings

• Also report warnings instead of just the errors. Disabled by default (for now).
• Since the latest compiler (0.19) does not output warnings anymore, hacks are currently used to determine missing type annotations.

Show Inferred Type Annotations

• This will only work if Report Warnings is also checked.

Compile With Debugger

• Adds the --debug flag to elm make.
• Enabling this will automatically disable Compile With Optimizations.

Compile With Optimizations

• Adds the --optimize flag to elm make.
• Enabling this will automatically disable Compile With Debugger.

Quick Fixes

• If you have atom-ide-ui installed, you can invoke the Diagnostics: Show Actions At Position command or click on the appropriate button from the panel. You can uncheck Enable Code Actions in the Settings view if you do not want to show the buttons.

• Available Quick Fixes:
  • Replace with
  • Add missing patterns
  • Add import
  • Add import as
  • Define top-level
  • Install package
  • Add type annotation
  • Convert using

Elmjutsu: Quick Fix File

• Fixes all issues in the active text editor in one go. If there is more than one fix for an issue, it will choose the first from the list.

Autocomplete

This provides suggestions for imports, project symbols, and 3rd-party package symbols.

• It's recommended to uncheck Enable autocomplete of the language-elm package to prevent duplicate suggestions.

Global Autocomplete *

• Check Enable Global Autocomplete if you want to include unimported project symbols.
  • This will also allow ⚡Auto import completion (which works like Add Import).
  • Take note that you may experience lag if you have a large project.

Filtering suggestions

• Fuzzy Filtering *

  You can check Enable Autocomplete Fuzzy Filtering to filter suggestions using fuzz-aldrin-plus.

  

• Regex Filtering

  If the typed text starts with a slash (/), the rest of the characters will be used as a regular expression to filter the suggestions by name.

  

• Type Filtering

  If the typed text starts with a colon (:), the rest of the characters will be used as a regular expression to filter the suggestions by type signature.

  

  • If you want to filter by name and type signature, put two underscores (__) in between. For example, :cons__String will suggest String.cons (Char -> String -> String) and String.uncons (String -> Maybe.Maybe ( Char, String )).

  • Use underscores in lieu of spaces (e.g. to match List a, type List_a).

  • Remember to escape dots, vertical bars, braces (for records), parentheses (for tuples), etc.

Autocomplete Snippets *

• You can also check Enable Autocomplete Snippets if you prefer.

Special Completions ⚡

Press tab to go to the next tab stop (similar to how snippets work). Special completions can be disabled individually in the package settings.

• ⚡Insert program

  Type "html", "Html.program", "platform", or "Platform.program" in an empty editor to insert skeleton code.

• ⚡Insert module
• ⚡Insert let/in
• ⚡Insert if/then/else

• ⚡Insert case/of

• ⚡Insert default arguments

• ⚡Replace type with default

• ⚡Define from type annotation

• ⚡Auto import

  See Global Autocomplete.

• ⚡Replace with inferred type

  See Type-Aware Autocomplete for a screenshot.

Type-Aware Autocomplete *

• Check Enable Type-Aware Autocomplete if you want to prioritize suggestions matching the expected type at cursor position.
  • The type can be inferred via the Infer Type command, but it's recommended to check Infer Expected Type At Cursor On The Fly in the package settings instead.
  • WARNING: This is highly experimental and may cause lag, especially if Enable Global Autocomplete is also checked.

Performance Tuning

• It's recommended to uncheck Enable autocomplete of the language-elm package. No need to install elm-oracle.

• If you are experiencing lag while typing, you can set the value of Max Number of Autocomplete Suggestions to a small number such as 50 so that Atom will have less items to render.

• Enabling both Global Autocomplete and Type-Aware Autocomplete will usually result to lag because there will be lots of computations involved. This may be improved in the future.

Navigation

• Elmjutsu: Go To Definition

  

  • If the atom-ide-ui or hyperclick package is installed, you can also check Enable Hyperclick to jump to definition using Ctrl + click / Cmd + click (Mac).

• Elmjutsu: Go To Symbol

  

  • You can type a : (colon) in the text box to also filter by type.

• Elmjutsu: Find Usages

  

• Elmjutsu: Go To Next Usage

  Moves the cursor to the position of the next usage.

• Elmjutsu: Go To Previous Usage

  Moves the cursor to the position of the previous usage.

• Elmjutsu: Go Back

  The current cursor position is added to a navigation stack before jumping via:

  • Go To Definition
  • Go To Symbol
  • Go To Next Usage
  • Go To Previous Usage
  • Clicking on a source path link (Sidekick and Datatip).

  Invoke this command to jump back to the previous position.

• Elmjutsu: Hide Usages Panel

  Closes the Usages panel (the panel is shown after invoking Find Usages or Rename Symbol).

Datatips

Provides support for Datatips. The atom-ide-ui package should be installed for this to work.

Signature Help

Provides support for Signature Help. The atom-ide-ui package should be installed for this to work.

Show Types in Tooltip *

This is disabled by default. To turn it on, check Show Types in Tooltip in the package settings. You can also change the placement of the tooltip (Types Tooltip Position).

Elmjutsu: Toggle Sidekick

Shows the type hints and documentation for the symbol at cursor position. The size, position of the panel, and amount of information to show can be modified in the package settings.

• Example #1 (default): Sidekick Position = "bottom", Sidekick Size = 0 (Automatically resizes to fit content.)

• Example #2: Sidekick Position = "right", Sidekick Size = 300

• Example #3: Sidekick Position = "bottom", Show Types in Sidekick is checked, Show Doc Comments in Sidekick and Show Source Paths in Sidekick are unchecked.

Elmjutsu: Infer Type

• Select some text or make sure that the cursor is between whitespaces or before a closing parenthesis before invoking this command. If nothing is selected and the cursor is not between whitespaces, the word under the cursor will be selected.
• Make sure that Elm Make Path is properly configured in the package settings. The default works for most cases.
• To be able to see the inferred types, at least one of these should be true:
  • Show Types in Tooltip is checked
  • Show Datatips is checked
  • The Sidekick panel is visible
• This uses similar tricks as those described in Type Bombs in Elm, which may sometimes fail or give incorrect results.

Infer Types on the Fly *

• You can also check the Infer Expected Type At Cursor On The Fly and Infer Type Of Selection On The Fly options in the package settings.
• WARNING: Infer Type Of Selection On The Fly currently has bad interactions with some packages that decorate the markers (e.g. Find And Replace) 😢 This will be fixed in the future.

Elmjutsu: Add Import

Quickly adds an import without scrolling to the top of the file. Also sorts the imports, removes duplicates, and removes defaults automatically.

• ProTip: There's no "Sort Imports" command, but you can achieve the same result by invoking Add Import and choosing an already imported symbol (like +, for example).

Elmjutsu: Add Import As

Adds an alias to the added import (see Add Import).

Package Management

• Elmjutsu: Install Package

  Quickly installs a package.

  • Elm 0.19 and above

    • Runs elm install <name>.
    • Does not support installing a specific version yet.
    • Make sure that Elm Path is properly configured in the package settings. The default works for most cases.

  • Elm 0.18

    • Runs elm-package install --yes <name> <version> (or elm-package install --yes <name> if the selected version is "Auto").
    • Make sure that Elm Package Path is properly configured in the package settings. The default works for most cases.

• Elmjutsu: Uninstall Package

  Removes an installed package.

  • Elm 0.19 and above

    • Not yet supported.

  • Elm 0.18

    • This removes the dependency from elm-package.json, then runs elm-package install --yes to clean up.

Hot Reloading

• Enable Hot Reloading should be checked in the Settings view to start a hot reloading server.

• You can then add something like the following to your HTML file to watch a specific JS file for changes:

  <script src="http://localhost:3000/build?path=~/Desktop/project/Main.js"></script>

  Replace ~/Desktop/project/Main.js with the output file path from elm make (--output flag). You can also use the Set Compile Output Path command to set the output file path for your project.

• This uses elm-hot to inject hot reloading code into the Elm app. The modified code is then sent to the browser via a web socket connection.

Refactoring

• Elmjutsu: Rename Symbol

  Renames the symbol across the whole project. Take note that this is not an undoable operation.

  • Press enter to rename or escape to cancel.
  • Uncheck usages to exclude.
  • Modified modules with open editors will not be saved automatically.
  • Renaming a module will not rename the associated file.
  • Currently, this also modifies the symbol name inside comments.

  

• Elmjutsu: Surround With Let

  • Press escape when you're done naming your variable.

  

• Elmjutsu: Lift To Let

  • Press escape when you're done naming your variable.
  • There are still cases where this will not work properly. There will be a better implementation in the future.

  

• Elmjutsu: Lift To Top Level

  • Press escape when you're done naming your function.
  • This does not compute the needed function arguments (yet?), so you also have to type those in with the function name.

  

Keybindings

Here is an example:

'atom-text-editor:not([mini])[data-grammar^="source elm"]':
  'f12': 'elmjutsu:go-to-definition'
  'ctrl-r': 'elmjutsu:go-to-symbol'
  'shift-f12': 'elmjutsu:find-usages'
  'f8': 'elmjutsu:go-to-next-usage'
  'shift-f8': 'elmjutsu:go-to-previous-usage'
  'ctrl-f12': 'elmjutsu:go-back'
  'alt-insert': 'elmjutsu:add-import'
  'f2': 'elmjutsu:rename-symbol'
  'alt-shift-l': 'elmjutsu:surround-with-let'
  'alt-l': 'elmjutsu:lift-to-let'
  'alt-t': 'elmjutsu:lift-to-top-level'
  'alt-i': 'elmjutsu:infer-type'
  'f6': 'diagnostics:show-actions-at-position'

'atom-workspace':
  'f1': 'elmjutsu:toggle-sidekick'
  'ctrl-shift-f12': 'elmjutsu:hide-usages-panel'
  'ctrl': 'linter-ui-default:expand-tooltip' # For linter and linter-ui-default users

Add them to your keymap.cson or bind them from Settings > Keybindings.

Notes

• Be sure to check out the settings for this package to find out about the available options.
• It's highly recommended to read CHANGELOG.md before upgrading to a newer version to check for breaking changes.
• The commands only work for top-level values for now.
• This package may fail to activate (when starting Atom) if you don't have elm.json or elm-package.json (Elm 0.18) files in your Elm project directories. This issue will be handled properly in the future.
• You may encounter weird behaviors if multiple files are using the same module name in your project.

Credits

• The initial code was based on the source of Try Elm.