*userfunc.txt*	Nvim


		  VIM REFERENCE MANUAL	  by Bram Moolenaar


Defining and using functions.

This is introduced in section |41.7| of the user manual.

				      Type |gO| to see the table of contents.

==============================================================================

1. Defining a function ~
						*define-function*
New functions can be defined.  These can be called just like builtin
functions.  The function executes a sequence of Ex commands.  Normal mode
commands can be executed with the |:normal| command.

The function name must start with an uppercase letter, to avoid confusion with
builtin functions.  To prevent from using the same name in different scripts
make them script-local.  If you do use a global function then avoid obvious,
short names.  A good habit is to start the function name with the name of the
script, e.g., "HTMLcolor()".

It is also possible to use curly braces, see |curly-braces-names|.

The |autoload| facility is useful to define a function only when it's called.

							*local-function*
A function local to a script must start with "s:".  A local script function
can only be called from within the script and from functions, user commands
and autocommands defined in the script.  It is also possible to call the
function from a mapping defined in the script, but then |<SID>| must be used
instead of "s:" when the mapping is expanded outside of the script.
There are only script-local functions, no buffer-local or window-local
functions.

					*:fu* *:function* *E128* *E129* *E123*
:fu[nction]		List all functions and their arguments.

:fu[nction][!] {name}	List function {name}, annotated with line numbers
			unless "!" is given.
			{name} may be a |Dictionary| |Funcref| entry: >
				:function dict.init
<			Note that {name} is not an expression, you cannot use
			a variable that is a function reference.  You can use
			this dirty trick to list the function referred to with
			variable "Funcref": >
				let g:MyFuncref = Funcref
				func g:MyFuncref
				unlet g:MyFuncref

:fu[nction] /{pattern}	List functions with a name matching {pattern}.
			Example that lists all functions ending with "File": >
				:function /File$
<
							*:function-verbose*
When 'verbose' is non-zero, listing a function will also display where it was
last defined. Example: >

    :verbose function SetFileTypeSH
	function SetFileTypeSH(name)
	    Last set from /usr/share/vim/vim-7.0/filetype.vim
<
See |:verbose-cmd| for more information.

						*E124* *E125* *E853* *E884*
:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
			Define a new function by the name {name}.  The body of
			the function follows in the next lines, until the
			matching |:endfunction|.

			The name must be made of alphanumeric characters and
			'_', and must start with a capital or "s:" (see
			above).  Note that using "b:" or "g:" is not allowed.
			(since patch 7.4.260 E884 is given if the function
			name has a colon in the name, e.g. for "foo:bar()".
			Before that patch no error was given).

			{name} may be a |Dictionary| |Funcref| entry: >
				:function dict.init(arg)
<			"dict" must be an existing dictionary.  The entry
			"init" is added if it didn't exist yet.  Otherwise [!]
			is required to overwrite an existing function.  The
			result is a |Funcref| to a numbered function.  The
			function can only be used with a |Funcref| and will be
			deleted if there are no more references to it.
								*E127* *E122*
			When a function by this name already exists and [!] is
			not used an error message is given.  There is one
			exception: When sourcing a script again, a function
			that was previously defined in that script will be
			silently replaced.
			When [!] is used, an existing function is silently
			replaced.  Unless it is currently being executed, that
			is an error.
			NOTE: Use ! wisely.  If used without care it can cause
			an existing function to be replaced unexpectedly,
			which is hard to debug.

			For the {arguments}