Add a callback function that will be invoked when changes have been made to buffer {buf}. {buf} refers to a buffer name or number. For the accepted values, see bufname(). When {buf} is omitted the current buffer is used. Returns a unique ID that can be passed to listener_remove().

The {callback} is invoked with five arguments: bufnr the buffer that was changed start first changed line number end first line number below the change added number of lines added, negative if lines were deleted changes a List of items with details about the changes

Example:

func Listener(bufnr, start, end, added, changes)
  echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed'
endfunc
call listener_add('Listener', bufnr)

The List cannot be changed. Each item in "changes" is a dictionary with these entries: lnum the first line number of the change end the first line below the change added number of lines added; negative if lines were deleted col first column in "lnum" that was affected by the change; one if unknown or the whole line was affected; this is a byte index, first character has a value of one. When lines are inserted (not when a line is split, e.g. by typing CR in Insert mode) the values are: lnum line above which the new line is added end equal to "lnum" added number of lines inserted col 1 When lines are deleted the values are: lnum the first deleted line end the line below the first deleted line, before the deletion was done added negative, number of lines deleted col 1 When lines are changed: lnum the first changed line end the line below the last changed line added 0 col first column with a change or 1

The entries are in the order the changes were made, thus the most recent change is at the end. The line numbers are valid when the callback is invoked, but later changes may make them invalid, thus keeping a copy for later might not work.

The {callback} is invoked just before the screen is updated, when listener_flush() is called or when a change is being made that changes the line count in a way it causes a line number in the list of changes to become invalid.

The {callback} is invoked with the text locked, see textlock. If you do need to make changes to the buffer, use a timer to do this later timer_start().

The {callback} is not invoked when the buffer is first loaded. Use the BufReadPost autocmd event to handle the initial text of a buffer. The {callback} is also not invoked when the buffer is unloaded, use the BufUnload autocmd event for that.

Returns zero if {callback} or {buf} is invalid.

Can also be used as a method, the base is passed as the second argument:

GetBuffer()->listener_add(callback)