runtime/help/plugins.md

   1 # Plugins
   2
   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`.
   6
   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()`. For example a function which is run every time the user saves
  10 the buffer would be:
  11
  12 ```lua
  13 function onSave()
  14     ...
  15     return false
  16 end
  17 ```
  18
  19 All available actions are listed in the keybindings section of the help.
  20
  21 These functions should also return a boolean specifying whether the view
  22 should be relocated to the cursor or not after the action is complete.
  23
  24 Note that these callbacks occur after the action has been completed. If you
  25 want a callback before the action is executed, use `preAction()`. In this case
  26 the boolean returned specifies whether or not the action should be executed
  27 after the lua code completes.
  28
  29 ---
  30
  31 There are a number of functions and variables that are available to you in
  32 oder to access the inner workings of micro. Here is a list (the type signatures
  33 for functions are given using Go's type system):
  34
  35 * OS: variable which gives the OS micro is currently running on (this is the same
  36 as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...)
  37
  38 * tabs: a list of all the tabs currently in use
  39
  40 * curTab: the index of the current tabs in the tabs list
  41
  42 * messenger: lets you send messages to the user or create prompts
  43
  44 * GetOption(name string): returns the value of the requested option
  45
  46 * AddOption(name string, value interface{}): sets the given option with the given
  47 value (`interface{}` means any type in Go).
  48
  49 * BindKey(key, action string): binds `key` to `action`.
  50
  51 * MakeCommand(name, function string): creates a command with `name` which will
  52 call `function` when executed.
  53
  54 * CurView(): returns the current view
  55
  56 * HandleCommand(cmd string): runs the given command
  57
  58 * HandleShellCommand(shellCmd string, interactive bool): runs the given shell
  59 command
  60
  61 // Used for asynchronous jobs
  62 * JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string):
  63 Starts running the given shell command in the background. `onStdout` `onStderr` and `onExit`
  64 are callbacks to lua functions which will be called when the given actions happen
  65 to the background process.
  66 `userargs` are the arguments which will get passed to the callback functions
  67
  68 * JobSend(cmd *exec.Cmd, data string): send a string into the stdin of the job process
  69
  70 * JobStop(cmd *exec.Cmd): kill a job
  71
  72 This may seem like a small list of available functions but some of the objects
  73 returned by the functions have many methods. `CurView()` returns a view object
  74 which has all the actions which you can call. For example `CurView():Save()`.