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     help/
  16         go-plugin.md
  17 ```
  18
  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:
  25
  26 * Colorschemes
  27 * Syntax files
  28 * Help files
  29 * Plugin files
  30 * Syntax header files
  31
  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.
  37
  38 # Info file
  39
  40 The `info.json` for the Go plugin is the following:
  41
  42 ```
  43 {
  44     "name": "go",
  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",
  48     "version": "1.0.0",
  49     "require": [
  50         "micro >= 2.0.0"
  51     ]
  52 }
  53 ```
  54
  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
  60 provides information.
  61
  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.
  65
  66 ## Lua callbacks
  67
  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
  71 which micro defines:
  72
  73 * `init()`: this function should be used for your plugin initialization.
  74
  75 * `onBufferOpen(buf)`: runs when a buffer is opened. The input contains
  76    the buffer object.
  77
  78 * `onBufPaneOpen(bufpane)`: runs when a bufpane is opened. The input
  79    contains the bufpane object.
  80
  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.
  85
  86 * `preAction(bufpane)`: runs immediately before `Action` is triggered
  87    by the user. Returns a boolean which defines whether the action should
  88    be canceled.
  89
  90 For example a function which is run every time the user saves the buffer
  91 would be:
  92
  93 ```lua
  94 function onSave(bp)
  95     ...
  96     return false
  97 end
  98 ```
  99
 100 The `bp` variable is a reference to the bufpane the action is being executed within.
 101 This is almost always the current bufpane.
 102
 103 All available actions are listed in the keybindings section of the help.
 104
 105 For callbacks to mouse actions, you are also given the event info:
 106
 107 ```lua
 108 function onMousePress(view, event)
 109     local x, y = event:Position()
 110
 111     return false
 112 end
 113 ```
 114
 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.
 117
 118 ## Accessing micro functions
 119
 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:
 123
 124 ```lua
 125 local micro = import("micro")
 126 micro.Log("Hello")
 127 ```
 128
 129 The packages and functions are listed below (in Go type signatures):
 130
 131 * `micro`
 132     - `TermMessage(msg interface{}...)`
 133     - `TermError()`
 134     - `InfoBar()`
 135     - `Log(msg interface{}...)`
 136     - `SetStatusInfoFn(fn string)`
 137 * `micro/config`
 138     - `MakeCommand`
 139     - `FileComplete`
 140     - `HelpComplete`
 141     - `OptionComplete`
 142     - `OptionValueComplete`
 143     - `NoComplete`
 144     - `TryBindKey`
 145     - `Reload`
 146     - `AddRuntimeFilesFromDirectory`
 147     - `AddRuntimeFileFromMemory`
 148     - `AddRuntimeFile`
 149     - `ListRuntimeFiles`
 150     - `ReadRuntimeFile`
 151     - `RTColorscheme`
 152     - `RTSyntax`
 153     - `RTHelp`
 154     - `RTPlugin`
 155     - `RegisterCommonOption`
 156     - `RegisterGlobalOption`
 157 * `micro/shell`
 158     - `ExecCommand`
 159     - `RunCommand`
 160     - `RunBackgroundShell`
 161     - `RunInteractiveShell`
 162     - `JobStart`
 163     - `JobSpawn`
 164     - `JobStop`
 165     - `JobStop`
 166     - `RunTermEmulator`
 167     - `TermEmuSupported`
 168 * `micro/buffer`
 169     - `NewMessage`
 170     - `NewMessageAtLine`
 171     - `MTInfo`
 172     - `MTWarning`
 173     - `MTError`
 174     - `Loc`
 175     - `BTDefault`
 176     - `BTLog`
 177     - `BTRaw`
 178     - `BTInfo`
 179     - `NewBufferFromFile`
 180     - `ByteOffset`
 181     - `Log`
 182     - `LogBuf`
 183 * `micro/util`
 184     - `RuneAt`
 185     - `GetLeadingWhitespace`
 186     - `IsWordChar`
 187
 188
 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.
 197
 198 For example, with a BufPane object called `bp`, you could call the `Save` function
 199 in Lua with `bp:Save()`.
 200
 201 Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax.
 202
 203 ```go
 204 micro.InfoBar().Message()
 205 ```
 206
 207 turns to
 208
 209 ```lua
 210 micro.InfoBar():Message()
 211 ```
 212
 213 ## Accessing the Go standard library
 214
 215 It is possible for your lua code to access many of the functions in the Go
 216 standard library.
 217
 218 Simply import the package you'd like and then you can use it. For example:
 219
 220 ```lua
 221 local ioutil = import("io/ioutil")
 222 local fmt = import("fmt")
 223 local micro = import("micro")
 224
 225 local data, err = ioutil.ReadFile("SomeFile.txt")
 226
 227 if err ~= nil then
 228     micro.InfoBar():Error("Error reading file: SomeFile.txt")
 229 else
 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)
 233
 234     -- Do something with the file you just read!
 235     -- ...
 236 end
 237 ```
 238
 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).
 243
 244 ```
 245 fmt
 246 io
 247 io/ioutil
 248 net
 249 math
 250 math/rand
 251 os
 252 runtime
 253 path
 254 filepath
 255 strings
 256 regexp
 257 errors
 258 time
 259 ```
 260
 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.
 265
 266 ## Adding help files, syntax files, or colorschemes in your plugin
 267
 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:
 272
 273 ```lua
 274 config = import("micro/config")
 275 config.AddRuntimeFile("test", config.RTHelp, "test.md")
 276 ```
 277
 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
 283 runtime.
 284
 285 ## Default plugins
 286
 287 There are 6 default plugins that come pre-installed with micro. These are
 288
 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
 294    programming tool.
 295 * `status`: provides some extensions to the status line (integration with
 296    Git and more).
 297
 298 These are good examples for many use-cases if you are looking to write
 299 your own plugins.
 300
 301 ## Plugin Manager
 302
 303 Micro also has a built in plugin manager which you can invoke with the
 304 `> plugin ...` command, or in the shell with `micro -plugin ...`.
 305
 306 For the valid commands you can use, see the `command` help topic.
 307
 308 The manager fetches plugins from the channels (which is simply a list of plugin
 309 metadata) which it knows about. By default, micro only knows about the official
 310 channel which is located at github.com/micro-editor/plugin-channel but you can
 311 add your own third-party channels using the `pluginchannels` option and you can
 312 directly link third-party plugins to allow installation through the plugin
 313 manager with the `pluginrepos` option.
 314
 315 If you'd like to publish a plugin you've made as an official plugin, you should
 316 upload your plugin online (to Github preferably) and add a `repo.json` file.
 317 This file will contain the metadata for your plugin. Here is an example:
 318
 319 ```json
 320 [{
 321   "Name": "pluginname",
 322   "Description": "Here is a nice concise description of my plugin",
 323   "Website": "https://github.com/user/plugin"
 324   "Tags": ["python", "linting"],
 325   "Versions": [
 326     {
 327       "Version": "1.0.0",
 328       "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
 329       "Require": {
 330         "micro": ">=1.0.3"
 331       }
 332     }
 333   ]
 334 }]
 335 ```
 336
 337 Then open a pull request at github.com/micro-editor/plugin-channel adding a link
 338 to the raw `repo.json` that is in your plugin repository.
 339
 340 To make updating the plugin work, the first line of your plugins lua code
 341 should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`)
 342 Please make sure to use [semver](http://semver.org/) for versioning.