3 Micro supports creating plugins with a simple Lua system. Every plugin has a
4 main script which is run at startup which should be placed in
5 `~/.config/micro/plugins/pluginName/pluginName.lua`.
7 There are a number of callback functions which you can create in your
8 plugin to run code at times other than startup. The naming scheme is
9 `onAction(view)`. For example a function which is run every time the user saves
19 The `view` variable is a reference to the view the action is being executed on.
20 This is almost always the current view, which you can get with `CurView()` as well.
22 All available actions are listed in the keybindings section of the help.
24 These functions should also return a boolean specifying whether the view
25 should be relocated to the cursor or not after the action is complete.
27 Note that these callbacks occur after the action has been completed. If you
28 want a callback before the action is executed, use `preAction()`. In this case
29 the boolean returned specifies whether or not the action should be executed
30 after the lua code completes.
32 Another useful callback to know about which is not a action is
33 `onViewOpen(view)` which is called whenever a new view is opened and the new
34 view is passed in. This is useful for setting local options based on the filetype,
35 for example turning off `tabstospaces` only for Go files when they are opened.
39 There are a number of functions and variables that are available to you in
40 order to access the inner workings of micro. Here is a list (the type signatures
41 for functions are given using Go's type system):
43 * `OS`: variable which gives the OS micro is currently running on (this is the same
44 as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...)
46 * `configDir`: contains the path to the micro configuration files
48 * `tabs`: a list of all the tabs currently in use
50 * `curTab`: the index of the current tabs in the tabs list
52 * `messenger`: lets you send messages to the user or create prompts
54 * `NewBuffer(text, path string) *Buffer`: creates a new buffer from a given reader with a given path
56 * `GetLeadingWhitespace() bool`: returns the leading whitespace of the given string
58 * `IsWordChar(str string) bool`: returns whether or not the string is a 'word character'
60 * `RuneStr(r rune) string`: returns a string containing the given rune
62 * `Loc(x, y int) Loc`: returns a new `Loc` struct
64 * `JoinPaths(dir... string) string` combines multiple directories to a full path
66 * `DirectoryName(path string)` returns all but the last element of path ,typically the path's directory
68 * `GetOption(name string)`: returns the value of the requested option
70 * `AddOption(name string, value interface{})`: sets the given option with the given
71 value (`interface{}` means any type in Go)
73 * `SetOption(option, value string)`: sets the given option to the value. This will
74 set the option globally, unless it is a local only option.
76 * `SetLocalOption(option, value string, view *View)`: sets the given option to
77 the value locally in the given buffer
79 * `BindKey(key, action string)`: binds `key` to `action`
81 * `MakeCommand(name, function string, completions ...Completion)`:
82 creates a command with `name` which will call `function` when executed.
83 Use 0 for completions to get NoCompletion.
85 * `MakeCompletion(function string)`:
86 creates a `Completion` to use with `MakeCommand`
88 * `CurView()`: returns the current view
90 * `HandleCommand(cmd string)`: runs the given command
92 * `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`: runs the given shell
93 command. The `interactive` bool specifies whether the command should run in the background. The
94 `waitToClose` bool only applies if `interactive` is true and means that it should wait before
95 returning to the editor.
97 * `ToCharPos(loc Loc, buf *Buffer) int`: returns the character position of a given x, y location
99 * `Reload`: (Re)load everything
101 * `ByteOffset(loc Loc, buf *Buffer) int`: exactly like `ToCharPos` except it it counts bytes instead of runes
103 * `JobSpawn(cmdName string, cmdArgs []string, onStdout, onStderr, onExit string, userargs ...string)`:
104 Starts running the given process in the background. `onStdout` `onStderr` and `onExit`
105 are callbacks to lua functions which will be called when the given actions happen
106 to the background process.
107 `userargs` are the arguments which will get passed to the callback functions
109 * `JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string)`:
110 Starts running the given shell command in the background. Note that the command execute
111 is first parsed by a shell when using this command. It is executed with `sh -c`.
113 * `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job process
115 * `JobStop(cmd *exec.Cmd)`: kill a job
117 This may seem like a small list of available functions but some of the objects
118 returned by the functions have many methods. `CurView()` returns a view object
119 which has all the actions which you can call. For example `CurView():Save(false)`.
120 You can see the full list of possible actions in the keybindings help topic.
121 The boolean on all the actions indicates whether or not the lua callbacks should
122 be run. I would recommend generally sticking to false when making a plugin to
123 avoid recursive problems, for example if you call `CurView():Save(true)` in `onSave()`.
124 Just use `CurView():Save(false)` so that it won't call `onSave()` again.
126 Using the view object, you can also access the buffer associated with that view
127 by using `CurView().Buf`, which lets you access the `FileType`, `Path`, `Name`...
129 The possible methods which you can call using the `messenger` variable are:
131 * `messenger.Message(msg ...interface{})`
132 * `messenger.Error(msg ...interface{})`
133 * `messenger.YesNoPrompt(prompt string) (bool, bool)`
134 * `messenger.Prompt(prompt, historyType string, completionType Completion) (string, bool)`
136 If you want a standard prompt, just use `messenger.Prompt(prompt, "", 0)`
138 # Adding help files, syntax files, or colorschemes in your plugin
140 You can use the `AddRuntimeFile(name, type, path string)` function to add various kinds of
141 files to your plugin. For example, if you'd like to add a help topic to your plugin
142 called `test`, you would create a `test.md` file, and call the function:
145 AddRuntimeFile("test", "help", "test.md")
148 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of files
150 To read the content of a runtime file use `ReadRuntimeFile(fileType, name string)`
151 or `ListRuntimeFiles(fileType string)` for all runtime files.
153 # Autocomplete command arguments
155 See this example to learn how to use `MakeCompletion` and `MakeCommand`
158 local function StartsWith(String,Start)
159 String = String:upper()
160 Start = Start:upper()
161 return string.sub(String,1,string.len(Start))==Start
164 function complete(input)
165 local allCompletions = {"Hello", "World", "Foo", "Bar"}
168 for i,v in pairs(allCompletions) do
169 if StartsWith(v, input) then
170 table.insert(result, v)
177 messenger:Message(arg)
180 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
185 For examples of plugins, see the default `autoclose` and `linter` plugins
186 (stored in the normal micro core repo under `runtime/plugins`) as well as
187 any plugins that are stored in the official channel [here](https://github.com/micro-editor/plugin-channel).
191 Micro also has a built in plugin manager which you can invoke with the `> plugin ...` command.
193 For the valid commands you can use, see the `command` help topic.
195 The manager fetches plugins from the channels (which is simply a list of plugin metadata)
196 which it knows about. By default, micro only knows about the official channel which is located
197 at github.com/micro-editor/plugin-channel but you can add your own third-party channels using
198 the `pluginchannels` option and you can directly link third-party plugins to allow installation
199 through the plugin manager with the `pluginrepos` option.
201 If you'd like to publish a plugin you've made as an official plugin, you should upload your
202 plugin online (to Github preferably) and add a `repo.json` file. This file will contain the
203 metadata for your plugin. Here is an example:
207 "Name": "pluginname",
208 "Description": "Here is a nice concise description of my plugin",
209 "Tags": ["python", "linting"],
213 "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
222 Then open a pull request at github.com/micro-editor/plugin-channel adding a link to the
223 raw `repo.json` that is in your plugin repository.
224 To make updating the plugin work, the first line of your plugins lua code should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`)
225 Please make sure to use [semver](http://semver.org/) for versioning.