StlShowFunc.txt Showing Functions in the Status Line Nov 02, 2012
Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM>
(remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2012 by Charles E. Campbell StlShowFunc-copyright
The VIM LICENSE applies to StlShowFunc.vim,
ftplugin/c/StlShowFunc_c.vim, ftplugin/dbg/StlShowFunc_dbg.vim,
ftplugin/matlab/StlShowFunc_m.vim, ftplugin/vim/StlShowFunc_vim.vim,
(see copyright) except use "StlShowFunc and associated functions"
instead of "Vim"
No warranty, express or implied. Use At-Your-Own-Risk.
==============================================================================
1. Contents StlShowFunc StlShowFunc-contents
1. Contents.........................................: StlShowFunc
2. StlShowFunc Manual...............................: StlShowFunc-manual
3. StlShowFunc History..............................: StlShowFunc-history
==============================================================================
2. StlShowFunc Manual StlShowFunc-manual
The StlShowFunc plugin and associated filetype plugins manipulate the
status line to show the name of the function that the cursor is in. In
addition, information on the filename, current line and column, and much
else is also displayed. Note that your current statusline option is
overridden with this plugin, although you can restore it by typing
If you'd like to change the colorization, define highlighting groups User1,
User2, and User3 as you wish. The plugin sets up defaults for them:
An example of the status line:
Currently, the cursor is in the StlShowFunc() in StlShowFunc.vim.
The plugin uses the new (as of vim 7.0) CursorMoved event to trigger a check on
whether or not the cursor has moved from one function to another.
COMMANDS
StlShowFunc [lang] : turn StlShowFunc on for the given language
At this time, currently supported languages
include:
cpp matlab c perl
dbg sh maple vim
StlShowFunc! : turn off StlShowFunc
HOW IT WORKS
Tersely, the StlShowFunc utility modifies the 'statusline' option
to call a function which returns a string based on window number. It also
sets up a CursorMoved event which, whenever the cursor is moved, checks to
see if the enclosing function name has changed and, if it has, sets a
script and window-associated variable to that function name.
Here's an overview of StlShowFunc's components:
plugin/StlShowFunc.vim:
* sets up a CursorMoved autocommand event so that, when the
cursor is moved, a check is made to determine if the containing
function has changed (ShowFuncSetup())
* StlSetFunc(), which assigns a function name to a window by changing
the 'statusline' option. It clears the association if given a "".
* StlShowFunc(), which maps the window number to the associated
StlShowFunc_[language]() function.
ftplugin/[lang]/StlShowFunc_[lang].vim
* Provides the function StlShowFunc_[lang](), which determines what
function the cursor is currently in and calls StlSetFunc(funcname)
when that function name changes and calls StlSetFunc("") when the
cursor is not currently inside a function).
* Invokes StlShowFunc "[lang]" to initialize the StlShowFunc system
for that window and language.
Here's a more detailed sequence of events involved in the function name
update:
* Initially, for supported languages, the ftplugin handler for the language
invokes StlShowFunc "[lang]", which calls s:ShowFuncSetup().
* This function then installs a CursorMoved autocommand event, so that when
the cursor is moved, StlShowFunc_[lang]() is called. It also calls
that handler to initialize a variable holding the name of the function
(if any) that the cursor is in.
* StlFuncSetup() then sets up the status line option ('stl') to call
StlShowFunc() (as well as to show other items on the status line).
* When the cursor is moved, the CursorMoved event is triggered. This
event thus invokes StlShowFunc_[lang]()
* StlShowFunc_[lang]() determines what the name of the function that the
cursor currently resides in is called. It calls StlSetFunc(funcname).
* StlSetFunc(funcname) sets a script variable, s:stlshowfunc_{winnr()},
to that function name. These variables are window-oriented, so one
may have multiple windows opened on the same file, each with their
own function name associated with their own cursor position.
* The 'statusline' option also triggers a refresh of the status line.
The 'statusline' option as set by StlFuncSetup() calls StlShowFunc()
as part of the status line refresh.
* The StlShowFunc() returns the string in s:stlshowfunc_{winnr()}.
OPTIONS
g:stlshowfunc_stlnofunc
This option lets users override the status line normally given by
the StlShowFunc plugin with their own preferences.
Use ":let" to set the following variable which will specify the statusline
when the cursor is not inside a function:
g:stlshowfunc_stlfunc
This option lets users override the status line normally given by
the StlShowFunc plugin with their own preferences.
Use ":let" to set the following variable which will specify the statusline
when the cursor is inside a function:
Note that including
will result in the status line showing the current function name.
The first variable (stlshowfunc_stlfunc) is used when StlShowFunc is
disabled; the second variable is used when StlShowFunc is enabled.
By default,
==============================================================================
3. StlShowFunc History StlShowFunc-history {{{1
v2 Jun 07, 2006 * modified ftplugin/StlShowFunc*.vim files to only update
the statusline when vim is in normal mode.
Sep 03, 2008 * stl now set in plugin/StlShowFunc.c
* "hi def" now used instead of HLTest().
May 20, 2009 * cecutil bug fix
Jun 15, 2009 * made all references to the statusline setting local
Aug 13, 2009 * StlShowFunc! stopped working somewhere along the line
(the StlShowFunc command was requiring an argument,
and obviously :StlShowFunc! doesn't have an argument)
Jul 09, 2010 * c files now avoid loading c/StlShowFunc_c.vim
* a test in cpp/StlShowFunc_cpp.vim no longer matches
things like "if" when embedded in a function name
when deciding if the function name is a real function.
Feb 07, 2011 * included support for fortran
Sep 24, 2012 * included g:stlshowfunc_stlfunc and g:stlshowfunc_stlnofunc
options
Nov 14, 2018 * included byte# option into no-function statusline
v1 May 25, 2006 * initial release
==============================================================================
4. Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: