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/
19 The `go.lua` file contains the main code for the plugin, though the
20 code may be distributed across multiple Lua files. The `info.json`
21 file contains information about the plugin such as the website,
22 description, version, and any requirements. Plugins may also
23 have additional files which can be added to micro's runtime files,
24 of which there are 5 types:
32 In most cases, a plugin will want to add help files, but in certain
33 cases a plugin may also want to add colorschemes or syntax files. It
34 is unlikely for a plugin to need to add plugin files at runtime or
35 syntax header files. No directory structure is enforced but keeping
36 runtime files in their own directories is good practice.
40 The `info.json` for the Go plugin is the following:
45 "description": "Go formatting and tool support",
46 "website": "https://github.com/micro-editor/go-plugin",
47 "install": "https://github.com/micro-editor/go-plugin",
55 All fields are simply interpreted as strings, so the version does not
56 need to be a semantic version, and the dependencies are also only
57 meant to be parsed by humans. The name should be an identifier, and
58 the website should point to a valid website. The install field should
59 provide info about installing the plugin, or point to a website that
62 Note that the name of the plugin is defined by the name field in
63 the `info.json` and not by the installation path. Some functions micro
64 exposes to plugins require passing the name of the plugin.
68 Plugins use Lua but also have access to many functions both from micro
69 and from the Go standard library. Many callbacks are also defined which
70 are called when certain events happen. Here is the list of callbacks
73 * `init()`: this function should be used for your plugin initialization.
75 * `onBufferOpen(buf)`: runs when a buffer is opened. The input contains
78 * `onBufPaneOpen(bufpane)`: runs when a bufpane is opened. The input
79 contains the bufpane object.
81 * `onAction(bufpane)`: runs when `Action` is triggered by the user, where
82 `Action` is a bindable action (see `> help keybindings`). A bufpane
83 is passed as input and the function should return a boolean defining
84 whether the view should be relocated after this action is performed.
86 * `preAction(bufpane)`: runs immediately before `Action` is triggered
87 by the user. Returns a boolean which defines whether the action should
90 For example a function which is run every time the user saves the buffer
100 The `bp` variable is a reference to the bufpane the action is being executed within.
101 This is almost always the current bufpane.
103 All available actions are listed in the keybindings section of the help.
105 For callbacks to mouse actions, you are also given the event info:
108 function onMousePress(view, event)
109 local x, y = event:Position()
115 These functions should also return a boolean specifying whether the bufpane should
116 be relocated to the cursor or not after the action is complete.
118 ## Accessing micro functions
120 Some of micro's internal information is exposed in the form of packages which
121 can be imported by Lua plugins. A package can be imported in Lua and a value
122 within it can be accessed using the following syntax:
125 local micro = import("micro")
129 The packages and functions are listed below (in Go type signatures):
132 - `TermMessage(msg interface{}...)`
135 - `Log(msg interface{}...)`
136 - `SetStatusInfoFn(fn string)`
142 - `OptionValueComplete`
146 - `AddRuntimeFilesFromDirectory`
147 - `AddRuntimeFileFromMemory`
155 - `RegisterCommonOption`
156 - `RegisterGlobalOption`
160 - `RunBackgroundShell`
161 - `RunInteractiveShell`
179 - `NewBufferFromFile`
185 - `GetLeadingWhitespace`
189 This may seem like a small list of available functions but some of the objects
190 returned by the functions have many methods. The Lua plugin may access any
191 public methods of an object returned by any of the functions above. Unfortunately
192 it is not possible to list all the available functions on this page. Please
193 go to the internal documentation at https://godoc.org/github.com/zyedidia/micro
194 to see the full list of available methods. Note that only methods of types that
195 are available to plugins via the functions above can be called from a plugin.
196 For an even more detailed reference see the source code on Github.
198 For example, with a BufPane object called `bp`, you could call the `Save` function
199 in Lua with `bp:Save()`.
201 Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax.
204 micro.InfoBar().Message()
210 micro.InfoBar():Message()
213 ## Accessing the Go standard library
215 It is possible for your lua code to access many of the functions in the Go
218 Simply import the package you'd like and then you can use it. For example:
221 local ioutil = import("io/ioutil")
222 local fmt = import("fmt")
223 local micro = import("micro")
225 local data, err = ioutil.ReadFile("SomeFile.txt")
228 micro.InfoBar():Error("Error reading file: SomeFile.txt")
230 -- Data is returned as an array of bytes
231 -- Using Sprintf will convert it to a string
232 local str = fmt.Sprintf("%s", data)
234 -- Do something with the file you just read!
239 Here are the packages from the Go standard library that you can access.
240 Nearly all functions from these packages are supported. For an exact
241 list of which functions are supported you can look through `lua.go`
242 (which should be easy to understand).
261 For documentation for each of these functions, see the Go standard
262 library documentation at https://golang.org/pkg/ (for the packages
263 exposed to micro plugins). The Lua standard library is also available
264 to plugins though it is rather small.
266 ## Adding help files, syntax files, or colorschemes in your plugin
268 You can use the `AddRuntimeFile(name string, type config.RTFiletype, path string)`
269 function to add various kinds of files to your plugin. For example, if you'd
270 like to add a help topic to your plugin called `test`, you would create a
271 `test.md` file, and call the function:
274 config = import("micro/config")
275 config.AddRuntimeFile("test", config.RTHelp, "test.md")
278 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of
279 files to the runtime. To read the content of a runtime file use
280 `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)`
281 for all runtime files. In addition, there is `AddRuntimeFileFromMemory` which
282 adds a runtime file based on a string that may have been constructed at
287 There are 6 default plugins that come pre-installed with micro. These are
289 * `autoclose`: automatically closes brackets, quotes, etc...
290 * `comment`: provides automatic commenting for a number of languages
291 * `ftoptions`: alters some default options depending on the filetype
292 * `linter`: provides extensible linting for many languages
293 * `literate`: provides advanced syntax highlighting for the Literate
295 * `status`: provides some extensions to the status line (integration with
298 These are good examples for many use-cases if you are looking to write
303 Micro's plugin manager is you! Ultimately the plugins that are created
304 for micro are quite simple and don't require a complex automated tool
305 to manage them. They should be "git cloned" or somehow placed in the
306 `~/.config/micro/plug` directory, and that is all that's necessary
307 for installation. In the rare case that a more complex installation
308 process is needed (such as dependencies, or additional setup) the
309 plugin creator should provide the additional instructions on their
310 website and point to the link using the `install` field in the `info.json`