runtime/plugins/linter/help/linter.md

   1 # Linter
   2
   3 The linter plugin runs a compiler or linter on your source code
   4 and parses the resulting output so that the messages and line numbers
   5 can be viewed from within micro. By default, the plugin supports the
   6 following filetypes and linters:
   7
   8 * c: gcc
   9 * c++: g++
  10 * d: dmd
  11 * go: go build
  12 * haskell: hlint
  13 * java: javac
  14 * javascript: jshint
  15 * javascript: eslint
  16 * literate: lit
  17 * lua: luacheck
  18 * nim: nim
  19 * objective-c: clang
  20 * python: pyflakes
  21 * python: mypy
  22 * python: pylint
  23 * shell: shfmt
  24 * swift: swiftc (MacOS and Linux only)
  25 * yaml: yamllint
  26
  27 If the linter plugin is enabled and the file corresponds to one of
  28 these filetypes, each time the buffer is saved, or when the `> lint`
  29 command is executed, micro will run the corresponding utility in the
  30 background and display the messages when it completes.
  31
  32 The linter plugin also allows users to extend the supported filetypes.
  33 From inside another micro plugin, the function `linter.makeLinter` can
  34 be called to register a new filetype. Here is the spec for the `makeLinter`
  35 function:
  36
  37 * `linter.makeLinter(name, filetype, cmd, args, errorformat, os, whitelist, domatch, loffset, coffset, callback)`
  38
  39 > name: name of the linter
  40 > filetype: filetype to check for to use linter
  41 > cmd: main linter process that is executed
  42 > args: arguments to pass to the linter process
  43     use %f to refer to the current file name
  44     use %d to refer to the current directory name
  45 > errorformat: how to parse the linter/compiler process output
  46     %f: file, %l: line number, %m: error/warning message
  47 > os: list of OSs this linter is supported or unsupported on
  48     optional param, default: {}
  49 > whitelist: should the OS list be a blacklist (do not run the linter for these OSs)
  50            or a whitelist (only run the linter for these OSs)
  51     optional param, default: false (should blacklist)
  52 > domatch: should the filetype be interpreted as a lua pattern to match with
  53          the actual filetype, or should the linter only activate on an exact match
  54     optional param, default: false (require exact match)
  55 > loffset: line offset will be added to the line number returned by the linter
  56          useful if the linter returns 0-indexed lines
  57     optional param, default: 0
  58 > coffset: column offset will be added to the col number returned by the linter
  59          useful if the linter returns 0-indexed columns
  60     optional param, default: 0
  61 > callback: function to call before executing the linter, if it returns
  62           false the lint is canceled. The callback is passed the buf.
  63     optional param, default: nil
  64
  65 Below is an example for including a linter for any filetype using
  66 the `misspell` linter which checks for misspelled words in a file.
  67
  68 ```lua
  69 function init()
  70     -- uses the default linter plugin
  71     -- matches any filetype
  72     linter.makeLinter("misspell", "", "misspell", {"%f"}, "%f:%l:%c: %m", {}, false, true)
  73 end
  74 ```
  75
  76 Here is an example for a more typical use-case, where the linter will only match one filetype (C in this case):
  77
  78 ```lua
  79 function init()
  80     linter.makeLinter("gcc", "c", "gcc", {"-fsyntax-only", "-Wall", "-Wextra", "%f"}, "%f:%l:%c:.+: %m")
  81 end
  82 ```