Making a plugin¶
This page is intended as a guide for creating an editor plugin which uses homotopy to compile snippets.
Atom example can also be used as a reference.
Calling homotopy¶
Once installed with pip
, Homotopy can be used by calling homotopy
program.
It takes several arguments (see Arguments section) and prints the resulting snippet to stdout.
Warning messages are outputted to stderr.
On a high level, plugin should do the following:
- Collect arguments from editor.
- Call
homotopy
. - Replace snippet text with the result of
homotopy
call.
Arguments¶
There are several arguments that can be passed to homotopy
.
Only two are required, language and snippet, but all of them should be provided by the plugin for full experience.
Language¶
This is the first positional argument. It represents the name of the language the snippet should be compiled to.
Cursor (-c)¶
When flag -c
is present homotopy
will put text [{cursor_marker}]
at the place
where the cursor should be placed after the expansion of the snippet.
homotopy -c c++ "if$true>"
if(true){
[{cursor_marker}]
}
Path (-p)¶
This optional argument that indicates the locations of custom snippets.
Value is string containing paths to snippet locations separated by ::
.
homotopy -p folder1::folder2 c++ if$true
if(true){
}
Tab size (-t)¶
Homotopy uses tabs to indent code. If the editor is configured to use soft tabs (spaces instead of tabs), use this option to indicate the size of one tab. All tabs in the result will be converted to the given number of spaces.
If this argument is not present, code with tabs will be returned.
homotopy -t 4 c++ if$true
if(true){
}
Cursor position¶
To make the user flow more natural, homotopy can mark the location that the cursor should be in after the expansion of a snippet.
There are few things to keep in mind when implementing this feature.
- Look for
[{cursor_marker}]
and replace it with cursor. Keep in mind that text [{cursor_marker}] should not be displayed. - If, for any reason,
[{cursor_marker}]
is not present, place the cursor in the line after the expanded snippet text. - Make sure that the operation looks atomic with respect to undo/redo logic.
Settings¶
Following user settings should be supported.
Homotopy location¶
If homotopy
is not in the user PATH, he/she should be able to configure the path to it.
User library¶
Locations to user library folders should be configurable and passed to the engine with -p
argument.
Error handling¶
- If an error occurs (wrong path to
homotopy
for example) when callinghomotopy
, an error message should be displayed to the user. - If any waring message is present (i.e. stderr is not empty), it should be displayed to the user (for example, so he/she can be informed when the snippet database is corrupt).