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(view)`. For example a function which is run every time the user saves
  10 the buffer would be:
  11
  12 ```lua
  13 function onSave(view)
  14     ...
  15     return false
  16 end
  17 ```
  18
  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.
  21
  22 All available actions are listed in the keybindings section of the help.
  23
  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.
  26
  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.
  31
  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.
  36
  37 ---
  38
  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):
  42
  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`...)
  45
  46 * `tabs`: a list of all the tabs currently in use
  47
  48 * `curTab`: the index of the current tabs in the tabs list
  49
  50 * `messenger`: lets you send messages to the user or create prompts
  51
  52 * `GetOption(name string)`: returns the value of the requested option
  53
  54 * `AddOption(name string, value interface{})`: sets the given option with the given
  55    value (`interface{}` means any type in Go)
  56
  57 * `SetOption(option, value string)`: sets the given option to the value. This will
  58    set the option globally, unless it is a local only option.
  59
  60 * `SetLocalOption(option, value string, buffer *Buffer)`: sets the given option to
  61    the value locally in the given buffer
  62
  63 * `BindKey(key, action string)`: binds `key` to `action`
  64
  65 * `MakeCommand(name, function string, completions ...Completion)`:
  66    creates a command with `name` which will call `function` when executed.
  67    Use 0 for completions to get NoCompletion.
  68
  69 * `MakeCompletion(function string)`:
  70    creates a `Completion` to use with `MakeCommand`
  71
  72 * `CurView()`: returns the current view
  73
  74 * `HandleCommand(cmd string)`: runs the given command
  75
  76 * `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`: runs the given shell
  77    command. The `interactive` bool specifies whether the command should run in the background. The
  78    `waitToClose` bool only applies if `interactive` is true and means that it should wait before
  79    returning to the editor.
  80
  81 * `JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string)`:
  82    Starts running the given shell command in the background. `onStdout` `onStderr` and `onExit`
  83    are callbacks to lua functions which will be called when the given actions happen
  84    to the background process.
  85    `userargs` are the arguments which will get passed to the callback functions
  86
  87 * `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job process
  88
  89 * `JobStop(cmd *exec.Cmd)`: kill a job
  90
  91 This may seem like a small list of available functions but some of the objects
  92 returned by the functions have many methods. `CurView()` returns a view object
  93 which has all the actions which you can call. For example `CurView():Save(false)`.
  94 You can see the full list of possible actions in the keybindings help topic.
  95 The boolean on all the actions indicates whether or not the lua callbacks should
  96 be run. I would recommend generally sticking to false when making a plugin to
  97 avoid recursive problems, for example if you call `CurView():Save(true)` in `onSave()`.
  98 Just use `CurView():Save(false)` so that it won't call `onSave()` again.
  99
 100 Using the view object, you can also access the buffer associated with that view
 101 by using `CurView().Buf`, which lets you access the `FileType`, `Path`, `Name`...
 102
 103 The possible methods which you can call using the `messenger` variable are:
 104
 105 * `messenger.Message(msg ...interface{})`
 106 * `messenger.Error(msg ...interface{})`
 107 * `messenger.YesNoPrompt(prompt string) (bool, bool)`
 108 * `messenger.Prompt(prompt, historyType string, completionType Completion) (string, bool)`
 109
 110 If you want a standard prompt, just use `messenger.Prompt(prompt, "", 0)`
 111
 112 # Adding help files, syntax files, or colorschemes in your plugin
 113
 114 You can use the `AddRuntimeFile(name, type, path string)` function to add various kinds of
 115 files to your plugin. For example, if you'd like to add a help topic and to your plugin
 116 called `test`, you would create the `test.md` file for example, and runt the function:
 117
 118 ```lua
 119 AddRuntimeFile("test", "help", "test.md")
 120 ```
 121
 122 # Autocomplete command arguments
 123
 124 See this example to learn how to use `MakeCompletion` and `MakeCommand`
 125
 126 ```lua
 127 local function StartsWith(String,Start)
 128   String = String:upper()
 129   Start = Start:upper()
 130   return string.sub(String,1,string.len(Start))==Start
 131 end
 132
 133 function complete(input)
 134   local allCompletions = {"Hello", "World", "Foo", "Bar"}
 135   local result = {}
 136
 137   for i,v in pairs(allCompletions) do
 138   if StartsWith(v, input) then
 139        table.insert(result, v)
 140      end
 141    end
 142    return result
 143 end
 144
 145 function foo(arg)
 146   messenger:Message(arg)
 147 end
 148
 149 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
 150 ```
 151
 152 # Default plugins
 153
 154 For examples of plugins, see the default plugins `linter`, `go`, and `autoclose`.
 155 They are stored in Micro's GitHub repository [here](https://github.com/zyedidia/micro/tree/master/runtime/plugins).