Notepad++ Linter++

This plugin provides realtime code checks of a file with any checkstyle-compatible linter: jshint, eslint, jscs, phpcs, csslint etc.

It is a fork of both:

• the 'linter' plugin by deadem
• the now defunct jslintnpp plugin by Martin Vladic.

Installation

1. See https://npp-user-manual.org/docs/plugins/ and use the plugin manager.
2. Go to Plugins -> Linter++ -> Edit config. This will give you a blank configuration file. Edit to taste.

Changes from the linter plugin

1. It has a docking window similar to that provided by the jslint plugin, which displays a list of all the detected errors in the file (by default sorted by line), and the tool which detected the issue.
2. There are menu entries which allow you to see the next or previous message. You don't need the dialogue window open to use these.
3. The window will also display (in a separate tab) any messages resulting from failures to execute checker programs.
4. It is no longer necessary to restart notepad++ after changing the configuration (unless you change the shortcut keys).
5. The linter configuration file has changed considerably, and it now gets validated against an xsd file.

Configuration

You can adjust your configration by editting the file Linter++.xml in %AppData%\plugins\config\Linter++.

There are 5 sections to the configuration file. You do need to supply a list of linters, but the rest of the configuration is optional.

1. Miscellaneous
2. Indicator
3. Messages
4. Shortcut Keys
5. Environment Variables
6. Linters

A note: Please don't supply empty sections, as this will become an error in the future. Just leave them out entirely.

Miscellaneous

This section contains miscellaneous parameters that don't fit in any other category. All of them are optional.

