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 plugin to
   8 run code at times other than startup. The naming scheme is `onAction(view)`. For
   9 example a function which is run every time the user saves the buffer would be:
  10
  11 ```lua
  12 function onSave(view)
  13     ...
  14     return false
  15 end
  16 ```
  17
  18 The `view` variable is a reference to the view the action is being executed on.
  19 This is almost always the current view, which you can get with `CurView()` as
  20 well.
  21
  22 All available actions are listed in the keybindings section of the help.
  23
  24 For callbacks to mouse actions, you are also given the event info:
  25
  26 ```lua
  27 function onMousePress(view, event)
  28     local x, y = event:Position()
  29
  30     return false
  31 end
  32 ```
  33
  34 These functions should also return a boolean specifying whether the view should
  35 be relocated to the cursor or not after the action is complete.
  36
  37 Note that these callbacks occur after the action has been completed. If you want
  38 a callback before the action is executed, use `preAction()`. In this case the
  39 boolean returned specifies whether or not the action should be executed after
  40 the lua code completes.
  41
  42 Another useful callback to know about which is not an action is
  43 `onViewOpen(view)` which is called whenever a new view is opened and the new
  44 view is passed in. This is useful for setting local options based on the
  45 filetype, for example turning off `tabstospaces` only for Go files when they are
  46 opened.
  47
  48 ---
  49
  50 There are a number of functions and variables that are available to you in order
  51 to access the inner workings of micro. Here is a list (the type signatures for
  52 functions are given using Go's type system):
  53
  54 * `OS`: variable which gives the OS micro is currently running on (this is the
  55   same as Go's GOOS variable, so `darwin`, `windows`, `linux`, `freebsd`...)
  56
  57 * `configDir`: contains the path to the micro configuration files
  58
  59 * `tabs`: a list of all the tabs currently in use
  60
  61 * `curTab`: the index of the current tabs in the tabs list
  62
  63 * `messenger`: lets you send messages to the user or create prompts
  64
  65 * `NewBuffer(text, path string) *Buffer`: creates a new buffer from a given
  66    reader with a given path
  67
  68 * `GetLeadingWhitespace() bool`: returns the leading whitespace of the given
  69    string
  70
  71 * `IsWordChar(str string) bool`: returns whether or not the string is a 'word
  72    character'
  73
  74 * `RuneStr(r rune) string`: returns a string containing the given rune
  75
  76 * `Loc(x, y int) Loc`: returns a new `Loc` struct
  77
  78 * `WorkingDirectory() string`: returns a rooted path name to the current working
  79    directory
  80
  81 * `JoinPaths(dir... string) string`: combines multiple directories to a full
  82    path
  83
  84 * `DirectoryName(path string)`: returns all but the last element of path,
  85    typically the path's directory
  86
  87 * `GetOption(name string)`: returns the value of the requested option
  88
  89 * `AddOption(name string, value interface{})`: sets the given option with the
  90    given value (`interface{}` means any type in Go)
  91
  92 * `SetOption(option, value string)`: sets the given option to the value. This
  93    will set the option globally, unless it is a local only option.
  94
  95 * `SetLocalOption(option, value string, view *View)`: sets the given option to
  96    the value locally in the given buffer
  97
  98 * `BindKey(key, action string)`: binds `key` to `action`
  99
 100 * `MakeCommand(name, function string, completions ...Completion)`:
 101    creates a command with `name` which will call `function` when executed. Use 0
 102    for completions to get NoCompletion.
 103
 104 * `MakeCompletion(function string)`:
 105    creates a `Completion` to use with `MakeCommand`
 106
 107 * `CurView()`: returns the current view
 108
 109 * `HandleCommand(cmd string)`: runs the given command
 110
 111 * `HandleShellCommand(shellCmd string, interactive bool, waitToClose bool)`:
 112    runs the given shell command. The `interactive` bool specifies whether the
 113    command should run in the background. The `waitToClose` bool only applies if
 114    `interactive` is true and means that it should wait before returning to the
 115    editor.
 116
 117 * `ToCharPos(loc Loc, buf *Buffer) int`: returns the character position of a
 118    given x, y location
 119
 120 * `Reload`: (Re)load everything
 121
 122 * `ByteOffset(loc Loc, buf *Buffer) int`: exactly like `ToCharPos` except it it
 123    counts bytes instead of runes
 124
 125 * `JobSpawn(cmdName string, cmdArgs []string, onStdout, onStderr, onExit string, userargs ...string)`:
 126    Starts running the given process in the background. `onStdout` `onStderr` and
 127    `onExit` are callbacks to lua functions which will be called when the given
 128    actions happen to the background process. `userargs` are the arguments which
 129    will get passed to the callback functions
 130
 131 * `JobStart(cmd string, onStdout, onStderr, onExit string, userargs ...string)`:
 132    Starts running the given shell command in the background. Note that the
 133    command execute is first parsed by a shell when using this command. It is
 134    executed with `sh -c`.
 135
 136 * `JobSend(cmd *exec.Cmd, data string)`: send a string into the stdin of the job
 137    process
 138
 139 * `JobStop(cmd *exec.Cmd)`: kill a job
 140
 141 This may seem like a small list of available functions but some of the objects
 142 returned by the functions have many methods. `CurView()` returns a view object
 143 which has all the actions which you can call. For example
 144 `CurView():Save(false)`. You can see the full list of possible actions in the
 145 keybindings help topic. The boolean on all the actions indicates whether or not
 146 the lua callbacks should be run. I would recommend generally sticking to false
 147 when making a plugin to avoid recursive problems, for example if you call
 148 `CurView():Save(true)` in `onSave()`. Just use `CurView():Save(false)` so that
 149 it won't call `onSave()` again.
 150
 151 Using the view object, you can also access the buffer associated with that view
 152 by using `CurView().Buf`, which lets you access the `FileType`, `Path`,
 153 `Name`...
 154
 155 The possible methods which you can call using the `messenger` variable are:
 156
 157 * `messenger.Message(msg ...interface{})`
 158 * `messenger.Error(msg ...interface{})`
 159 * `messenger.YesNoPrompt(prompt string) (bool,bool)`
 160 * `messenger.Prompt(prompt, historyType string, completionType Completion) (string, bool)`
 161 * `messenger.AddLog(msg ...interface{})`
 162
 163 #### Note
 164
 165 Go function signatures use `.` and lua uses `:` so
 166
 167 ```go
 168 messenger.Message()
 169 ```
 170
 171 turns to
 172
 173 ```lua
 174 messenger:Message()
 175 ```
 176
 177 If you want a standard prompt, just use
 178
 179 ```lua
 180 messenger:Prompt(prompt, "", 0)
 181 ```
 182
 183 Debug or logging your plugin can be done with below lua example code.
 184
 185 ```lua
 186 messenger:AddLog("Message goes here ",pluginVariableToPrintHere)
 187 ```
 188
 189 In Micro to see your plugin logging output press `CtrlE` then type `log`, a
 190 logging window will open and any logging sent from your plugin will be displayed
 191 here.
 192
 193
 194 ## Accessing the Go standard library
 195
 196 It is possible for your lua code to access many of the functions in the Go
 197 standard library.
 198
 199 Simply import the package you'd like and then you can use it. For example:
 200
 201 ```lua
 202 local ioutil = import("io/ioutil")
 203 local fmt = import("fmt")
 204
 205 local data, err = ioutil.ReadFile("SomeFile.txt")
 206
 207 if err ~= nil then
 208     messenger:Error("Error reading file: SomeFile.txt")
 209 else
 210     -- Data is returned as an array of bytes
 211     -- Using Sprintf will convert it to a string
 212     local str = fmt.Sprintf("%s", data)
 213
 214     -- Do something with the file you just read!
 215     -- ...
 216 end
 217 ```
 218
 219 Here are the packages from the Go standard library that you can access.
 220 Nearly all functions from these packages are supported. For an exact
 221 list of which functions are supported you can look through `lua.go`
 222 (which should be easy to understand).
 223
 224 ```
 225 fmt
 226 io
 227 io/ioutil
 228 net
 229 math
 230 math/rand
 231 os
 232 runtime
 233 path
 234 filepath
 235 strings
 236 regexp
 237 errors
 238 time
 239 ```
 240
 241 For documentation for each of these functions, you can simply look
 242 through the Go standard library documentation.
 243
 244 ## Adding help files, syntax files, or colorschemes in your plugin
 245
 246 You can use the `AddRuntimeFile(name, type, path string)` function to add
 247 various kinds of files to your plugin. For example, if you'd like to add a help
 248 topic to your plugin called `test`, you would create a `test.md` file, and call
 249 the function:
 250
 251 ```lua
 252 AddRuntimeFile("test", "help", "test.md")
 253 ```
 254
 255 Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of
 256 files to the runtime. To read the content of a runtime file use
 257 `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)`
 258 for all runtime files.
 259
 260
 261 ## Autocomplete command arguments
 262
 263 See this example to learn how to use `MakeCompletion` and `MakeCommand`
 264
 265 ```lua
 266 local function StartsWith(String,Start)
 267     String = String:upper()
 268     Start = Start:upper()
 269     return string.sub(String,1,string.len(Start))==Start
 270 end
 271
 272 function complete(input)
 273     local allCompletions = {"Hello", "World", "Foo", "Bar"}
 274     local result = {}
 275
 276     for i,v in pairs(allCompletions) do
 277         if StartsWith(v, input) then
 278             table.insert(result, v)
 279         end
 280     end
 281     return result
 282 end
 283
 284 function foo(arg)
 285     messenger:Message(arg)
 286 end
 287
 288 MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
 289 ```
 290
 291
 292 ## Default plugins
 293
 294 For examples of plugins, see the default `autoclose` and `linter` plugins
 295 (stored in the normal micro core repo under `runtime/plugins`) as well as any
 296 plugins that are stored in the official channel
 297 [here](https://github.com/micro-editor/plugin-channel).
 298
 299
 300 ## Plugin Manager
 301
 302 Micro also has a built in plugin manager which you can invoke with the
 303 `> plugin ...` command.
 304
 305 For the valid commands you can use, see the `command` help topic.
 306
 307 The manager fetches plugins from the channels (which is simply a list of plugin
 308 metadata) which it knows about. By default, micro only knows about the official
 309 channel which is located at github.com/micro-editor/plugin-channel but you can
 310 add your own third-party channels using the `pluginchannels` option and you can
 311 directly link third-party plugins to allow installation through the plugin
 312 manager with the `pluginrepos` option.
 313
 314 If you'd like to publish a plugin you've made as an official plugin, you should
 315 upload your plugin online (to Github preferably) and add a `repo.json` file.
 316 This file will contain the metadata for your plugin. Here is an example:
 317
 318 ```json
 319 [{
 320   "Name": "pluginname",
 321   "Description": "Here is a nice concise description of my plugin",
 322   "Tags": ["python", "linting"],
 323   "Versions": [
 324     {
 325       "Version": "1.0.0",
 326       "Url": "https://github.com/user/plugin/archive/v1.0.0.zip",
 327       "Require": {
 328         "micro": ">=1.0.3"
 329       }
 330     }
 331   ]
 332 }]
 333 ```
 334
 335 Then open a pull request at github.com/micro-editor/plugin-channel adding a link
 336 to the raw `repo.json` that is in your plugin repository. To make updating the
 337 plugin work, the first line of your plugins lua code should contain the version
 338 of the plugin. (Like this: `VERSION = "1.0.0"`) Please make sure to use
 339 [semver](http://semver.org/) for versioning.