Add user facing function to get tag near line number (#643)

autoload/tagbar.vim

@@ -3515,6 +3515,32 @@ endfunction
 " Autoload functions {{{1
 
 " Wrappers {{{2
+function! tagbar#GetTagNearLine(lnum, ...) abort
+    if a:0 > 0
+        let fmt = a:1
+        let longsig   = a:2 =~# 's'
+        let fullpath  = a:2 =~# 'f'
+        let prototype = a:2 =~# 'p'
+    else
+        let fmt = '%s'
+        let longsig   = 0
+        let fullpath  = 0
+        let prototype = 0
+    endif
+
+    let taginfo = s:GetNearbyTag(0, 1, a:lnum)
+
+    if empty(taginfo)
+        return ''
+    endif
+
+    if prototype
+        return taginfo.getPrototype(1)
+    else
+        return printf(fmt, taginfo.str(longsig, fullpath))
+    endif
+endfunction
+
 function! tagbar#ToggleWindow(...) abort
     let flags = a:0 > 0 ? a:1 : ''
     call s:ToggleWindow(flags)

doc/tagbar.txt

@@ -320,6 +320,24 @@ FUNCTIONS                                                   *tagbar-functions*
     update tag information.  This should be called after you have used
     |tagbar#currenttag| manually.
 
+*tagbar#GetTagNearLine()*
+    Get the current tag near the specified line number (lnum). Optionally
+    takes a fmt and signature specification using the same method as the
+    |tagbar#currenttag()| function. Defaults to GetTagNearLine(lnum, '%s', '').
+
+    This could be used in a custom foldtext function to show the current tag
+    the fold current fold is located in.
+
+    Example:
+   >
+    set foldtext=MyFoldFunc()
+    function! MyFoldFunc()
+        let tag = tagbar#GetTagNearLine(v:foldend, '%s', 'p')
+        let lines = v:foldend - v:foldstart + 1
+        return tag . ' --- ' . lines . ' lines'
+    endfunction
+<
+
 ------------------------------------------------------------------------------
 KEY MAPPINGS                                                     *tagbar-keys*