<misc>
  <disabled/>
  <font>
    <!-- add as many or as few things as you need. All are optional. -->
    <typeface>Times New Roman</typeface>
    <style>Type style (used if typeface not specified or can't be found)</style>
    <height>height in device units</height>
    <width>width in device units</width>
    <weight>weight in textual or numeric format</weight>
    <italic/>
    <underline/>
    <strikethrough/>
  </font>
</misc>

1. disabled - if this is supplied, the plugin will be disabled on startup, as if you'd used the 'Enabled' toggle to switch it off.
2. font - this allows you to specify the font to use in the tab list. It is a little complicated in an attempt to match the windows CreateFont api. Please see that for style names and weight names. I'd suggest not mixing a font name and a font style as the results can be really confusing if you you pick a weight that isn't supported...

Indicator

You can control all the various settings for a scintilla indicator here. Your xml will look something like this:

<indicator>
  <colour>
    <shade>
      <red>255</red>
      <green>0</green>
      <blue>0</blue>
    </shade>
  </colour>
  <style>roundbox</style>
  <fill_opacity>30</fill_opacity>
  <outline_opacity>255</outline_opacity>
  <draw_under/>
  <hover>
    <style>box</style>
    <colour> <red>20</red> <green>20</green> <blue>250</blue> </colour>
  </hover>
</indicator>

If you use <as_message/> instead of <shade>...</shade> in the top level <colour>...</colour> block, then the colour of the indicator will match the colour of the message in the message window. This sadly isn't available for the hover colour.

It's best to read the scintilla documentation and play around a little bit to determine what works best for you.

Messages

By default, error messages will be shown in the docked dialogue window as red, warning messages as orange, and any other messages are shown in cyan (I'd be interested to find out if anyone gets this colour and under what circumstances).

You can change the colours by adding a <messages> section, like this:

<messages>
  <default> <red>0</red> <green>255</green> <blue>255</blue> </default>
  <error> <red>255</red> <green>0</green> <blue>0</blue> </error>
  <warning> <red>127</red> <green>127</green> <blue>0</blue> </warning>
</messages>

You don't need to specify all of the entries here, just the ones where you want to override the default.

Shortcut Keys

You can supply shortcut keys for one or more of the menu entries, like this:

<shortcuts>
  <edit><alt/><ctrl/><key>F5</key></edit>
  <show><shift/><ctrl/><key>F6</key></show>
  <previous><ctrl/><key>F7</key></previous>
  <next><key>F8</key></next>
  <on_off><key>F9</key></on_off>
</shortcuts>

There may be some other keys which you'd like to use for shortcuts (only F1-F12, num pad 0-9, and the 6 keys in the insert..page down block are set up currently). Please let me know and I'll try to add them.

Notes:

1. Changing the shortcuts will not take effect till next time you start notepad++
2. Notepad++ determines which shortcuts get which keypresses, so take care not to clash with shortcuts from other plugins.

Environment Variables

As you can see below, you can use windows environment variables in your command line. linter++ also provides some of its own variables and allows you to define your own variables.

Please note that these variables also get passed to the called linters as environment variables.

Predefined variables

There are also some pseudo environment variables provided by linter++:

• %LINTER_PLUGIN_DIR% - Directory where linter++.dll is installed
• %LINTER_CONFIG_DIR% - Directory where your linter++.xml is installed.
• %LINTER_TARGET% - temporary linter file
• %TARGET% - original file (e.g. c:\users\me\fred.js)
• %TARGET_DIR% - directory of original file (e.g. c:\users\me)
• %TARGET_EXT% - extension of original file (e.g. .js)
• %TARGET_FILENAME% - filename of original file (e.g. fred.js)

User defined variables

You can define your own variables to use if the supplied ones aren't enough, by adding a <variables> section to the XML so the following will define a GIT_REPO_ROOT which can be used in linter commands (or other variable definitions).

<variables>
  <variable>
    <name>GIT_REPO_ROOT</name>
    <command>
      <program>%ProgramFiles%\GIT\cmd\git.exe</program>
      <args>rev-parse --show-toplevel</args>
    </command>
  </variable>
</variables>

The command will be run and the output will be stored in the named variable, excluding the trailing newline.

Variables are defined in the order in which they appears in the XML, so later ones can use earlier ones. Any of them can use the automatically defined variables.

The <command> element

You will see both here and in the linters section below the use of <command> elements which contain a <program> element and an <args> element.

These are used to run the chosen programs. The specified program will be run with the specified arguments. Both will have any environment variables (like %UserProfile%) expanded before the program is executed. It is recommended for <args> elements that you enclose environment variables in double quotes in case the expansion contains spaces. However, you should NOT do that for <program> elements.

Whitespace in the <args> element will be trimmed from the start and end, and compacted to a single white space so you can make your xml moderately readable.

Linters

A linter definition consists of a list of extensions to match, and a list of program to run (specified as command line and arguments).

For instance, you may wish to use eslint, jscs and jshint on all files with .js or .jsm extensions and run css lint on all css file. Your linters section would end up looking something like this:

<linters>
  <linter>
    <extensions>
     <extension>.js</extension>
     <extension>.jsm</extension>
    </extensions>
    <commands>
      <command>
        <program>%AppData%\npm\eslint.cmd</program>
        <args>
          -c "%USERPROFILE%"\eslintrc.yaml
          --resolve-plugins-relative-to="%AppData%"\npm
          --format checkstyle %%
        </args>
      </command>
      <command>
        <program>%AppData%\npm\jscs.cmd</program>
        <args>--reporter=checkstyle %%</args>
      </command>
      <command>
        <program>%AppData%\npm\jshint.cmd</program>
        <args>--reporter=checkstyle %%</args>
      </command>
    </commands>
  </linter>
  <linter>
    <extensions>
      <extension>.css</extension>
    </extensions>
    <commands>
      <command>
        <program>%AppData%\npm\csslint.cmd</program>
        <args>--format=checkstyle-xml</args>
      </command>
    </commands>
  </linter>
</linters>

If you don't specify %LINTER_TARGET% or %% in your <args> element, it is assumed that your linter process its input from stdin (as is the case for the csslint command in the example above).

The <args> element will accept %% as the last two characters as a shortcut for "%LINTER_TARGET%".

Example

Putting all those together, we get this:

<?xml version="1.0" encoding="utf-8" ?>
<LinterPP>
  <indicator>
    <colour>
      <shade>
        <red>255</red>
        <green>0</green>
        <blue>0</blue>
      </shade>
    </colour>
    <style>roundbox</style>
    <fill_opacity>30</fill_opacity>
    <outline_opacity>255</outline_opacity>
    <draw_under/>
  </indicator>

  <messages>
    <default> <red>0</red> <green>255</green> <blue>255</blue> </default>
    <error> <red>255</red> <green>0</green> <blue>0</blue> </error>
    <warning> <red>127</red> <green>127</green> <blue>0</blue> </warning>
  </messages>

  <shortcuts>
    <edit><alt/><ctrl/><key>F5</key></edit>
    <show><shift/><ctrl/><key>F6</key></show>
    <previous><ctrl/><key>F7</key></previous>
    <next>><key>F8</key></next>
  </shortcuts>

  <variables>
    <variable>
      <name>GIT_REPO_ROOT%</name>
      <command>
        <program>%ProgramFiles%\GIT\cmd\git.exe</program>
        <args>rev-parse --show-toplevel</args>
      </command>
    </variable>
  </variables>

  <linters>
    <linter>
      <extensions>
       <extension>.js</extension>
       <extension>.jsm</extension>
      </extensions>
      <commands>
        <command>
          <program>%AppData%\npm\eslint.cmd</program>
            <args>
              -c "%USERPROFILE%"\eslintrc.yaml
              --resolve-plugins-relative-to="%AppData%"\npm
              --format checkstyle
              %%
            </args>
        </command>
        <command>
          <program>%AppData%\npm\jscs.cmd</program>
          <args>--reporter=checkstyle %%</args>
        </command>
        <command>
          <program>%AppData%\npm\jshint.cmd</program>
          <args>--reporter=checkstyle %%</args>
        </command>
      </commands>
    </linter>
    <linter>
      <extensions>
        <extension>.css</extension>
      </extensions>
      <commands>
        <command>
          <program>%AppData%\npm\csslint.cmd</program>
          <args>--format=checkstyle-xml</args>
        </command>
      </commands>
    </linter>
    <linter>
      <extensions>
        <extension>.ps1</extension>
      </extensions>
      <commands>
        <command>
          <program>%ProgramFiles%\PowerShell\7\pwsh.exe</program>
          <args>
            -File "%LINTER_PLUGIN_DIR%\powershell-linter.ps1"
            -Settings "%GIT_REPO_ROOT%"\Settings.psd1
            %%
          </args>
        </command>
      </commands>
    </linter>
  </linters>
</LinterPP>