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`
183 - `GetLeadingWhitespace`
187 This may seem like a small list of available functions but some of the objects
188 returned by the functions have many methods. The Lua plugin may access any
189 public methods of an object returned by any of the functions above. Unfortunately
190 it is not possible to list all the available functions on this page. Please
191 go to the internal documentation at https://godoc.org/github.com/zyedidia/micro
192 to see the full list of available methods. Note that only methods of types that
193 are available to plugins via the functions above can be called from a plugin.
194 For an even more detailed reference see the source code on Github.
196 For example, with a BufPane object called `bp`, you could call the `Save` function
197 in Lua with `bp:Save()`.
199 Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax.
202 micro.InfoBar().Message()
208 micro.InfoBar():Message()
211 ## Accessing the Go standard library
213 It is possible for your lua code to access many of the functions in the Go
216 Simply import the package you'd like and then you can use it. For example:
219 local ioutil = import("io/ioutil")
220 local fmt = import("fmt")
221 local micro = import("micro")
223 local data, err = ioutil.ReadFile("SomeFile.txt")
226 micro.InfoBar():Error("Error reading file: SomeFile.txt")
228 -- Data is returned as an array of bytes
229 -- Using Sprintf will convert it to a string
230 local str = fmt.Sprintf("%s", data)
232 -- Do something with the file you just read!
237 Here are the packages from the Go standard library that you can access.
238 Nearly all functions from these packages are supported. For an exact
239 list of which functions are supported you can look through `lua.go`
240 (which should be easy to understand).
259 For documentation for each of these functions, see the Go standard
260 library documentation at https://golang.org/pkg/ (for the packages
261 exposed to micro plugins). The Lua standard library is also available
262 to plugins though it is rather small.
264 ## Adding help files, syntax files, or colorschemes in your plugin
266 You can use the `AddRuntimeFile(name string, type config.RTFiletype, path string)`
267 function to add various kinds of files to your plugin. For example, if you'd
268 like to add a help topic to your plugin called `test`, you would create a
269 `test.md` file, and call the function:
272 config = import("micro/config")
273 config.AddRuntimeFile("test", config.RTHelp, "test.md")
276 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of
277 files to the runtime. To read the content of a runtime file use
278 `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)`
279 for all runtime files. In addition, there is `AddRuntimeFileFromMemory` which
280 adds a runtime file based on a string that may have been constructed at
285 There are 6 default plugins that come pre-installed with micro. These are
287 * `autoclose`: automatically closes brackets, quotes, etc...
288 * `comment`: provides automatic commenting for a number of languages
289 * `ftoptions`: alters some default options depending on the filetype
290 * `linter`: provides extensible linting for many languages
291 * `literate`: provides advanced syntax highlighting for the Literate
293 * `status`: provides some extensions to the status line (integration with
296 These are good examples for many use-cases if you are looking to write
301 Micro's plugin manager is you! Ultimately the plugins that are created
302 for micro are quite simple and don't require a complex automated tool
303 to manage them. They should be "git cloned" or somehow placed in the
304 `~/.config/micro/plug` directory, and that is all that's necessary
305 for installation. In the rare case that a more complex installation
306 process is needed (such as dependencies, or additional setup) the
307 plugin creator should provide the additional instructions on their
308 website and point to the link using the `install` field in the `info.json`