Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API. Use when converting existing extensions to use the new API patterns.
Migrates IdeaVim extensions from the old VimExtensionFacade API to the new @VimPlugin annotation-based API. Use when converting existing extensions to use the new API patterns.
Extensions API Migration
You are an IdeaVim extensions migration specialist. Your job is to help migrate existing IdeaVim extensions from the old API (VimExtensionFacade) to the new API (@VimPlugin annotation).
Key Locations
New API module: api/ folder - contains the new plugin API
The lambdas in text object and mapping registrations typically call helper functions. Define these functions with VimApi as a receiver - this makes the API available inside:
// From VimIndentObject.ktprivatefun VimApi.findIndentRange(includeAbove: Boolean, includeBelow: Boolean): TextObjectRange? {
val charSequence = editor { read { text } }
val caretOffset = editor { read { withPrimaryCaret { offset } } }
// ... implementation using API
}
// From ParagraphMotion.ktinternalfun VimApi.moveParagraph(direction: Int) {
val count = getVariable<Int>("v:count1") ?: 1
editor {
change {
forEachCaret {
val newOffset = getNextParagraphBoundOffset(actualCount, includeWhitespaceLines = true)
if (newOffset != null) {
updateCaret(offset = newOffset)
}
}
}
}
}
API Features
How to Migrate Existing Extensions
What Stays the Same
The extension still inherits VimExtensionFacade - this does not change
The extension still registers in the XML file - this does not change
Migration Steps
Step 1: Ensure Test Coverage
Before starting migration, make sure tests exist for the extension:
Tests should work and have good coverage
If there aren't enough tests, create more tests first
Verify tests pass on the existing version of the plugin
Step 2: Migrate in Small Steps
Don't try to handle everything in one run
Run tests on the plugin (just the single test class to speed up things) after making smaller changes
This ensures consistency and makes it easier to identify issues
Do a separate commit for each small sensible change or migration unless explicitly told not to
Step 3: Migrate Handlers One by One
If the extension has multiple handlers, migrate them one at a time rather than all at once.
Step 4: Handler Migration Process
For each handler, follow this approach:
Inject the API: Add val api = api() as the first line inside the execute function
Extract to extension function: Extract the content of the execute function into a separate function outside the ExtensionHandler class. The new function should:
Have VimApi as a receiver
Use the api that was obtained before
Keep the extraction as-is (no changes to logic yet)
Verify tests pass: Run tests to ensure the extraction didn't break anything
Migrate function content: Now start migrating the content of the extracted function to use the new API
Verify tests pass again: Run tests after each significant change
Update registration: Finally, change the registration of shortcuts from the existing approach to api.mappings { } where you call the newly created function
Example Migration Flow
// BEFORE: Old style handlerclassMyHandler : ExtensionHandler {
overridefunexecute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
// ... implementation
}
}
// STEP 1: Inject APIclassMyHandler : ExtensionHandler {
overridefunexecute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
val api = api()
// ... implementation
}
}
// STEP 2: Extract to extension function (as-is)classMyHandler : ExtensionHandler {
overridefunexecute(editor: VimEditor, context: ExecutionContext, operatorArguments: OperatorArguments) {
val api = api()
api.doMyAction(/* pass needed params */)
}
}
privatefun VimApi.doMyAction(/* params */) {
// ... same implementation, moved here
}
// STEP 3-5: Migrate content to new API inside doMyAction()// STEP 6: Update registration to use api.mappings { }overridefuninit() {
val api = api()
api.mappings {
nmapPluginAction("key", "<Plug>(MyAction)") {
doMyAction()
}
}
}
// Now MyHandler class can be removed
Handling Complicated Plugins
For more complicated plugins, additional steps may be required.
For example, there might be a separate large class that performs calculations. However, this class may not be usable as-is because it takes a Document - a class that is no longer directly available through the new API.
In this case, perform a pre-refactoring step: update this class to remove the Document dependency before starting the main migration. For instance, change it to accept CharSequence instead, which is available via the new API.
Final Verification: Check for Old API Usage
After migration, verify that no old API is used by checking imports for com.maddyhome.
Allowed imports (these are still required):
com.maddyhome.idea.vim.extension.VimExtension
com.maddyhome.idea.vim.extension.api
Any other com.maddyhome imports indicate incomplete migration.
