Updated to vai 1.6
Vai has a for now simple plugin system based on yapsy. Vai supports two types of plugins at the moment
- Command plugins, which are activated when the user types
:sometext
while in command mode and presses enter, and - Syntaxcolor plugins, which are activated on startup to determine the personalized color highlighting of syntax.
Plugin development is made easier by a SDK package provided as vai.sdk. Plugins importing vai.sdk
get access to a set
of easy access functions and classes that abstract the inner workings of vai as much as possible, making plugins
more stable in the face of changes in vai and easier to write for the plugin developer.
There are two levels of plugins. The system plugins are shipped with vai, and must be placed in the proper directory under
vai/plugins. User plugins are plugins that are installed by the user, and must go in the proper subdirectory of
~/.local/share/vai/plugins/
All plugins must be contained in their own directory (e.g. MyPlugin). This directory must contain the following files
MyPlugin.ini
contains information about the plugin, in a simple INI format.MyPlugin.py
contains the "entry point" for the plugin. In most cases, this contains a single class with a proper interface we will explain later.__init__.py
Being a plugin a python package, this file must exist, and in general must be empty
The ini file has the same structure regardless of the plugin type, and must contain the following entries, which are quite self-explanatory. Module must refer to the MyPlugin.py file containing the plugin classes:
[Core] Name = MyPlugin Module = MyPlugin.py [Documentation] Author = Stefano Borini Version = 1.0 Website = http://github.com/stefanoborini/vai Description = My first plugin
The content of the MyPlugin.py
depends on the actual plugin type.
To write a syntaxcolor plugin, the best starting point is the DeepBlue syntaxcolor plugin, available in vai/plugins/syntaxcolors/
.
This is a very dumb syntax color plugin that paints all syntax tokens blue.
The Module file DeepBlue.py must define a class instance of sdk.SyntaxColorsPlugin
:
class DeepBlue(sdk.SyntaxColorsPlugin):
This class must define three methods:
name(self)
Returns the name of the plugin as a string.supportsNumColors(self, num_colors)
returns True if the plugin supports the passed amount of colors. If you develop a purely 8 colors plugin, return True only if num_colors is 8, False otherwisecolorSchema(self, num_colors)
this is the business end of the class. It must return a dictionary associating syntax tokens to colors.
To better explain the last method, see the following examples:
"Keyword": "blue",
This entry associates the "Keyword" token, to the color blue. All keywords will appear as blue, if not specified otherwise with a more specific Keyword identification:
"Keyword.Constant": "white,blue",
Although not yet supported, this syntax will allow to specify font properties alterations:
"Keyword.Constant": "white bold,blue",
The space separates alterations from the color. Alterations must come after the color.
You can obtain a list of the available tokens from the pygments documentation, and the list of the available colors from the module
vaitk.gui.VColor.VGlobalColors
distributed together with vai. At the moment, only named colors can be specified, not hex values.
To install the syntaxcolor plugin you have to copy the plugin directory into
~/.local/share/vai/plugins/syntaxcolors/
. The new colorscheme will only be used if chosen. You enable it
by editing ~/.config/vai/vairc
and setting
"colors.syntax_schema": "your_syntaxcolor_name",
A command plugin is triggered when the user types a :command
while in command mode.
The command plugin is defined as a class derived from sdk.CommandPlugin
. Your plugin must reimplement this class
The Time plugin, available in vai/plugins/commands/Time
, shows a trivial plugin that sets the current time in the
status bar for 3 seconds:
class TimePlugin(sdk.CommandPlugin): def name(self): """ To be reimplement in the plugin """ return "Time" def keyword(self): return "time" def execute(self, command_line): sdk.statusBar().setMessage(time.asctime(), 3000) return True
The name method, as in the case of the syntaxcolors plugins, must return the conventional name for the plugin.
The keyword method must return the keyword that will activate the plugin at the command line. In this case,
typing :time
will activate the plugin. When this happens, the execute()
method will be called.
The full command line as a string will be passed as an argument.