3 Micro supports creating plugins with a simple Lua system. Plugins are
4 folders containing Lua files and possibly other source files placed
5 in `~/.config/micro/plug`. The plugin directory (within `plug`) should
6 contain at least one Lua file and an `info.json` file. The info file
7 provides additional information such as the name of the plugin, the
8 plugin's website, dependencies, etc... Here is an example info file
9 from the go plugin, which has the following file structure:
12 ~/.config/micro/plug/go-plugin
21 "description": "Go formatting and tool support",
22 "website": "https://github.com/micro-editor/go-plugin",
23 "install": "https://github.com/micro-editor/go-plugin",
31 All fields are simply interpreted as strings, so the version does not
32 need to be a semantic version, and the dependencies are also only
33 meant to be parsed by humans. The name should be an identifier, and
34 the website should point to a valid website. The install field should
35 provide info about installing the plugin, or point to a website that
40 Plugins use Lua but also have access to many functions both from micro
41 and from the Go standard library. Many callbacks are also defined which
42 are called when certain events happen. Here is the list of callbacks
45 * `init()`: this function should be used for your plugin initialization.
47 * `onBufferOpen(buf)`: runs when a buffer is opened. The input contains
50 * `onBufPaneOpen(bufpane)`: runs when a bufpane is opened. The input
51 contains the bufpane object.
53 * `onAction(bufpane)`: runs when `Action` is triggered by the user, where
54 `Action` is a bindable action (see `> help keybindings`). A bufpane
55 is passed as input and the function should return a boolean defining
56 whether the view should be relocated after this action is performed.
58 * `preAction(bufpane)`: runs immediately before `Action` is triggered
59 by the user. Returns a boolean which defines whether the action should
62 For example a function which is run every time the user saves the buffer
72 The `bp` variable is a reference to the bufpane the action is being executed within.
73 This is almost always the current bufpane.
75 All available actions are listed in the keybindings section of the help.
77 For callbacks to mouse actions, you are also given the event info:
80 function onMousePress(view, event)
81 local x, y = event:Position()
87 These functions should also return a boolean specifying whether the bufpane should
88 be relocated to the cursor or not after the action is complete.
90 ## Accessing micro functions
92 Some of micro's internal information is exposed in the form of packages which
93 can be imported by Lua plugins. A package can be imported in Lua and a value
94 within it can be accessed using the following syntax:
97 local micro = import("micro")
101 The packages and functions are listed below:
104 - `TermMessage(msg interface{}...)`
107 - `Log(msg interface{}...)`
114 - `OptionValueComplete`
118 - `AddRuntimeFilesFromDirectory`
119 - `AddRuntimeFileFromMemory`
127 - `RegisterCommonOption`
128 - `RegisterGlobalOption`
132 - `RunBackgroundShell`
133 - `RunInteractiveShell`
151 - `NewBufferFromFile`
155 - `GetLeadingWhitespace`
159 This may seem like a small list of available functions but some of the objects
160 returned by the functions have many methods. The Lua plugin may access any
161 public methods of an object returned by any of the functions above. For example,
162 with a BufPane object called `bp`, you could called the `Save` function in Lua
165 Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax.
168 micro.InfoBar().Message()
174 micro.InfoBar():Message()
177 ## Accessing the Go standard library
179 It is possible for your lua code to access many of the functions in the Go
182 Simply import the package you'd like and then you can use it. For example:
185 local ioutil = import("io/ioutil")
186 local fmt = import("fmt")
187 local micro = import("micro")
189 local data, err = ioutil.ReadFile("SomeFile.txt")
192 micro.InfoBar():Error("Error reading file: SomeFile.txt")
194 -- Data is returned as an array of bytes
195 -- Using Sprintf will convert it to a string
196 local str = fmt.Sprintf("%s", data)
198 -- Do something with the file you just read!
203 Here are the packages from the Go standard library that you can access.
204 Nearly all functions from these packages are supported. For an exact
205 list of which functions are supported you can look through `lua.go`
206 (which should be easy to understand).
225 For documentation for each of these functions, you can simply look
226 through the Go standard library documentation.
228 ## Adding help files, syntax files, or colorschemes in your plugin
230 You can use the `AddRuntimeFile(name, type, path string)` function to add
231 various kinds of files to your plugin. For example, if you'd like to add a help
232 topic to your plugin called `test`, you would create a `test.md` file, and call
236 AddRuntimeFile("test", "help", "test.md")
239 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of
240 files to the runtime. To read the content of a runtime file use
241 `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)`
242 for all runtime files.
244 ## Autocomplete command arguments
246 See this example to learn how to use `MakeCompletion` and `MakeCommand`
249 local function StartsWith(String,Start)
250 String = String:upper()
251 Start = Start:upper()
252 return string.sub(String,1,string.len(Start))==Start
255 function complete(input)
256 local allCompletions = {"Hello", "World", "Foo", "Bar"}
259 for i,v in pairs(allCompletions) do
260 if StartsWith(v, input) then
261 table.insert(result, v)
268 messenger:Message(arg)
271 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
276 For examples of plugins, see the default `autoclose` and `linter` plugins
277 (stored in the normal micro core repo under `runtime/plugins`) as well as any
278 plugins that are stored in the official channel
279 [here](https://github.com/micro-editor/plugin-channel).
283 Micro also has a built in plugin manager which you can invoke with the
284 `> plugin ...` command.
286 For the valid commands you can use, see the `commands` help topic.
288 The manager fetches plugins from the channels (which is simply a list of plugin
289 metadata) which it knows about. By default, micro only knows about the official
290 channel which is located at github.com/micro-editor/plugin-channel but you can
291 add your own third-party channels using the `pluginchannels` option and you can
292 directly link third-party plugins to allow installation through the plugin
293 manager with the `pluginrepos` option.
295 If you'd like to publish a plugin you've made as an official plugin, you should
296 upload your plugin online (to Github preferably) and add a `repo.json` file.
297 This file will contain the metadata for your plugin. Here is an example:
301 "Name": "pluginname",
302 "Description": "Here is a nice concise description of my plugin",
303 "Tags": ["python", "linting"],
307 "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
316 Then open a pull request at github.com/micro-editor/plugin-channel adding a link
317 to the raw `repo.json` that is in your plugin repository. To make updating the
318 plugin work, the first line of your plugins lua code should contain the version
319 of the plugin. (Like this: `VERSION = "1.0.0"`) Please make sure to use
320 [semver](http://semver.org/) for versioning.