feat(lsp)!: pass entire entry to format function (#34166)

* feat(lsp)!: pass entire entry to format function

* refactor(lsp): deprecate `vim.lsp.log.should_log()`

runtime/doc/deprecated.txt

@@ -33,6 +33,8 @@ LSP
 • *vim.lsp.client_is_stopped()*		Use |vim.lsp.get_client_by_id()| instead.
 • *vim.lsp.util.stylize_markdown()*	Use |vim.treesitter.start()| with
 					`vim.wo.conceallevel = 2`.
+• *vim.lsp.log.should_log()*		Use |vim.lsp.log.set_format_func()| instead
+					and return `nil` to omit entries from the logfile.
 
 LUA
 

runtime/doc/lsp.txt

@@ -2656,11 +2656,13 @@ get_level()                                          *vim.lsp.log.get_level()*
         (`integer`) current log level
 
 set_format_func({handle})                      *vim.lsp.log.set_format_func()*
-    Sets formatting function used to format logs
+    Sets the formatting function used to format logs. If the formatting
+    function returns nil, the entry won't be written to the log file.
 
     Parameters: ~
-      • {handle}  (`function`) function to apply to logging arguments, pass
-                  vim.inspect for multi-line formatting
+      • {handle}  (`fun(level:string, ...): string?`) Function to apply to log
+                  entries. The default will log the level, date, source and
+                  line number of the caller, followed by the arguments.
 
 set_level({level})                                   *vim.lsp.log.set_level()*
     Sets the current log level.
@@ -2668,15 +2670,6 @@ set_level({level})                                   *vim.lsp.log.set_level()*
     Parameters: ~
       • {level}  (`string|integer`) One of |vim.log.levels|
 
-should_log({level})                                 *vim.lsp.log.should_log()*
-    Checks whether the level is sufficient for logging.
-
-    Parameters: ~
-      • {level}  (`integer`) log level
-
-    Return: ~
-        (`boolean`) true if would log, false if not
-
 
 ==============================================================================
 Lua module: vim.lsp.rpc                                              *lsp-rpc*

runtime/doc/news.txt

@@ -71,6 +71,8 @@ HIGHLIGHTS
 LSP
 
 • `root_markers` in |vim.lsp.Config| can now be ordered by priority.
+• The function set with |vim.lsp.log.set_format_func()| is now given all
+  arguments corresponding to a log entry instead of the individual arguments.
 
 LUA
 

runtime/lua/vim/lsp/log.lua

@@ -39,8 +39,28 @@ local current_log_level = log_levels.WARN
 
 local log_date_format = '%F %H:%M:%S'
 
-local function format_func(arg)
-  return vim.inspect(arg, { newline = ' ', indent = '' })
+--- Default formatting function.
+--- @param level? string
+local function format_func(level, ...)
+  if log_levels[level] < current_log_level then
+    return nil
+  end
+
+  local info = debug.getinfo(2, 'Sl')
+  local header = string.format(
+    '[%s][%s] %s:%s',
+    level,
+    os.date(log_date_format),
+    info.short_src,
+    info.currentline
+  )
+  local parts = { header }
+  local argc = select('#', ...)
+  for i = 1, argc do
+    local arg = select(i, ...)
+    table.insert(parts, arg == nil and 'nil' or vim.inspect(arg, { newline = ' ', indent = '' }))
+  end
+  return table.concat(parts, '\t') .. '\n'
 end
 
 local function notify(msg, level)
@@ -116,13 +136,9 @@ for level, levelnr in pairs(log_levels) do
 end
 
 --- @param level string
---- @param levelnr integer
 --- @return fun(...:any): boolean?
-local function create_logger(level, levelnr)
+local function create_logger(level)
   return function(...)
-    if not log.should_log(levelnr) then
-      return false
-    end
     local argc = select('#', ...)
     if argc == 0 then
       return true
@@ -130,22 +146,12 @@ local function create_logger(level, levelnr)
     if not open_logfile() then
       return false
     end
-    local info = debug.getinfo(2, 'Sl')
-    local header = string.format(
-      '[%s][%s] %s:%s',
-      level,
-      os.date(log_date_format),
-      info.short_src,
-      info.currentline
-    )
-    local parts = { header }
-    for i = 1, argc do
-      local arg = select(i, ...)
-      table.insert(parts, arg == nil and 'nil' or format_func(arg))
+    local message = format_func(level, ...)
+    if message then
+      assert(logfile)
+      logfile:write(message)
+      logfile:flush()
     end
-    assert(logfile)
-    logfile:write(table.concat(parts, '\t'), '\n')
-    logfile:flush()
   end
 end
 
@@ -154,19 +160,19 @@ end
 -- log at that level (if applicable, it is checked either way).
 
 --- @nodoc
-log.debug = create_logger('DEBUG', log_levels.DEBUG)
+log.debug = create_logger('DEBUG')
 
 --- @nodoc
-log.error = create_logger('ERROR', log_levels.ERROR)
+log.error = create_logger('ERROR')
 
 --- @nodoc
-log.info = create_logger('INFO', log_levels.INFO)
+log.info = create_logger('INFO')
 
 --- @nodoc
-log.trace = create_logger('TRACE', log_levels.TRACE)
+log.trace = create_logger('TRACE')
 
 --- @nodoc
-log.warn = create_logger('WARN', log_levels.WARN)
+log.warn = create_logger('WARN')
 
 --- Sets the current log level.
 ---@param level (string|integer) One of |vim.log.levels|
@@ -188,8 +194,10 @@ function log.get_level()
   return current_log_level
 end
 
---- Sets formatting function used to format logs
----@param handle function function to apply to logging arguments, pass vim.inspect for multi-line formatting
+--- Sets the formatting function used to format logs. If the formatting function returns nil, the entry won't
+--- be written to the log file.
+---@param handle fun(level:string, ...): string? Function to apply to log entries. The default will log the level,
+---date, source and line number of the caller, followed by the arguments.
 function log.set_format_func(handle)
   vim.validate('handle', handle, function(h)
     return type(h) == 'function' or h == vim.inspect
@@ -199,9 +207,12 @@ function log.set_format_func(handle)
 end
 
 --- Checks whether the level is sufficient for logging.
+---@deprecated
 ---@param level integer log level
 ---@return boolean : true if would log, false if not
 function log.should_log(level)
+  vim.deprecate('vim.lsp.log.should_log', 'vim.lsp.log.set_format_func', '0.13')
+
   vim.validate('level', level, 'number')
 
   return level >= current_log_level