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     repo.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 ## 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
  73 within.  This is almost always the current bufpane.
  74
  75 All available actions are listed in the keybindings section of the help.
  76
  77 These functions should also return a boolean specifying whether the bufpane
  78 should be relocated to the cursor or not after the action is complete.
  79
  80 ## Accessing micro functions
  81
  82 Some of micro's internal information is exposed in the form of packages which
  83 can be imported by Lua plugins. A package can be imported in Lua and a value
  84 within it can be accessed using the following syntax:
  85
  86 ```lua
  87 local micro = import("micro")
  88 micro.Log("Hello")
  89 ```
  90
  91 The packages and functions are listed below (in Go type signatures):
  92
  93 * `micro`
  94     - `TermMessage(msg interface{}...)`: temporarily close micro and print a
  95        message
  96
  97     - `TermError(filename string, lineNum int, err string)`: temporarily close
  98        micro and print an error formatted as `filename, lineNum: err`.
  99
 100     - `InfoBar()`: return the infobar BufPane object.
 101
 102     - `Log(msg interface{}...)`: write a message to `log.txt` (requires
 103        `-debug` flag, or binary built with `build-dbg`).
 104
 105     - `SetStatusInfoFn(fn string)`: register the given lua function as
 106        accessible from the statusline formatting options.
 107
 108     - `CurPane() *BufPane`: returns the current BufPane, or nil if the
 109        current pane is not a BufPane.
 110
 111     - `CurTab() *Tab`: returns the current tab.
 112 * `micro/config`
 113         - `MakeCommand(name string, action func(bp *BufPane, args[]string),
 114                    completer buffer.Completer)`:
 115        create a command with the given name, and lua callback function when
 116        the command is run. A completer may also be given to specify how
 117        autocompletion should work with the custom command.
 118
 119         - `FileComplete`: autocomplete using files in the current directory
 120         - `HelpComplete`: autocomplete using names of help documents
 121         - `OptionComplete`: autocomplete using names of options
 122         - `OptionValueComplete`: autocomplete using names of options, and valid
 123        values afterwards
 124         - `NoComplete`: no autocompletion suggestions
 125
 126         - `TryBindKey(k, v string, overwrite bool) (bool, error)`: bind the key
 127        `k` to the string `v` in the `bindings.json` file.  If `overwrite` is
 128        true, this will overwrite any existing binding to key `k`. Returns true
 129        if the binding was made, and a possible error (for example writing to
 130        `bindings.json` can cause an error).
 131
 132         - `Reload()`: reload configuration files.
 133
 134         - `AddRuntimeFileFromMemory(filetype RTFiletype, filename, data string)`:
 135        add a runtime file to the `filetype` runtime filetype, with name
 136        `filename` and data `data`.
 137
 138         - `AddRuntimeFilesFromDirectory(plugin string, filetype RTFiletype,
 139                                     directory, pattern string)`:
 140        add runtime files for the given plugin with the given RTFiletype from
 141        a directory within the plugin root. Only adds files that match the
 142        pattern using Go's `filepath.Match`
 143
 144         - `AddRuntimeFile(plugin string, filetype RTFiletype, filepath string)`:
 145        add a given file inside the plugin root directory as a runtime file
 146        to the given RTFiletype category.
 147
 148         - `ListRuntimeFiles(fileType RTFiletype) []string`: returns a list of
 149        names of runtime files of the given type.
 150
 151         - `ReadRuntimeFile(fileType RTFiletype, name string) string`: returns the
 152        contents of a given runtime file.
 153
 154         - `NewRTFiletype() int`: creates a new RTFiletype, and returns its value.
 155
 156         - `RTColorscheme`: runtime files for colorschemes.
 157         - `RTSyntax`: runtime files for syntax files.
 158         - `RTHelp`: runtime files for help documents.
 159         - `RTPlugin`: runtime files for plugin source code.
 160
 161         - `RegisterCommonOption(pl string, name string, defaultvalue interface{})`:
 162        registers a new option with for the given plugin. The name of the
 163        option will be `pl.name`, and will have the given default value. Since
 164        this registers a common option, the option will be modifiable on a
 165        per-buffer basis, while also having a global value (in the
 166        GlobalSettings map).
 167
 168         - `RegisterGlobalOption(pl string, name string, defaultvalue interface{})`:
 169        same as `RegisterCommonOption` but the option cannot be modified
 170        locally to each buffer.
 171
 172         - `GetGlobalOption(name string) interface{}`: returns the value of a
 173        given plugin in the `GlobalSettings` map.
 174
 175         - `SetGlobalOption(option, value string) error`: sets an option to a
 176        given value. Same as using the `> set` command. This will parse the
 177        value to the actual value type.
 178
 179         - `SetGlobalOptionNative(option string, value interface{}) error`: sets
 180        an option to a given value, where the type of value is the actual
 181        type of the value internally.
 182 * `micro/shell`
 183         - `ExecCommand(name string, arg ...string) (string, error)`: runs an
 184        executable with the given arguments, and pipes the output (stderr
 185        and stdout) of the executable to an internal buffer, which is
 186        returned as a string, along with a possible error.
 187
 188         - `RunCommand(input string) (string, error)`: same as `ExecCommand`,
 189        except this uses micro's argument parser to parse the arguments from
 190        the input. For example `cat 'hello world.txt' file.txt`, will pass
 191        two arguments in the `ExecCommand` argument list (quoting arguments
 192        will preserve spaces).
 193
 194         - `RunBackgroundShell(input string) (func() string, error)`: returns a
 195        function that will run the given shell command and return its output.
 196
 197         - `RunInteractiveShell(input string, wait bool, getOutput bool)
 198                           (string, error)`:
 199        temporarily closes micro and runs the given command in the terminal.
 200        If `wait` is true, micro will wait for the user to press enter before
 201        returning to text editing. If `getOutput` is true, micro redirect
 202        stdout from the command to the returned string.
 203
 204         - `JobStart(cmd string, onStdout, onStderr,
 205                 onExit func(string, []interface{}), userargs ...interface{})
 206                 *exec.Cmd`:
 207        Starts a background job by running the shell on the given command
 208        (using `sh -c`). Three callbacks can be provided which will be called
 209        when the command generates stdout, stderr, or exits. The userargs will
 210        be passed to the callbacks, along with the output as the first
 211        argument of the callback.
 212
 213         - `JobSpawn(cmd string, cmdArgs []string, onStdout, onStderr,
 214                 onExit func(string, []interface{}), userargs ...interface{})
 215                 *exec.Cmd`:
 216        same as `JobStart`, except doesn't run the command through the shell
 217        and instead takes as inputs the list of arguments.
 218
 219         - `JobStop(cmd *exec.Cmd)`: kills a job.
 220         - `JobSend(cmd *exec.Cmd, data string)`: sends some data to a job's stdin.
 221
 222         - `RunTermEmulator(h *BufPane, input string, wait bool, getOutput bool,
 223                        callback func(out string, userargs []interface{}),
 224                        userargs []interface{}) error`:
 225        starts a terminal emulator from a given BufPane with the input command.
 226        If `wait` is true it will wait for the user to exit by pressing enter
 227        once the executable has terminated and if `getOutput` is true it will
 228        redirect the stdout of the process to a pipe which will be passed to
 229        the callback which is a function that takes a string and a list of
 230        optional user arguments. This function returns an error on systems
 231        where the terminal emulator is not supported.
 232
 233         - `TermEmuSupported`: true on systems where the terminal emulator is
 234        supported and false otherwise. Supported systems:
 235         * Linux
 236         * MacOS
 237         * Dragonfly
 238         * OpenBSD
 239         * FreeBSD
 240
 241 * `micro/buffer`
 242     - `NewMessage(owner string, msg string, start, end, Loc, kind MsgType)
 243                   *Message`:
 244        creates a new message with an owner over a range given by the start
 245        and end locations.
 246
 247     - `NewMessageAtLine(owner string, msg string, line int, kindMsgType)
 248                         *Message`:
 249        creates a new message with owner, type and message at a given line.
 250
 251     - `MTInfo`: info message.
 252     - `MTWarning`: warning message.
 253     - `MTError` error message.
 254
 255     - `Loc(x, y int) Loc`: creates a new location struct.
 256
 257     - `BTDefault`: default buffer type.
 258     - `BTLog`: log buffer type.
 259     - `BTRaw`: raw buffer type.
 260     - `BTInfo`: info buffer type.
 261
 262     - `NewBuffer(text, path string) *Buffer`: creates a new buffer with the
 263        given text at a certain path.
 264
 265     - `NewBufferFromFile(path string) (*Buffer, error)`: creates a new
 266        buffer by reading from disk at the given path.
 267
 268     - `ByteOffset(pos Loc, buf *Buffer) int`: returns the byte index of the
 269        given position in a buffer.
 270
 271     - `Log(s string)`: writes a string to the log buffer.
 272     - `LogBuf() *Buffer`: returns the log buffer.
 273 * `micro/util`
 274     - `RuneAt(str string, idx int) string`: returns the utf8 rune at a
 275        given index within a string.
 276     - `GetLeadingWhitespace(s string) string`: returns the leading
 277        whitespace of a string.
 278     - `IsWordChar(s string) bool`: returns true if the first rune in a
 279        string is a word character.
 280     - `String(b []byte) string`: converts a byte array to a string.
 281     - `RuneStr(r rune) string`: converts a rune to a string.
 282
 283 This may seem like a small list of available functions but some of the objects
 284 returned by the functions have many methods. The Lua plugin may access any
 285 public methods of an object returned by any of the functions above.
 286 Unfortunately it is not possible to list all the available functions on this
 287 page. Please go to the internal documentation at
 288 https://godoc.org/github.com/zyedidia/micro to see the full list of available
 289 methods. Note that only methods of types that are available to plugins via
 290 the functions above can be called from a plugin.  For an even more detailed
 291 reference see the source code on Github.
 292
 293 For example, with a BufPane object called `bp`, you could call the `Save`
 294 function in Lua with `bp:Save()`.
 295
 296 Note that Lua uses the `:` syntax to call a function rather than Go's `.`
 297 syntax.
 298
 299 ```go
 300 micro.InfoBar().Message()
 301 ```
 302
 303 turns to
 304
 305 ```lua
 306 micro.InfoBar():Message()
 307 ```
 308
 309 ## Accessing the Go standard library
 310
 311 It is possible for your lua code to access many of the functions in the Go
 312 standard library.
 313
 314 Simply import the package you'd like and then you can use it. For example:
 315
 316 ```lua
 317 local ioutil = import("io/ioutil")
 318 local fmt = import("fmt")
 319 local micro = import("micro")
 320
 321 local data, err = ioutil.ReadFile("SomeFile.txt")
 322
 323 if err ~= nil then
 324     micro.InfoBar():Error("Error reading file: SomeFile.txt")
 325 else
 326     -- Data is returned as an array of bytes
 327     -- Using Sprintf will convert it to a string
 328     local str = fmt.Sprintf("%s", data)
 329
 330     -- Do something with the file you just read!
 331     -- ...
 332 end
 333 ```
 334
 335 Here are the packages from the Go standard library that you can access.
 336 Nearly all functions from these packages are supported. For an exact
 337 list of which functions are supported you can look through `lua.go`
 338 (which should be easy to understand).
 339
 340 ```
 341 fmt
 342 io
 343 io/ioutil
 344 net
 345 math
 346 math/rand
 347 os
 348 runtime
 349 path
 350 filepath
 351 strings
 352 regexp
 353 errors
 354 time
 355 ```
 356
 357 For documentation for each of these functions, see the Go standard
 358 library documentation at https://golang.org/pkg/ (for the packages
 359 exposed to micro plugins). The Lua standard library is also available
 360 to plugins though it is rather small.
 361
 362 The following functions are also available from the go-humanize package:
 363
 364 The `humanize` package exposes:
 365 * `Bytes`
 366 * `Ordinal`
 367 * `Ftoa`
 368 * `FtoaWithDigits`
 369
 370 ## Adding help files, syntax files, or colorschemes in your plugin
 371
 372 You can use the `AddRuntimeFile(name string, type config.RTFiletype,
 373                                 path string)`
 374 function to add various kinds of files to your plugin. For example, if you'd
 375 like to add a help topic to your plugin called `test`, you would create a
 376 `test.md` file, and call the function:
 377
 378 ```lua
 379 config = import("micro/config")
 380 config.AddRuntimeFile("test", config.RTHelp, "test.md")
 381 ```
 382
 383 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of
 384 files to the runtime. To read the content of a runtime file use
 385 `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)`
 386 for all runtime files. In addition, there is `AddRuntimeFileFromMemory` which
 387 adds a runtime file based on a string that may have been constructed at
 388 runtime.
 389
 390 ## Default plugins
 391
 392 There are 6 default plugins that come pre-installed with micro. These are
 393
 394 * `autoclose`: automatically closes brackets, quotes, etc...
 395 * `comment`: provides automatic commenting for a number of languages
 396 * `ftoptions`: alters some default options depending on the filetype
 397 * `linter`: provides extensible linting for many languages
 398 * `literate`: provides advanced syntax highlighting for the Literate
 399    programming tool.
 400 * `status`: provides some extensions to the status line (integration with
 401    Git and more).
 402 * `diff`: integrates the `diffgutter` option with Git. If you are in a Git
 403    directory, the diff gutter will show changes with respect to the most
 404    recent Git commit rather than the diff since opening the file.
 405
 406 See `> help linter`, `> help comment`, and `> help status` for additional
 407 documentation specific to those plugins.
 408
 409 These are good examples for many use-cases if you are looking to write
 410 your own plugins.
 411
 412 ## Plugin Manager
 413
 414 Micro also has a built in plugin manager which you can invoke with the
 415 `> plugin ...` command, or in the shell with `micro -plugin ...`.
 416
 417 For the valid commands you can use, see the `command` help topic.
 418
 419 The manager fetches plugins from the channels (which is simply a list of plugin
 420 metadata) which it knows about. By default, micro only knows about the official
 421 channel which is located at github.com/micro-editor/plugin-channel but you can
 422 add your own third-party channels using the `pluginchannels` option and you can
 423 directly link third-party plugins to allow installation through the plugin
 424 manager with the `pluginrepos` option.
 425
 426 If you'd like to publish a plugin you've made as an official plugin, you should
 427 upload your plugin online (to Github preferably) and add a `repo.json` file.
 428 This file will contain the metadata for your plugin. Here is an example:
 429
 430 ```json
 431 [{
 432   "Name": "pluginname",
 433   "Description": "Here is a nice concise description of my plugin",
 434   "Website": "https://github.com/user/plugin",
 435   "Tags": ["python", "linting"],
 436   "Versions": [
 437     {
 438       "Version": "1.0.0",
 439       "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
 440       "Require": {
 441         "micro": ">=1.0.3"
 442       }
 443     }
 444   ]
 445 }]
 446 ```
 447
 448 Then open a pull request at github.com/micro-editor/plugin-channel adding a
 449 link to the raw `repo.json` that is in your plugin repository.
 450
 451 To make updating the plugin work, the first line of your plugins lua code
 452 should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`)
 453 Please make sure to use [semver](http://semver.org/) for versioning.