How to define external Vim functions?

[jphalip]

Hi,

I'd like to create some custom Vim functions. It looks like all the standard functions in IdeaVim are annotated with @VimscriptFunction, but that annotation comes from the annotation-processors kotlin project, which I'm not sure is accessible from outside of IdeaVim.

Could you please clarify it it's in fact possible to define your own functions, and if so, how?

Thanks!

Julien

[citizenmatt]

If you're writing an extension to IdeaVim, you'll most likely implement VimExtension to register mappings, etc. You can also export functions here, using the VimExtensionFacade.exportScriptFunction method.

Here's the method signature:

ideavim/src/main/java/com/maddyhome/idea/vim/extension/VimExtensionFacade.kt

Lines 221 to 229 in 791edbd

	fun exportScriptFunction(
	scope: Scope?,
	name: String,
	args: List<String>,
	defaultArgs: List<Pair<String, Expression>>,
	hasOptionalArguments: Boolean,
	flags: EnumSet<FunctionFlag>,
	function: ScriptFunction
	) {

This essentially corresponds to the :function command and defines the function, with name, arguments, default values, etc. You can also specify the range, abort, dict and closure flags (see :help func-range, :help func-abort, etc.). Finally, you need to pass an instance of the ScriptFunction interface:

ideavim/src/main/java/com/maddyhome/idea/vim/extension/VimExtensionFacade.kt

Lines 278 to 280 in 791edbd

	fun interface ScriptFunction {
	fun execute(editor: VimEditor, context: ExecutionContext, args: Map<String, VimDataType>): ExecutionResult
	}

This is easily implemented, takes in an editor, the current context and a map of argument to VimDataType values. You don't get quite as much flexibility as a normal script function, especially with additional optional arguments, but you can most likely implement what you need. The return value should be an instance of ExecutionResult, which can be success, error, break, continue or an instance with a return value.

I'm only aware of one usage of this method, and that's to support custom operators from extensions with the 'operatorfunc' option. Some of the built in extensions will export a script function and create bindings that set opfunc=CommentaryOperatorFunc and then invoke the g@ command, just like they would do as a standard Vim script plugin.

They use the VimExtensionFacade.exportOperatorFunction helper to export the function, and it's a good example of how to export custom code as a script function:

ideavim/src/main/java/com/maddyhome/idea/vim/extension/VimExtensionFacade.kt

Lines 257 to 276 in 791edbd

	fun VimExtensionFacade.exportOperatorFunction(name: String, function: OperatorFunction) {
	exportScriptFunction(null, name, listOf("type"), emptyList(), false, noneOfEnum()) {
	editor, context, args ->
	val type = args["type"]?.asString()
	val selectionType = when (type) {
	"line" -> SelectionType.LINE_WISE
	"block" -> SelectionType.BLOCK_WISE
	"char" -> SelectionType.CHARACTER_WISE
	else -> return@exportScriptFunction ExecutionResult.Error
	}
	if (function.apply(editor, context, selectionType)) {
	ExecutionResult.Success
	}
	else {
	ExecutionResult.Error
	}
	}
	}

It registers the script function and provides an (implicit) implementation of the ScriptFunction interface that converts the 'operatorfunc' arguments into parameters for the OperatorFunction.apply method.

[jphalip]

Thanks @citizenmatt for your thorough reply. I'll look into this and come back if I run into any issues.