runtime/help/plugins.md

   1 # Plugins
   2
   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:
  10
  11 ```
  12 ~/.config/micro/plug/go-plugin
  13     go.lua
  14     info.json
  15 ```
  16
  17 info.json:
  18 ```
  19 {
  20     "name": "go",
  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",
  24     "version": "1.0.0",
  25     "require": [
  26         "micro >= 2.0.0"
  27     ]
  28 }
  29 ```
  30
  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
  36 provides information.
  37
  38 ## Lua callbacks
  39
  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
  43 which micro defines:
  44
  45 * `init()`: this function should be used for your plugin initialization.
  46
  47 * `onBufferOpen(buf)`: runs when a buffer is opened. The input contains
  48    the buffer object.
  49
  50 * `onBufPaneOpen(bufpane)`: runs when a bufpane is opened. The input
  51    contains the bufpane object.
  52
  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.
  57
  58 * `preAction(bufpane)`: runs immediately before `Action` is triggered
  59    by the user. Returns a boolean which defines whether the action should
  60    be canceled.
  61
  62 For example a function which is run every time the user saves the buffer
  63 would be:
  64
  65 ```lua
  66 function onSave(bp)
  67     ...
  68     return false
  69 end
  70 ```
  71
  72 The `bp` variable is a reference to the bufpane the action is being executed within.
  73 This is almost always the current bufpane.
  74
  75 All available actions are listed in the keybindings section of the help.
  76
  77 For callbacks to mouse actions, you are also given the event info:
  78
  79 ```lua
  80 function onMousePress(view, event)
  81     local x, y = event:Position()
  82
  83     return false
  84 end
  85 ```
  86
  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.
  89
  90 ## Accessing micro functions
  91
  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:
  95
  96 ```lua
  97 local micro = import("micro")
  98 micro.Log("Hello")
  99 ```
 100
 101 The packages and functions are listed below:
 102
 103 * `micro`
 104     - `TermMessage(msg interface{}...)`
 105     - `TermError()`
 106     - `InfoBar()`
 107     - `Log(msg interface{}...)`
 108     - `SetStatusInfoFn`
 109 * `micro/config`
 110     - `MakeCommand`
 111     - `FileComplete`
 112     - `HelpComplete`
 113     - `OptionComplete`
 114     - `OptionValueComplete`
 115     - `NoComplete`
 116     - `TryBindKey`
 117     - `Reload`
 118     - `AddRuntimeFilesFromDirectory`
 119     - `AddRuntimeFileFromMemory`
 120     - `AddRuntimeFile`
 121     - `ListRuntimeFiles`
 122     - `ReadRuntimeFile`
 123     - `RTColorscheme`
 124     - `RTSyntax`
 125     - `RTHelp`
 126     - `RTPlugin`
 127     - `RegisterCommonOption`
 128     - `RegisterGlobalOption`
 129 * `micro/shell`
 130     - `ExecCommand`
 131     - `RunCommand`
 132     - `RunBackgroundShell`
 133     - `RunInteractiveShell`
 134     - `JobStart`
 135     - `JobSpawn`
 136     - `JobStop`
 137     - `JobStop`
 138     - `RunTermEmulator`
 139     - `TermEmuSupported`
 140 * `micro/buffer`
 141     - `NewMessage`
 142     - `NewMessageAtLine`
 143     - `MTInfo`
 144     - `MTWarning`
 145     - `MTError`
 146     - `Loc`
 147     - `BTDefault`
 148     - `BTLog`
 149     - `BTRaw`
 150     - `BTInfo`
 151     - `NewBufferFromFile`
 152     - `ByteOffset`
 153 * `micro/util`
 154     - `RuneAt`
 155     - `GetLeadingWhitespace`
 156     - `IsWordChar`
 157
 158
 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
 163 with `bp:Save()`.
 164
 165 Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax.
 166
 167 ```go
 168 micro.InfoBar().Message()
 169 ```
 170
 171 turns to
 172
 173 ```lua
 174 micro.InfoBar():Message()
 175 ```
 176
 177 ## Accessing the Go standard library
 178
 179 It is possible for your lua code to access many of the functions in the Go
 180 standard library.
 181
 182 Simply import the package you'd like and then you can use it. For example:
 183
 184 ```lua
 185 local ioutil = import("io/ioutil")
 186 local fmt = import("fmt")
 187 local micro = import("micro")
 188
 189 local data, err = ioutil.ReadFile("SomeFile.txt")
 190
 191 if err ~= nil then
 192     micro.InfoBar():Error("Error reading file: SomeFile.txt")
 193 else
 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)
 197
 198     -- Do something with the file you just read!
 199     -- ...
 200 end
 201 ```
 202
 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).
 207
 208 ```
 209 fmt
 210 io
 211 io/ioutil
 212 net
 213 math
 214 math/rand
 215 os
 216 runtime
 217 path
 218 filepath
 219 strings
 220 regexp
 221 errors
 222 time
 223 ```
 224
 225 For documentation for each of these functions, you can simply look
 226 through the Go standard library documentation.
 227
 228 ## Adding help files, syntax files, or colorschemes in your plugin
 229
 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
 233 the function:
 234
 235 ```lua
 236 AddRuntimeFile("test", "help", "test.md")
 237 ```
 238
 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.
 243
 244 ## Autocomplete command arguments
 245
 246 See this example to learn how to use `MakeCompletion` and `MakeCommand`
 247
 248 ```lua
 249 local function StartsWith(String,Start)
 250     String = String:upper()
 251     Start = Start:upper()
 252     return string.sub(String,1,string.len(Start))==Start
 253 end
 254
 255 function complete(input)
 256     local allCompletions = {"Hello", "World", "Foo", "Bar"}
 257     local result = {}
 258
 259     for i,v in pairs(allCompletions) do
 260         if StartsWith(v, input) then
 261             table.insert(result, v)
 262         end
 263     end
 264     return result
 265 end
 266
 267 function foo(arg)
 268     messenger:Message(arg)
 269 end
 270
 271 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
 272 ```
 273
 274 ## Default plugins
 275
 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).
 280
 281 ## Plugin Manager
 282
 283 Micro also has a built in plugin manager which you can invoke with the
 284 `> plugin ...` command.
 285
 286 For the valid commands you can use, see the `commands` help topic.
 287
 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.
 294
 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:
 298
 299 ```json
 300 [{
 301   "Name": "pluginname",
 302   "Description": "Here is a nice concise description of my plugin",
 303   "Tags": ["python", "linting"],
 304   "Versions": [
 305     {
 306       "Version": "1.0.0",
 307       "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
 308       "Require": {
 309         "micro": ">=1.0.3"
 310       }
 311     }
 312   ]
 313 }]
 314 ```
 315
 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.