atom-elmjutsu

by halohalospecial

halohalospecial / atom-elmjutsu

A bag of tricks for developing with Elm. (Atom package)

199 Stars 21 Forks Last release: about 4 years ago (v2.5.4) MIT License 683 Commits 184 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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
    :
  • For
    Autocomplete
    :
  • For
    Datatips
    :
  • Add your keybindings.

Features Overview

Note: Features marked with

*
are disabled by default. You may enable them in the Settings view.

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
    [email protected]
    (
    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).

error-highlighting

  • 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.

show-inferred-type-annotations

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.

quick-fix-replace-with

  • 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.

autocomplete

Global Autocomplete
*

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

auto-import

Filtering suggestions

  • Fuzzy Filtering
    *

You can check

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

autocomplete-fuzzy-filtering

  • 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.

autocomplete-regex-filtering

  • 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.

autocomplete-type-filtering

  • 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.

autocomplete-snippet

Special Completions :zap:

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

  • :zap:
    Insert program

Type

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

construct-html-program

  • :zap:
    Insert module
  • :zap:
    Insert let/in
  • :zap:
    Insert if/then/else

construct-basic

  • :zap:
    Insert case/of

construct-case-of

  • :zap:
    Insert default arguments

construct-default-arguments

  • :zap:
    Replace type with default

construct-default-value-for-type

  • :zap:
    Define from type annotation

construct-from-type-annotation-1

construct-from-type-annotation-2

construct-from-type-annotation-3

  • :zap:
    Auto import

See Global Autocomplete.

  • :zap:
    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.

type-aware-autocomplete

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

    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

    go-to-symbol

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

    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.

datatips

Signature Help

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

signature-help

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
).

show-types-in-tooltip

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.)

sidekick1

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

sidekick3

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

sidekick2

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
    ) :cry: This will be fixed in the future.

infer-types-on-the-fly

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).

add-import

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 
        .
      • 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  
        (or
        elm-package install --yes 
        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:

    
    
    

    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.

hot-reloading

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.

    rename-symbol

  • Elmjutsu: Surround With Let

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

    surround-with-let

  • 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.

    lift-to-let

  • 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.

    lift-to-top-level

Keybindings

Here is an example: ```cson '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 ``` <!-- 'atom-text-editor': 'alt-enter': 'elmjutsu:eval' 'ctrl-enter': 'elmjutsu:pipe-selections'

'.elmjutsu-pipe-selections': "ctrl-enter": "elmjutsu:apply-pipe-selections" ``` -->

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.