From 212dcd0bf753f08c0127a26a71b673c734b45c02 Mon Sep 17 00:00:00 2001 From: Yaroslav Date: Thu, 5 Sep 2019 19:35:38 +0300 Subject: init commit, extracted vim config from i3rice --- .vim/doc/neomake.txt | 1052 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1052 insertions(+) create mode 100644 .vim/doc/neomake.txt (limited to '.vim/doc/neomake.txt') diff --git a/.vim/doc/neomake.txt b/.vim/doc/neomake.txt new file mode 100644 index 0000000..77622a3 --- /dev/null +++ b/.vim/doc/neomake.txt @@ -0,0 +1,1052 @@ +*neomake.txt* - asynchronous make for Vim version 7.4+ and Neovim + + ███╗ ██╗███████╗ ██████╗ ███╗ ███╗ █████╗ ██╗ ██╗███████╗ + ████╗ ██║██╔════╝██╔═══██╗████╗ ████║██╔══██╗██║ ██╔╝██╔════╝ + ██╔██╗ ██║█████╗ ██║ ██║██╔████╔██║███████║█████╔╝ █████╗ + ██║╚██╗██║██╔══╝ ██║ ██║██║╚██╔╝██║██╔══██║██╔═██╗ ██╔══╝ + ██║ ╚████║███████╗╚██████╔╝██║ ╚═╝ ██║██║ ██║██║ ██╗███████╗ + ╚═╝ ╚═══╝╚══════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝ + + Run make tasks (such as linters and build tools) asynchronously. + +============================================================================== +CONTENTS *neomake* + + 1. Introduction ............................... |neomake-introduction| + 2. Commands ....................................... |neomake-commands| + 3. Configuration ............................. |neomake-configuration| + 3.1. Automake ..................................... |neomake-automake| + 4. Functions ..................................... |neomake-functions| + 5. Autocommands/Hooks ............................. |neomake-autocmds| + 6. Frequently Asked Questions (FAQ) .................... |neomake-faq| + +============================================================================== +1. Introduction *neomake-introduction* + +Neomake leverages Neovim's or Vim's |job-control| feature where available to +run programs like syntax checkers asynchronously. Where job control is not +available, it resorts to a synchronous |system()| call, making it possible to +run this plugin in both older Vims and Neovim. +This plugin is heavily inspired by Vim plugins such as Syntastic and +dispatch. + +============================================================================== +2. Commands *neomake-commands* + + *:Neomake* + *:NeomakeFile* +:Neomake [makers] Run a make command with the current file as input. If + no makers are specified, the default makers for the + current |filetype| are used. See + |neomake-configuration| for more on makers. + + *:Neomake!* + *:NeomakeProject* +:Neomake! [makers] Run a make command with no file as input. If no makers + are specified, the default top-level makers will be + used. If no default top-level makers exist, + |'makeprg'| will be used. + + *:NeomakeSh* +:NeomakeSh {command} Run {command} in a shell (according to 'shell'). The + command output will be loaded into the quickfix list + when the job is complete. Example: > + :NeomakeSh find . -name '*.pyc' +< + *:NeomakeSh!* +:NeomakeSh! {command} Same as |:NeomakeSh|, but does not buffer the output. + Example: > + :NeomakeSh! while true; do date; sleep 1; done +< + *:NeomakeInfo* +:NeomakeInfo Display information, meant for debugging and inclusion + in bug reports / help requests. + + *:NeomakeListJobs* +:NeomakeListJobs List all running jobs in the format: > + job_id job_name +< + *:NeomakeCancelJob* +:NeomakeCancelJob {job_id} + Terminate a job identified by its job_id. + + *:NeomakeCancelJobs* +:NeomakeCancelJobs + Terminate all jobs. + + *:NeomakeClean* + *:NeomakeClean!* +:NeomakeClean[!] + Clean signs, highlights etc. for file-mode, or + project-mode (with bang). + +============================================================================== +2.1. Toggle commands *neomake-toggle* + +The following commands enable, disable or toggle Neomake globally, per tab or +per buffer by changing the `disabled` setting, which gets checked when Neomake +gets called via autocommands, e.g. with |neomake-automake| or custom +autocommands. You can still call e.g. |:Neomake| manually, and it will run. +In verbose mode (e.g. when called with |:verbose| (`:verb Neomake`)) the new +status gets displayed. + +*:NeomakeToggle* toggles Neomake globally. +*:NeomakeToggleBuffer* toggles Neomake for the current buffer. +*:NeomakeToggleTab* toggles Neomake for the current tab. + *neomake-disable* +*:NeomakeDisable* disables Neomake globally. +*:NeomakeDisableBuffer* disables Neomake for the current buffer. +*:NeomakeDisableTab* disables Neomake for the current tab. + *neomake-enable* +*:NeomakeEnable* enables Neomake globally. +*:NeomakeEnableBuffer* enables Neomake for the current buffer. +*:NeomakeEnableTab* enables Neomake for the current tab. + +*:NeomakeStatus* displays the current status. + +============================================================================== +3. Configuration *neomake-configuration* + +If you just want an easy way to run |:make| asynchronously, you're all set. +Just set your |'makeprg'| and |'errorformat'| as usual, and run |:Neomake!|. +If you want more, read on. + +3.1 Automaking *neomake-automake* + +To configure Neomake to automatically run on certain events you can use +`neomake#configure#automake()`. + +The first argument can either be a dictionary (mapping autocommand event +names to config dicts for fine grained control), or a string (as a shortcut to +configure certain modes). The 2nd argument is the default delay to use. + +String usage (simple setup):~ + + n: normal mode~ + This uses the |TextChanged| (falling back to |CursorHold|) and |InsertLeave| + events. + + i: insert mode~ + This uses the |TextChangedI| event (falling back to |CursorHoldI|). + + r: "read" mode - when a buffer gets read/open~ + This will hook into the |BufWinEnter|, |FileType| and |FileChangedShellPost| + events. + + w: "write" mode - when a buffer gets written~ + This uses the |BufWritePost| event, with an explicit timeout of 0. + +Examples: > + + " When writing a buffer. + call neomake#configure#automake('w') + " When writing a buffer, and on normal mode changes (after 750ms). + call neomake#configure#automake('nw', 750) + " When reading a buffer (after 1s), and when writing. + call neomake#configure#automake('rw', 1000) + +Dictionary usage (advanced setup):~ +> + call neomake#configure#automake({ + \ 'TextChanged': {}, + \ 'InsertLeave': {}, + \ 'BufWritePost': {'delay': 0}, + \ 'BufWinEnter': {}, + \ }, 500) +< +This will trigger Neomake on |TextChanged|, |InsertLeave|, |BufWritePost| and +|BufWinEnter|, with a delay of 500ms by default, but 0 for |BufWritePost|. + +You could do some advanced setup, based on if your laptop is running on +battery: > + function! MyOnBattery() + return readfile('/sys/class/power_supply/AC/online') == ['0'] + endfunction + if MyOnBattery() + call neomake#configure#automake('w') + else + call neomake#configure#automake('nrw', 1000) + endif +< + *neomake-automake-dynamic-delay* +The automake delay gets adjusted dynamically when timers or make runs get +aborted. This is meant to support the use case where you are doing multiple +changes in succession (e.g. |undo|). +This can be controlled with the experimental `automake.cancelation_delay` +setting, which has to be a list: > + call neomake#configure('automake.cancelation_delay', [0.2, 0.5, 3000]) +> +The first value gets multiplied with the number of restarted timers (before a +make was triggered). +The second value gets multiplied with canceled/restarted make runs. +The sum of those values plus 1 gets multiplied with the original/configured +delay. The third value is used as a maximum. +With the default settings from above this means that given a default delay of +500ms, 7 restarted timer, and 1 restarted make run, it would use a delay of +`(7*0.2 + 1*0.5 + 1) * 500 = 1450`. +The counts for restarted timers and make runs gets reset once a make run +finishes. + +Makers *neomake-makers* +A maker is an object that tells Neomake how to run a job for you. + + *neomake-makers-get_list_entries* +If a maker has a `get_list_entries` function, this gets used to retrieve +entries for the location or quickfix list directly. +The function gets passed a jobinfo (|neomake-object-jobinfo|) object, and +should return a list of entries that will be used to fill the +location/quickfix list: > + let maker = {'name': 'My maker'} + function! maker.get_list_entries(jobinfo) abort + return [ + \ {'text': 'Some error', 'lnum': 1, 'bufnr': a:jobinfo.bufnr}, + \ {'text': 'Some warning', 'type': 'W', 'lnum': 2, 'col': 1, + \ 'length': 5, 'filename': '/path/to/file'}, + \ ] + endfunction +< +The required keys for entries are `text` and `lnum`, and you should set one of +`bufnr` or `filename` (otherwise the entry will not be valid). +The `length` entry in the example is internal to Neomake, and sets the length +for an highlight (see |neomake-highlight|). + + *neomake-job-makers* +Otherwise a maker gets run as a job with a file as input ("file mode", good +for linting), or with no file as input ("project mode", good for building and +project-level tasks). + +Here is a sample maker definition: > + let g:neomake_make_maker = { + \ 'exe': 'make', + \ 'args': ['--build'], + \ 'errorformat': '%f:%l:%c: %m', + \ } + " Use the maker like this: + :Neomake! make +< + *neomake-makers-InitForJob* +You can configure a maker dynamically through a `InitForJob` function, which +gets the jobinfo (|neomake-object-jobinfo|) as its argument. + +This can also be configured as setting: > + function! CustomExe(jobinfo) abort + let self.args = [self.exe] + self.args + let self.exe = 'some_custom_wrapper' + endfunction + call neomake#config#set('ft.python.InitForJob', function('CustomExe')) +< + *neomake-makers-exe* + *neomake-makers-args* +`exe` has to be a string, while `args` can be a list or a string. +If `args` is a list, entries like '%' and '%:p' will be |expand()|ed, and +quoting/escaping is applied automatically. If you want to handle escaping +yourself, `args` should be a string. + +In the above example, the exe argument isn't strictly necessary, since Neomake +uses the name of the maker as the default value for it. If you want it to be +usable on an individual file, you should also include the filetype in the +name: > + let g:neomake_c_lint_maker = { + \ 'exe': 'lint', + \ 'args': ['--option', 'x'], + \ 'errorformat': '%f:%l:%c: %m', + \ } + + " Run this maker for the open file (runs "lint --option x myfile.c"): + :Neomake lint + + " Or run it on the whole project, executing the command from Vim's current + " working directory (runs "lint --option x"): + :Neomake! c_lint +< + *neomake-args-file* +When running a maker on a file with |:Neomake|, you may want to control where +in the `args` list the file's path will appear. To do this, insert '%t' in +the `args` list and use `append_file=0`: > + let g:neomake_c_lint_maker = { + \ 'exe': 'lint', + \ 'args': ['%t', '--option', 'x'], + \ 'append_file': 0, + \ 'errorformat': '%f:%l:%c: %m', + \ } +< +This will cause "lint /path/to/file.c --option x" to be run instead of +"lint --option x /path/to/file.c". + +`%t` gets replaced with the absolute path to the file (handling any temporary +file). + + *neomake-makers-processing* +A job maker's output gets processed in two ways: +1. through a maker's `process_output` function, or +2. via its `errorformat` (together with `mapexpr` and `postprocess`). + + *neomake-makers-process_output* +If a maker has a `process_output` function, this gets used to retrieve +entries for the location or quickfix list for the job's output directly. + +The function gets called with a `context` dictionary, with the following +entries: + - `output`: a list of lines + - `source`: the source of the output (`stderr`, `stdout`) + - `jobinfo`: the jobinfo object, see |neomake-object-jobinfo| +It should return a list of entries (dictionaries), where `text` and `lnum` +are required. `bufnr` defaults to the jobs's buffer. + +Using this method skips the processing based on `errorformat` (including +`mapexpr` and `postprocess`). + +See |neomake-makers-process_json| below for handling JSON output. + + *neomake-makers-process_json* +A maker's `process_json` function gets a |dict| with parsed JSON directly, +handling the JSON parsing and any errors before. + +The function gets called with a `context` dictionary, containing the following +entries: + - `json`: a dictionary with the parsed JSON + - `source`: the source of the output (`stderr`, `stdout`) + - `jobinfo`: the jobinfo object, see |neomake-object-jobinfo| +It should return a list of entries (dictionaries), where `text` and `lnum` +are required. `bufnr` defaults to the jobs's buffer. + +Using this method skips the processing based on `errorformat` (including +`mapexpr` and `postprocess`). + + *neomake-makers-filter_output* +A maker's `filter_output` function can filter any output before it gets +processed further. + +The function gets called with two arguments: the list of lines (to be modified +in place) and a context dictionary with the following entries: + - `source`: the source of the output (`stderr`, `stdout`) + - `jobinfo`: the jobinfo object, see |neomake-object-jobinfo| + + *neomake-makers-mapexpr* +You can define two optional properties on a maker object to process its +output: `mapexpr` is applied to the maker's output before any processing, and +`postprocess` is applied to each of the quickfix or location list entries. + +The `mapexpr` property gets passed directly into |map()| as the `expr` +argument: > + call map(lines, maker.mapexpr) + + "printf('[%s] %s', neomake_output_source, v:val)" +< + *neomake-makers-postprocess* +The `postprocess` property is a function (or list of functions) that get(s) +called for each entry in the location or quickfix list. +It allows to change entries there or remove them by setting the `valid` entry +to `-1`. + +Example: make all entries a warning where `nr` is in the range of 100-199: > + function PostprocessLintMaker(entry) + if a:entry.nr >= 100 && a:entry.nr < 200 + let a:entry.type = 'W' + endif + endfunction + let g:neomake_ft_lint_maker = { + \ 'exe': 'lint', + \ 'args': ['--option', 'x'], + \ 'errorformat': '%f:%l:%c:%n: %m', + \ 'postprocess': function('PostprocessLintMaker') + \ } +< +Example: remove some entry for a specific maker (using |expr-lambda|): > + let g:neomake_asciidoc_asciidoc_postprocess = { + \ entry -> entry.text =~# 'illegal system attribute name: font-style' + \ ? extend(entry, {'valid': -1}) + \ : entry} +< + +Builtin postprocessors are `neomake#postprocess#compress_whitespace`, which +fixes whitespace issues (which is useful with multiline error messages), +and `neomake#postprocess#generic_length`, which adds a length property (used +for highlights |neomake-highlight|) for entries, when the message refers to an +identifier at the entry's column. +See `neomake#makers#ft#text#PostprocessWritegood` for an example. + +Entries can be selectively removed in post-processing by setting its "valid" +property to `-1`. This removal will happen even if `remove_invalid_entries` +is disabled. This feature is meant for conditional removals and a simpler way +for end users to filter list entries. Makers should handle removals through +|errorformat| using '%-G' to remove items that should never appear in the +error list. + + *neomake-makers-buffer_output* +Default: 1 +By default Neomake will only process the output from makers when either the +output type changes (from stderr to stdout or vice versa), or at the end of +the job. + +If you have a maker that is expected to run longer, and you want to get +feedback as early as possible, you can set this to `0`. + +You can override this for a maker using e.g.: > + let g:neomake_ft_test_maker_buffer_output = 0 +< +Your results will appear earlier, but if the |'errorformat'| is meant to parse +multiline output this will likely cause issues (depending on how the maker +flushes its output). + +To change the default for all makers use: > + call neomake#config#set('maker_defaults.buffer_output', 0) +< + *neomake-makers-remove_invalid_entries* +Default: 0 +This option filters invalid entries from makers from the location/quickfix +list (i.e. entries that do not match the |'errorformat'|, and that would show +up with a `||` prefix in the location/quickfix list): > + let g:neomake_ft_maker_remove_invalid_entries = 1 +< +NOTE: the default for this is 0, because unhandled/unexpected output might be +useful, e.g. when the program displays some error. +Makers should handle this properly through |errorformat|, e.g. by using '%-G' +(see |efm-ignore| and |neomake-faq-errorformat|). + +To change the default for all makers use: > + call neomake#config#set('maker_defaults.remove_invalid_entries, 1) +< + *neomake-makers-cwd* +The working directory of a maker defaults to the current working directory +of the make run (|getcwd()|). +The `cwd` property overrides this, and gets expanded in the context of the +current buffer. Special buffers (like fugitive blobs) get handled for values +starting with `%:` (typically used in this context), falling back to +|expand()|. See |filename-modifiers|. + > +Example: change to the buffer's directory: > + let g:neomake_my_example_maker = { + \ 'exe': 'pwd', + \ 'cwd': '%:p:h' + \ } +< + *neomake-makers-tempfile_enabled* +Default: 1 +This will pass a temporary file with the buffer's contents to the maker, in +case the buffer is not readable, modified, or has no filename. +A maker can specify the temporary file's name through the `tempfile_name` +property, and you can set it through the |neomake-makers-InitForJob| callback +(for advanced usage). +Otherwise it gets generated based on the original filename/filetype, and +falls back to using |tempname()|. + +You can configure this per buffer or maker as usual, e.g.: > + let g:neomake___tempfile_enabled = 0 +< + *neomake-makers-tempfile_dir* +Default: unset +You can configure the directory to use for temporary files (see +|neomake-makers-tempfile_enabled|). + +The default behavior is to use the same directory as the original file, so +that any config files (e.g. `setup.cfg` for Python tools) take effect. + +You can configure this per buffer or maker as usual, e.g.: > + let g:neomake___tempfile_dir = '/tmp/custom' +< +The value gets expanded (via `neomake#utils#ExpandArgs`), which allows for +the following to use the original file's directory structure (`%:p:h`): > + let g:neomake_tempfile_dir = '/tmp/custom%:p:h' +< + *neomake-makers-output_stream* +Default: "both" ("stdout", "stderr", "both") +The `output_stream` setting specifies what stream gets used for output from +the maker. +Any output on a stream not configured here gets reported as unexpected output. + + *neomake-makers-supports_stdin* +Default: 0 +With `supports_stdin = 1` a maker indicates that it can use stdin instead of a +temporary file. By default "-" is then used for the filename. + +`supports_stdin` can be a dict function on the maker, which will get the +current jobinfo as its argument, and should return 1 or 0. +This function can change `self.args`, which is useful to append options like +e.g. "['--stdin-display-name', '%:p']". +You can also change `self.tempfile_name` therein. +It can be useful to change the current working directory for the maker here, +e.g. when it does not use its `--stdin-display-name` (or similar) option +to look for its config. Use the jobinfo's `cd` method for this: > + function! maker.supports_stdin(jobinfo) abort + let self.args += ['--stdin-display-name', '%:.'] + call a:jobinfo.cd('%:h') + return 1 + endfunction +< + *neomake-makers-uses_stdin* +Default: 0 +`uses_stdin = 1` can be used to always use stdin for file arguments, +regardless of if a temporary file / stdin is required to be used. +It uses "-" as the default for "tempfile_name". + +Global Options *neomake-options* + +*g:neomake__maker* +*g:neomake___maker* +Define a new filetype or project-level maker. See |neomake-makers|. + + *neomake-makers-properties* +*g:neomake__* +*g:neomake___* +*b:neomake__* +*b:neomake___* +Configure properties for a maker where is one of `exe`, `args`, +`errorformat`, `buffer_output`, `remove_invalid_entries`, `append_file`, +or `supports_stdin`. + +This can also be set per buffer, e.g.: > + let g:neomake_javascript_jshint_exe = './myjshint' + let b:neomake_javascript_jshint_exe = './myotherjshint' +< + +The global defaults can be configured using `g:neomake_`, i.e. +*g:neomake_remove_invalid_entries* to remove invalid entries from the quickfix +/ location list (|neomake-makers-remove_invalid_entries|), unless explicitly +provided by the maker or overridden by your global/buffer setting. + +The internal defaults are: > + let defaults = { + \ 'exe': maker.name, + \ 'args': [], + \ 'errorformat': &errorformat, + \ 'buffer_output': 0, + \ 'remove_invalid_entries': 0 + \ } +< + +*g:neomake__enabled_makers* +*b:neomake__enabled_makers* +This setting will tell Neomake which makers to use by default for the given +filetype `` (when called without a maker as an argument, i.e. |:Neomake|). + +The default for this setting is the return value of the function +`neomake#makers#ft##EnabledMakers`. For Python this is defined in +`./autoload/neomake/makers/ft/python.vim`, and might return: > + ['python', 'frosted', 'pylama'] +< +This setting can also be defined per buffer, so the following snippet can be +used to configure a custom set of makers from your vimrc: > + let g:neomake_python_enabled_makers = ['pep8', 'pylint'] + augroup my_custom_maker + au! + au Filetype custom.py let b:neomake_python_enabled_makers = ['flake8'] + augroup END +< +Please refer to |autocmd-patterns| for help on defining the pattern +(`custom.py`) in this case. + +*g:neomake_enabled_makers* +*b:neomake_enabled_makers* +This setting will tell Neomake which makers to use by default when not +operating on a single file, or when no makers are defined for the filetype of +the current buffer. This effectively defaults to: > + let g:neomake_enabled_makers = ['makeprg'] +< +*g:neomake_open_list* +*b:neomake_open_list* +This setting will open the |location-list| or |quickfix| list (depending on +whether it is operating on a file) when adding entries. A value of 2 will +preserve the cursor position when the |location-list| or |quickfix| window is +opened. Defaults to 0. + +*g:neomake_list_height* +*b:neomake_list_height* +The maximum height of the |location-list| or |quickfix| list window opened by +Neomake. If there are fewer entries it will use that instead. +Defaults to 10. + +*g:neomake_echo_current_error* +This setting will |:echo| the error for the line your cursor is on, if any. +It uses a timer (if |timers| are available), and |CursorHold|/|CursorHoldI| +otherwise. +Defaults to 1. + +*g:neomake_virtualtext_current_error* +Use Neovim's virtualtext API to display the error for the current line next +to the text. This is experimental, and uses the same mechanism (timer) +as |g:neomake_echo_current_error|. +Defaults to 1 (only available on Neovim 0.3.2+). + +*g:neomake_virtualtext_prefix* +The prefix used with |g:neomake_virtualtext_current_error|. +Defaults to "❯ ". + +*g:neomake_cursormoved_delay* +Delay (in ms) for the timer used to echo the current error with +|g:neomake_echo_current_error|. +Defaults to 100. + +*g:neomake_serialize* +Setting this to 1 tells Neomake to run each enabled maker one after the other. +This is a good way to ensure messages don't get mixed up. This setting is +implied with non-async Vim versions. + +*g:neomake_serialize_abort_on_error* +Setting this to 1 tells Neomake to abort after the first error status is +encountered. This setting only works when |g:neomake_serialize| is on. + +*g:neomake_verbose* +Controls how verbose Neomake should be. Neomake log levels are as follows: + 0 - Errors only + 1 - Quiet message + 2 - Loud message (may log multiple messages at once, making the screen + shift momentarily) + 3 - Debug information (all messages). + This will also add time information to messages. +Each log level includes all the levels before it. + +Defaults to 1. + +|'verbose'| gets added to this setting, so you can use |:verbose| to increase +the verbosity temporarily: > + :3verb Neomake +< +*g:neomake_logfile* +Setting this to a file path will write all messages (regardless of the level +configured through |g:neomake_verbose|) into it. +This is useful for debugging/hacking, and when reporting issues. +It requires Vim 7.4.503+ (or Neovim) to work properly, otherwise it will not +append, but overwrite the file with each message. + + *neomake-signs* +*g:neomake_place_signs* +This setting enables the placement of signs next to items from the location +and quickfix list (i.e. errors/warnings etc recognized from the +|'errorformat'|). Defaults to 1. + +*g:neomake_error_sign* +*g:neomake_warning_sign* +*g:neomake_info_sign* +*g:neomake_message_sign* +These options allow you to control the appearance of the signs that are +placed into the |signs| column next to lines with messages. +These are dictionaries that represent the parameters provided by +|:sign-define|. Here is an example definition: > + let g:neomake_error_sign = { + \ 'text': 'E>', + \ 'texthl': 'ErrorMsg', + \ } +< +See the |:highlight| command to list the highlight groups available to you or +create new ones. + +Neomake uses the following defaults: > + + let g:neomake_error_sign = { + \ 'text': '✖', + \ 'texthl': 'NeomakeErrorSign', + \ } + let g:neomake_warning_sign = { + \ 'text': '‼', + \ 'texthl': 'NeomakeWarningSign', + \ } + let g:neomake_message_sign = { + \ 'text': '➤', + \ 'texthl': 'NeomakeMessageSign', + \ } + let g:neomake_info_sign = { + \ 'text': 'ℹ', + \ 'texthl': 'NeomakeInfoSign' + \ } +< + +Default |highlight-groups| are created with those names, but only if they do +not exist already, which allows you to customize them. This should typically +be done through the |ColorScheme| autoevent, which applies it after any color +scheme: > + + augroup my_neomake_signs + au! + autocmd ColorScheme * + \ hi NeomakeErrorSign ctermfg=white | + \ hi NeomakeWarningSign ctermfg=yellow + augroup END +< +You can use `neomake#utils#GetHighlight` to get e.g. the "bg" from +"SignColumn". See `neomake#signs#DefineHighlights` where this is used. + + *neomake-highlight* +*g:neomake_highlight_columns* +This setting enables highlighting of columns for items from the location and +quickfix list. Defaults to 1. + +*g:neomake_highlight_lines* +This setting enables highlighting of lines for items from the location and +quickfix list. Defaults to 0. + +If both |g:neomake_highlight_columns| and |g:neomake_highlight_lines| are +enabled, items with column information are highlighted using the column. + +The following highlighting groups are used: + - NeomakeError: links to "SpellBad" (|hl-SpellBad|) + - NeomakeWarning: links to "SpellCap" (|hl-SpellCap|) + - NeomakeInfo: links to "NeomakeWarning" + - NeomakeMessage: links to "NeomakeWarning" + +You can define them yourself: > + + augroup my_neomake_highlights + au! + autocmd ColorScheme * + \ highlight NeomakeError … | + \ highlight NeomakeWarning … + guisp=White + augroup END +> + +*g:airline#extensions#neomake#enabled* +Shows warning and error counts returned by |neomake#statusline#LoclistCounts| +in the warning and error sections of the vim-airline |'statusline'|. Defaults +to 1. + +============================================================================== +4. Functions *neomake-functions* + +This list is non-exhaustive at the moment, but you may find some of these +functions useful. + +*neomake#Make* (options) +This is the main entrypoint to Neomake, used by the |:Neomake| (and +|:Neomake!|) command. + +`options` is a dictionary, and might include: +- `file_mode`: 1 if the makers should get run against a single file (typically + used for linting). Default: 1. +- `enabled_makers`: the makers to use (list). Default: uses configuration. + +Returns: a list of jobinfo objects (|neomake-object-jobinfo|). + +Deprecated interface (with different return value)~ +The old and deprecated API will accept the following arguments instead of the +`options` dict: filemode, enabled_makers[, exit_callback]. +The `exit_callback` (which should get replaced by using the +|NeomakeJobFinished| or |NeomakeFinished| hooks) gets the following dictionary +as its sole argument: > + { 'status': , + \ 'name': , + \ 'has_next': <1 if another maker follows, 0 otherwise> } +Returns: a list of job ids. + +*neomake#Sh* (command[, callback]) +This function is called by the |:NeomakeSh| command. It runs the specified +shell `command` according to 'shell'. |neomake#Sh| returns the single job id +that was created (-1 on Vim without asynchronous support); you can potentially +cancel this job with |neomake#CancelJob|. + +It also accepts a second, optional callback argument that is called when +the command exits. The callback is given the following dictionary as its +sole argument: > + { 'status': , + \ 'name': 'sh: ', + \ 'has_next': 0 } +< +The callback will receive a `jobinfo` object dict as `self` +(|dict-functions|). + +*neomake#ListJobs* +Invoked via |:NeomakeListJobs|. Echoes a list of running jobs in the format +(job_id, job_name). + +*neomake#CancelJob* +Invoked via |:NeomakeCancelJob|. Terminate a job identified by its job_id. +Example: > + let job_id = neomake#Sh("bash -c 'while true; do sleep 1; done'") + call neomake#CancelJob(job_id) + +*neomake#signs#RedefineErrorSign* +*neomake#signs#RedefineWarningSign* +These functions define the error sign and the warning sign respectively. They +optionally take a dictionary in the same format as |g:neomake_error_sign|. If +no such dictionary is provided, the default values will be used. These +functions may be useful if somehow |:Neomake| is being invoked before you +define |g:neomake_error_sign|. > + let g:neomake_error_sign = {'text': 'D:'} + call neomake#signs#RedefineErrorSign() +< + *neomake-statusline* +The main function for statusline integration is `neomake#statusline#get()`, +which caches the information retrieved from `neomake#statusline#get_status()`. + +*neomake#statusline#get()* [options] +The function requires the buffer number as first argument, and an optional +dictionary. You might want to use |g:actual_curbuf| for bufnr, if calling +`neomake#status#get()` from a statusline expression, but then highlights are +not evaluated, and you typically want to use this in a statusline function +(`'set statusline=%!MyStatusLine()'`) instead. + +Returns a string for a 'statusline'. + +The optional argument is a dictionary of options (see below). + +The following example creates a custom 'statusline' function, where `a:active` +may reflect if the window is the current one (implementation not provided): > + let neomake_status_str = neomake#statusline#get(bufnr, { + \ 'format_running': '… ({{running_job_names}})', + \ 'format_loclist_ok': + \ (a:active ? '%#NeomakeStatusGood#' : '%*').'✓', + \ 'format_quickfix_ok': '', + \ 'format_quickfix_issues': (a:active ? '%s' : ''), + \ 'format_status': '%%(%s' + \ .(a:active ? '%%#StatColorHi2#' : '%%*') + \ .'%%)', + \ }) +< +A simpler example: > + let neomake_status_str = neomake#statusline#get(bufnr, { + \ 'format_running': '… ({{running_job_names}})', + \ 'format_loclist_ok': '✓', + \ 'format_quickfix_ok': '', + \ 'format_quickfix_issues': '%s', + \ }) +< +You can use the following options: + +For location list items:~ + - format_loclist_unknown: format for when the status for location list + issues is unknown, i.e. Neomake was not run on the current buffer. + Default: `'?'` + - format_loclist_ok: format for when there are no location list issues. + Default: `'%#NeomakeStatusGood#✓%#NeomakeStatReset#'` (a checkmark using + the NeomakeStatusGood highlight group). + - format_loclist_type_X: format for location list issues of type X + (E, W, I, …). + Default: looks up "format_loclist_type_default" first, and then uses + `' {{type}}:{{count}} '`, with an existing highlight group as prefix + ("NeomakeStatColorTypeX" or "NeomakeStatColorDefault"), e.g. + - format_loclist_type_default: default format for location list issues if + "format_loclist_type_X" is not defined. + - format_loclist_issues: format for wrapping all location list issues. + Default: `'%s%%#NeomakeStatReset'` (used with |printf()|). + +For quickfix list items:~ + - format_quickfix_ok: format for no quickfix issues. + Default: `''` + - format_quickfix_type_X: format for quickfix list issues of type X + (E, W, I, …). + Default: `' {{type}}:{{count}} '` + Default: looks up "format_quickfix_type_default" first, and then uses + `' Q{{type}}:{{count}} '`, with an existing highlight group as prefix + ("NeomakeStatColorQuickfixTypeX" or "NeomakeStatColorQuickfixDefault"). + - format_quickfix_issues: format for wrapping all quickfix list issues. + You can use an empty string to skip displaying quickfix issues, which can + be useful for non-current windows. + Default: `'%s%%#NeomakeStatReset'` (used with |printf()|). + +Status related:~ + - format_status: used to wrap the whole status. + This is a |printf()| format string, where `%s` gets replaced with the + whole status (and any literal/non-printf `%` needs to be escaped as `%%`). + Default: not used / `'%s'` + - format_status_disabled: used to wrap the whole status when disabled. + This is a |printf()| format string, where `%s` gets replaced with the + whole status (and any literal/non-printf `%` needs to be escaped as `%%`). + Default: `'{{disabled_info}} %s'` + - format_disabled_info: The `disabled_info` placeholder from the + "format_status_disabled" argument. There `disabled_scope` placeholder is + available here. Default: `'{{disabled_scope}}-'` + - format_status_enabled: used to wrap the whole status when enabled. + This is a |printf()| format string, where `%s` gets replaced with the + whole status (and any literal/non-printf `%` needs to be escaped as `%%`). + Default: not used / `'%s'` + +General:~ + - format_lists: used to format the overall location list and quickfix list + sections (before format_status). + `{{lists_sep}}` is empty ("") with only a single list section, + and defaults to " " if both are not empty. + Default: `'{{loclist}}{{lists_sep}}{{quickfix}}'` + +Running jobs:~ + If any jobs are currently running in file or project mode, those get + displayed by default in the loclist or quickfix section. The following + options control its appearance: + + - format_running: used in case there are jobs running. Use 0 (as a number) + to disable this, but fall through to the last known status. + Default: `… ({{running_job_names}})` + - format_running_job_file: Wrap the running job name for file-level makers. + Default: not used / `'%s'` + - format_running_job_project: Wrap the running job name for project makers. + Default: `'%s!'`. + - running_jobs_separator: Separator for formatted running job names. + Default: `', '`. + +Advanced options:~ + + - use_highlights_with_defaults: include highlight attributes with default + options (e.g. "%#NeomakeStatusGood#" with "format_loclist_ok"). + Default: 1 + +You can use the following format placeholders: + - `{{running_job_names}}}`: comma-separated list of running jobs (typically + their maker names). + This gets built using `format_running_job_file`, + `format_running_job_project`, and `running_jobs_separator`. + - `{{disabled_scope}}`: When manually overriden, the scope of the disabling. + One of "b", "t", "g". + +*neomake#statusline#LoclistStatus* +*neomake#statusline#QflistStatus* +These functions return text for your |'statusline'|. They each take an +optional first argument, which is the prefix text that will be shown if errors +or warnings exist. Example usage: > + set statusline+=\ %#ErrorMsg#%{neomake#statusline#QflistStatus('qf:\ ')} +< +The result of this will be something like 'qf: E:1, W:2' if there are errors +or warnings and the empty string otherwise. + +*neomake#statusline#LoclistCounts* +*neomake#statusline#QflistCounts* +These functions get the counts of errors by error type for the |location-list| +and the |quickfix| respectively. The return value is something like this: > + {'E': 2, 'W': 1, 'x': 5} + + function! MyOnNeomakeJobFinished() abort + let context = g:neomake_hook_context + if context.jobinfo.exit_code != 0 + echom printf('The job for maker %s exited non-zero: %s', + \ context.jobinfo.maker.name, context.jobinfo.exit_code) + endif + endfunction + augroup my_neomake_hooks + au! + autocmd User NeomakeJobFinished call MyOnNeomakeJobFinished() + augroup END +< +Note: you might want to use |autocmd-nested| (in particular when handling +opening of the location/quickfix window yourself, so that other autocommands +get triggered, e.g. |WinEnter| for the qf window that gets opened/created): > + augroup my_neomake_hooks + au! + autocmd User NeomakeFinished nested call MyOnNeomakeFinished() + augroup END +< + *NeomakeJobInit* +The NeomakeJobInit autocommand gets triggered before a job gets started. +You can use this to change the command (`jobinfo.argv`). +Context: + - `g:neomake_hook_context.jobinfo`: see |neomake-object-jobinfo|. + The `argv` entry contains the command to run (executable and arguments). + This can be a list or a string, depending on the maker and the job backend. + + *NeomakeJobStarted* +The NeomakeJobStarted autocommand gets triggered after a job started. +Context: + - `g:neomake_hook_context.jobinfo`: see |neomake-object-jobinfo|. + + *NeomakeCountsChanged* +The NeomakeCountsChanged user autocommand gets triggered after counts for the +location/quickfix list have changed, either because the list got reset or new +entries got added. +You can use this to e.g. update the statusline. +Context: + - `g:neomake_hook_context.reset`: 1 if the list got reset, 0 otherwise. + - `g:neomake_hook_context.jobinfo`: when the list is not reset; see + |neomake-object-jobinfo|. + + *NeomakeFinished* +The NeomakeFinished user autocommand gets triggered after all jobs of a build +have finished. +You can use this to e.g. close an empty location or quickfix window. +Context: + - `g:neomake_hook_context`: a dictionary with the following keys: + - `make_info`: make info, which contains all of the entries from below, + plus some more. (The object itself is not documented yet) + - `make_id`: the numeric ID of the make run. + - `options`: a dictionary (related to |neomake-object-jobinfo|): + - `file_mode` + - `bufnr` + - `ft` + - `finished_jobs`: a list of job infos (|neomake-object-jobinfo|) for the + finished jobs. + + *NeomakeJobFinished* +The NeomakeJobFinished autocommand gets triggered after a single job has +finished. +Context: + - `g:neomake_hook_context.jobinfo`: see |neomake-object-jobinfo|; `exit_code` + is available there. + +============================================================================== +5. Objects *neomake-objects* + + *neomake-object-jobinfo* +The `jobinfo` dictionary contains information about a job. +(this is experimental, so not everything is documented) + - `maker`: a dictionary containing information about the maker that ran + this job. See |neomake-object-maker|. + - `file_mode`: 1 for file mode, 0 for project/directory mode. + - `make_id`: the ID of the make run + - `get_pid()`: get the process ID (PID) of the job (-1 if not running + anymore). + + - Relevant for file mode: + - `bufnr`: the number of the buffer. + - `ft`: the filetype. + *neomake-object-maker* +The `maker` dictionary contains the following keys: +(this is experimental, so not everything is documented) + - `name`: name of the maker. + - `exe`: executable of the maker. + +============================================================================== +6. Frequently Asked Questions (FAQ) *neomake-faq* + +6.1 Other plugins overwrite the signs placed by Neomake~ + +When using quickfixsigns (https://github.com/tomtom/quickfixsigns_vim/) it +will also place signs for errors and warnings in the quickfix/location list, +and conflicts therefore with Neomake's own signs (see +|g:neomake_place_signs|). You can make quickfixsigns respect Neomake's signs +using this option: > + + let g:quickfixsigns_protect_sign_rx = '^neomake_' +< +6.2 How to configure the makers to be used?~ + +See |g:neomake__enabled_makers| (press `` on the link to go there). + + *neomake-faq-errorformat* +6.3 How to develop/debug the errorformat setting?~ + +Here are some tips to develop the 'errorformat' setting for makers: + +1. Get the output from the linter into a buffer (see also |:read!|). +2. Set the errorformat, e.g. `:let &efm = '%E%f:%l:%c\,%n: %m,%Z%m`. + See |errorformat| for documentation of the format itself. +3. Load the buffer into the quickfix list: `:cgetbuffer`. +4. Use |:copen| to open the quickfix window, and/or `:echo getqflist()` to + display the raw data. +5. Pay attention to the "`valid`" property of entries. + +vim: ft=help tw=78 isk+=<,>,\:,-,' -- cgit v1.2.3