Refactorvim

Marco Herrn [email protected] 2019-11-10 :notoc: :homepage: https://github.com/hupfdule/refactorvim :license-link: https://github.com/hupfdule/refactorvim/blob/master/LICENSE.txt :source-highlighter: prettify :refactorvim-version: 0.3.0 :experimental:

Refactorvim is a small Vim plugin for refactoring vimscript plugins.

It provides an ftplugin for vim files and therefore is only active when the current buffer has filetype vim.

With refactovim you can

• Rename and move autoload functions
• Toggle the visibility of functions and variables between autoload and script-local
• Jump to the definition of a function or variable

Refactorvim is designed to refactor the codebase of a single Vim plugin. Therefore it operates in the whole plugin directory of the currently edited file.

Commands

Refactorvim provides the following commands:

[[:RefactorvimRename]] RefactorvimRename:: Rename an autoload function or an autoload namespace. + This can be used to rename a function without changing its namespace. +

For example when moving function foo#bar#frobnitz() to foo#bar#qux() the resulting function name will be foo#bar#qux().

It can also be used to rename a function including its namespace. This involves moving the function declaration to the autoload file corresponding to the new namespace. +

For example when moving function foo#bar#frobnitz() to the namespace baz#qux# the resulting function name will be baz#qux#frobnitz().

It can also be used to rename a whole autoload namespace. This involves moving the file corresponding to the original namepace to the file corresponding to the new namespace. +

For example when moving namespace foo#bar# to baz#qux# the new function name of foo#bar#frobnitz() will be baz#qux#frobnitz().

In all cases references to the affected functions are updated in the whole project. + This command has some internal logic to decide whether the given arguments are a function or a namespace. This is done in the following order: + - if the given name ends with () it is considered a function - if the given name ends with # it is considered a namespace - if a function with the given name exists it is considered a function - if an autoload vim script with the path corresponding to the given name exists it is considered a namespace - otherwise the meaning is unclear and an error will be displayed + To make the meaning clear always provide the () or # suffix. + This command takes two parameters. + 1. {source} The function or namespace to rename. 2. {target} The new name of the function or namespace. + The command supports completion for both parameters via kbd:[Tab] key. + Additionally a <<detect-autoload-function, commandline mode mapping>> is defined to fill in the current autoload function.

Be aware that this does not check for referenced script-local variables and functions. Therefore after such a refactoring it may be possible that the code isn't directly runnable without further adaptations.

[[:RefactorvimToggleVisibility]] RefactorvimToggleVisibility:: Toggle the visibility of a function or variable between autoload and script-local. + This command operates on the <cword>. Therefore the cursor must reside on the name of a function or variable. + If the function or variable starts with s: it is considered script-local and will be switched to autoload by removing the s: prefix and instead adding the autoload prefix for the current autoload script. + If the function or variable contains # characters it is considered an autoload function or variable and will be switched to script-local by removing the autoload prefix and adding s: instead. + As autoload functions and variables may already be referenced in other scripts a check is done to verify whether they are already referenced outside the script. If that is the case, the user gets the choice of changing the visibility only in the current script (in which case the existing references will be broken, as they refer to an autoload function or variable that doesn't exist anymore) or changing the visibility in all files (in which case the existing references will be broken, as the refer to a script-local function or variable in a different script) or aborting the operation (in which case no changes will be made). + Other scopes (like buffer-local, window-local, etc.) are not supported and in such cases this command does nothing than displaying an error.

Mappings

Refactorivm provides the following mappings:

[[detect-autoload-function]] <Plug>(RefactorvimCurrentAutoloadFunction):: A commandline mode mapping for detecting the autoload function to operate on. + If the cursor is currently on the name of an autoload function, that name is returned. + If the cursor is somewhere inside an autoload function or in a comment directly preceding an autoload function (without any blank lines between) the name of that function is returned. + Otherwise nothing is returned. + By default this mapping is mapped to <C-R><C-N> + Use cmap {newmapping} <Plug>(RefactorvimCurrentAutoloadFunction) to map it to a different key.

[[toggle-visibility]] <Plug>(RefactorvimToggleVisibility):: A normal mode mapping for toggling the visibility of the function or variable at the current cursor position (the name of the function or variable needs to be the <cword>). + By default this mapping is mapped to <Leader>V + Use nmap {newmapping} <Plug>(RefactorvimToggleVisibility) to map it to a different key.

[[go-to-definition]] <Plug>(RefactorvimGotoDefinition):: A normal mode mapping for jumping to the definition of the function or variable at the current cursor position. + In the case of (script-local or autoload) functions the cursor will be moved the function signature. + In the case of function arguments (prefixed by a:) the cursor will be moved to the corresponding argument in the function signature. + In the case of local variables (prefixed by l: or without any prefix) the cursor will be moved to the first assignment to that variable. + In the case of autloat variables the exact definition is a bit unclear and the cursor will be moved to the first assignment to that variable in the autload script matching the variables autoload prefix. + By default this mapping is mapped to gd + Use nmap {newmapping} <Plug>(RefactorvimGotoDefinition) to map it to a different key.

Functions

Refactorvim provides the following functions:

refactorvim#renaming#get_autoload_functions():: Returns the names of all autoload functions in the current project as a list. + The names dont include the trailing ()` characters. + This function is used internally to provide completion of command arguments to <<:RefactorvimRename, RefactorvimRename>>.

refactorvim#renaming#get_autoload_namespaces():: Returns the names of all autoload namespaces in the current project as a list. + The names dont include the trailing #` character. + This function is used internally to provide completion of command arguments to <<:RefactorvimRename, RefactorvimRename>>.

refactorvim#renaming#get_current_autoload_function():: Returns the name of the autoload function the cursor is currently in. + See <<detect-autoload-function, <Plug>(RefactorvimCurrentAutoloadFunction)>> for a detailled description and the default mapping that is assigned to that function.

refactorvim#renaming#rename({source}, {target}):: Renames an autoload function or namespace including necessary renaming and copying of files due to changed namespaces. + This function is by default provided via the <<:RefactorvimRename, RefactorvimRename>> command. + See <<:RefactorvimRename, RefactorvimRename>> for a detailled description of the provided functionality.

refactorvim#renaming#toggle_visibility({function_name}):: Toggle the visibility of the specified function between script-local and autoloaded. + This function is by default provided via the <<:RefactorvimToggleVisibility, RefactorvimToggleVisibility>> command and the <<toggle-visibility, toggle-visibility>> mapping. + See <<:RefactorvimToggleVisibility, RefactorvimToggleVisibility>> for a detailed description of the provided functionality.

refactorvim#motions#goto_definition():: Jump to the definition of the function or variable under the cursor. + This function is by default provided via the <<go-to-definition, go-to-definition>> mapping. + See <<go-to-definition, go-to-definition>> for a detailed description of the provided functionality.

Complementary Plugins

https://github.com/machakann/vim-Verdin[machakann/vim-Verdin]:: Provides an omni completion function for Vim script. https://github.com/tpope/vim-scriptease[tpope/vim-scriptease]:: Provides handy commands for writing Vim plugins. https://github.com/WolfgangMehner/vim-support[WolfgangMehner/vim-support]:: Provides snippets, templates and mappings for writing Vim plugins.

License

This plugin is licensed under the terms of the link:{license-link}[MIT License].