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 * `configDir`: contains the path to the micro configuration files
  47
  48 * `tabs`: a list of all the tabs currently in use
  49
  50 * `curTab`: the index of the current tabs in the tabs list
  51
  52 * `messenger`: lets you send messages to the user or create prompts
  53
  54 * `RuneStr(r rune) string`: returns a string containing the given rune
  55
  56 * `Loc(x, y int) Loc`: returns a new `Loc` struct
  57
  58 * `JoinPaths(dir... string) string` combines multiple directories to a full path
  59
  60 * `DirectoryName(path string)` returns all but the last element of path ,typically the path's directory
  61
  62 * `GetOption(name string)`: returns the value of the requested option
  63
  64 * `AddOption(name string, value interface{})`: sets the given option with the given
  65    value (`interface{}` means any type in Go)
  66
  67 * `SetOption(option, value string)`: sets the given option to the value. This will
  68    set the option globally, unless it is a local only option.
  69
  70 * `SetLocalOption(option, value string, buffer *Buffer)`: sets the given option to
  71    the value locally in the given buffer
  72
  73 * `BindKey(key, action string)`: binds `key` to `action`
  74
  75 * `MakeCommand(name, function string, completions ...Completion)`:
  76    creates a command with `name` which will call `function` when executed.
  77    Use 0 for completions to get NoCompletion.
  78
  79 * `MakeCompletion(function string)`:
  80    creates a `Completion` to use with `MakeCommand`
  81
  82 * `CurView()`: returns the current view
  83
  84 * `HandleCommand(cmd string)`: runs the given command
  85
  86 * `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`: runs the given shell
  87    command. The `interactive` bool specifies whether the command should run in the background. The
  88    `waitToClose` bool only applies if `interactive` is true and means that it should wait before
  89    returning to the editor.
  90
  91 * `ToCharPos(loc Loc, buf *Buffer) int`: returns the character position of a given x, y location.
  92
  93 * `ByteOffset(loc Loc, buf *Buffer) int`: exactly like `ToCharPos` except it it counts bytes instead of runes.
  94
  95 * `JobSpawn(cmdName string, cmdArgs []string, onStdout, onStderr, onExit string, userargs ...string)`:
  96    Starts running the given process in the background. `onStdout` `onStderr` and `onExit`
  97    are callbacks to lua functions which will be called when the given actions happen
  98    to the background process.
  99    `userargs` are the arguments which will get passed to the callback functions
 100
 101 * `JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string)`:
 102    Starts running the given shell command in the background.
 103    This function is a shorthand for `JobSpawn`.
 104
 105 * `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job process
 106
 107 * `JobStop(cmd *exec.Cmd)`: kill a job
 108
 109 This may seem like a small list of available functions but some of the objects
 110 returned by the functions have many methods. `CurView()` returns a view object
 111 which has all the actions which you can call. For example `CurView():Save(false)`.
 112 You can see the full list of possible actions in the keybindings help topic.
 113 The boolean on all the actions indicates whether or not the lua callbacks should
 114 be run. I would recommend generally sticking to false when making a plugin to
 115 avoid recursive problems, for example if you call `CurView():Save(true)` in `onSave()`.
 116 Just use `CurView():Save(false)` so that it won't call `onSave()` again.
 117
 118 Using the view object, you can also access the buffer associated with that view
 119 by using `CurView().Buf`, which lets you access the `FileType`, `Path`, `Name`...
 120
 121 The possible methods which you can call using the `messenger` variable are:
 122
 123 * `messenger.Message(msg ...interface{})`
 124 * `messenger.Error(msg ...interface{})`
 125 * `messenger.YesNoPrompt(prompt string) (bool, bool)`
 126 * `messenger.Prompt(prompt, historyType string, completionType Completion) (string, bool)`
 127
 128 If you want a standard prompt, just use `messenger.Prompt(prompt, "", 0)`
 129
 130 # Adding help files, syntax files, or colorschemes in your plugin
 131
 132 You can use the `AddRuntimeFile(name, type, path string)` function to add various kinds of
 133 files to your plugin. For example, if you'd like to add a help topic and to your plugin
 134 called `test`, you would create the `test.md` file for example, and runt the function:
 135
 136 ```lua
 137 AddRuntimeFile("test", "help", "test.md")
 138 ```
 139
 140 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of files
 141 to the runtime.
 142
 143 # Autocomplete command arguments
 144
 145 See this example to learn how to use `MakeCompletion` and `MakeCommand`
 146
 147 ```lua
 148 local function StartsWith(String,Start)
 149   String = String:upper()
 150   Start = Start:upper()
 151   return string.sub(String,1,string.len(Start))==Start
 152 end
 153
 154 function complete(input)
 155   local allCompletions = {"Hello", "World", "Foo", "Bar"}
 156   local result = {}
 157
 158   for i,v in pairs(allCompletions) do
 159   if StartsWith(v, input) then
 160        table.insert(result, v)
 161      end
 162    end
 163    return result
 164 end
 165
 166 function foo(arg)
 167   messenger:Message(arg)
 168 end
 169
 170 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
 171 ```
 172
 173 # Default plugins
 174
 175 For examples of plugins, see the default `autoclose` and `linter` plugins
 176 (stored in the normal micro core repo under `runtime/plugins`) as well as
 177 any plugins that are stored in the official channel [here](https://github.com/micro-editor/plugin-channel).
 178
 179 # Plugin Manager
 180
 181 Micro also has a built in plugin manager which you can invoke with the `> plugin ...` command.
 182
 183 For the valid commands you can use, see the `command` help topic.
 184
 185 The manager fetches plugins from the channels (which is simply a list of plugin metadata)
 186 which it knows about. By default, micro only knows about the official channel which is located
 187 at github.com/micro-editor/plugin-channel but you can add your own third-party channels using
 188 the `pluginchannels` option and you can directly link third-party plugins to allow installation
 189 through the plugin manager with the `pluginrepos` option.
 190
 191 If you'd like to publish a plugin you've made as an official plugin, you should upload your
 192 plugin online (to Github preferably) and add a `repo.json` file. This file will contain the
 193 metadata for your plugin. Here is an example:
 194
 195 ```json
 196 [{
 197   "Name": "pluginname",
 198   "Description": "Here is a nice concise description of my plugin",
 199   "Tags": ["python", "linting"],
 200   "Versions": [
 201     {
 202       "Version": "1.0.0",
 203       "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
 204       "Require": {
 205         "micro": ">=1.0.3"
 206       }
 207     }
 208   ]
 209 }]
 210 ```
 211
 212 Then open a pull request at github.com/micro-editor/plugin-channel adding a link to the
 213 raw `repo.json` that is in your plugin repository.
 214 To make updating the plugin work, the first line of your plugins lua code should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`)
 215 Please make sure to use [semver](http://semver.org/) for versioning.