X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fplugins.md;h=1818b96bddd4d11f677f4b4439c6556f2d214830;hb=54c23cae72d7237bc898a59f79aad0acffdf0ffe;hp=1224ce4768cf0e06555f4a50be944f65ddb8fae3;hpb=ef768e36f3e9f8b97db4dfb52d3e9723d760c586;p=micro.git diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 1224ce47..1818b96b 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -11,7 +11,7 @@ from the go plugin, which has the following file structure: ``` ~/.config/micro/plug/go-plugin/ go.lua - info.json + repo.json help/ go-plugin.md ``` @@ -35,34 +35,6 @@ is unlikely for a plugin to need to add plugin files at runtime or syntax header files. No directory structure is enforced but keeping runtime files in their own directories is good practice. -# Info file - -The `info.json` for the Go plugin is the following: - -``` -{ - "name": "go", - "description": "Go formatting and tool support", - "website": "https://github.com/micro-editor/go-plugin", - "install": "https://github.com/micro-editor/go-plugin", - "version": "1.0.0", - "require": [ - "micro >= 2.0.0" - ] -} -``` - -All fields are simply interpreted as strings, so the version does not -need to be a semantic version, and the dependencies are also only -meant to be parsed by humans. The name should be an identifier, and -the website should point to a valid website. The install field should -provide info about installing the plugin, or point to a website that -provides information. - -Note that the name of the plugin is defined by the name field in -the `info.json` and not by the installation path. Some functions micro -exposes to plugins require passing the name of the plugin. - ## Lua callbacks Plugins use Lua but also have access to many functions both from micro @@ -71,6 +43,12 @@ are called when certain events happen. Here is the list of callbacks which micro defines: * `init()`: this function should be used for your plugin initialization. + This function is called after buffers have been initialized. + +* `preinit()`: initialization function called before buffers have been + initialized. + +* `postinit()`: initialization function called after `init()`. * `onBufferOpen(buf)`: runs when a buffer is opened. The input contains the buffer object. @@ -97,23 +75,13 @@ function onSave(bp) end ``` -The `bp` variable is a reference to the bufpane the action is being executed within. -This is almost always the current bufpane. +The `bp` variable is a reference to the bufpane the action is being executed +within. This is almost always the current bufpane. All available actions are listed in the keybindings section of the help. -For callbacks to mouse actions, you are also given the event info: - -```lua -function onMousePress(view, event) - local x, y = event:Position() - - return false -end -``` - -These functions should also return a boolean specifying whether the bufpane should -be relocated to the cursor or not after the action is complete. +These functions should also return a boolean specifying whether the bufpane +should be relocated to the cursor or not after the action is complete. ## Accessing micro functions @@ -129,76 +97,211 @@ micro.Log("Hello") The packages and functions are listed below (in Go type signatures): * `micro` - - `TermMessage(msg interface{}...)` - - `TermError()` - - `InfoBar()` - - `Log(msg interface{}...)` - - `SetStatusInfoFn(fn string)` + - `TermMessage(msg interface{}...)`: temporarily close micro and print a + message + + - `TermError(filename string, lineNum int, err string)`: temporarily close + micro and print an error formatted as `filename, lineNum: err`. + + - `InfoBar()`: return the infobar BufPane object. + + - `Log(msg interface{}...)`: write a message to `log.txt` (requires + `-debug` flag, or binary built with `build-dbg`). + + - `SetStatusInfoFn(fn string)`: register the given lua function as + accessible from the statusline formatting options. + + - `CurPane() *BufPane`: returns the current BufPane, or nil if the + current pane is not a BufPane. + + - `CurTab() *Tab`: returns the current tab. * `micro/config` - - `MakeCommand` - - `FileComplete` - - `HelpComplete` - - `OptionComplete` - - `OptionValueComplete` - - `NoComplete` - - `TryBindKey` - - `Reload` - - `AddRuntimeFilesFromDirectory` - - `AddRuntimeFileFromMemory` - - `AddRuntimeFile` - - `ListRuntimeFiles` - - `ReadRuntimeFile` - - `RTColorscheme` - - `RTSyntax` - - `RTHelp` - - `RTPlugin` - - `RegisterCommonOption` - - `RegisterGlobalOption` + - `MakeCommand(name string, action func(bp *BufPane, args[]string), + completer buffer.Completer)`: + create a command with the given name, and lua callback function when + the command is run. A completer may also be given to specify how + autocompletion should work with the custom command. + + - `FileComplete`: autocomplete using files in the current directory + - `HelpComplete`: autocomplete using names of help documents + - `OptionComplete`: autocomplete using names of options + - `OptionValueComplete`: autocomplete using names of options, and valid + values afterwards + - `NoComplete`: no autocompletion suggestions + + - `TryBindKey(k, v string, overwrite bool) (bool, error)`: bind the key + `k` to the string `v` in the `bindings.json` file. If `overwrite` is + true, this will overwrite any existing binding to key `k`. Returns true + if the binding was made, and a possible error (for example writing to + `bindings.json` can cause an error). + + - `Reload()`: reload configuration files. + + - `AddRuntimeFileFromMemory(filetype RTFiletype, filename, data string)`: + add a runtime file to the `filetype` runtime filetype, with name + `filename` and data `data`. + + - `AddRuntimeFilesFromDirectory(plugin string, filetype RTFiletype, + directory, pattern string)`: + add runtime files for the given plugin with the given RTFiletype from + a directory within the plugin root. Only adds files that match the + pattern using Go's `filepath.Match` + + - `AddRuntimeFile(plugin string, filetype RTFiletype, filepath string)`: + add a given file inside the plugin root directory as a runtime file + to the given RTFiletype category. + + - `ListRuntimeFiles(fileType RTFiletype) []string`: returns a list of + names of runtime files of the given type. + + - `ReadRuntimeFile(fileType RTFiletype, name string) string`: returns the + contents of a given runtime file. + + - `NewRTFiletype() int`: creates a new RTFiletype, and returns its value. + + - `RTColorscheme`: runtime files for colorschemes. + - `RTSyntax`: runtime files for syntax files. + - `RTHelp`: runtime files for help documents. + - `RTPlugin`: runtime files for plugin source code. + + - `RegisterCommonOption(pl string, name string, defaultvalue interface{})`: + registers a new option with for the given plugin. The name of the + option will be `pl.name`, and will have the given default value. Since + this registers a common option, the option will be modifiable on a + per-buffer basis, while also having a global value (in the + GlobalSettings map). + + - `RegisterGlobalOption(pl string, name string, defaultvalue interface{})`: + same as `RegisterCommonOption` but the option cannot be modified + locally to each buffer. + + - `GetGlobalOption(name string) interface{}`: returns the value of a + given plugin in the `GlobalSettings` map. + + - `SetGlobalOption(option, value string) error`: sets an option to a + given value. Same as using the `> set` command. This will parse the + value to the actual value type. + + - `SetGlobalOptionNative(option string, value interface{}) error`: sets + an option to a given value, where the type of value is the actual + type of the value internally. * `micro/shell` - - `ExecCommand` - - `RunCommand` - - `RunBackgroundShell` - - `RunInteractiveShell` - - `JobStart` - - `JobSpawn` - - `JobStop` - - `JobStop` - - `RunTermEmulator` - - `TermEmuSupported` + - `ExecCommand(name string, arg ...string) (string, error)`: runs an + executable with the given arguments, and pipes the output (stderr + and stdout) of the executable to an internal buffer, which is + returned as a string, along with a possible error. + + - `RunCommand(input string) (string, error)`: same as `ExecCommand`, + except this uses micro's argument parser to parse the arguments from + the input. For example `cat 'hello world.txt' file.txt`, will pass + two arguments in the `ExecCommand` argument list (quoting arguments + will preserve spaces). + + - `RunBackgroundShell(input string) (func() string, error)`: returns a + function that will run the given shell command and return its output. + + - `RunInteractiveShell(input string, wait bool, getOutput bool) + (string, error)`: + temporarily closes micro and runs the given command in the terminal. + If `wait` is true, micro will wait for the user to press enter before + returning to text editing. If `getOutput` is true, micro redirect + stdout from the command to the returned string. + + - `JobStart(cmd string, onStdout, onStderr, + onExit func(string, []interface{}), userargs ...interface{}) + *exec.Cmd`: + Starts a background job by running the shell on the given command + (using `sh -c`). Three callbacks can be provided which will be called + when the command generates stdout, stderr, or exits. The userargs will + be passed to the callbacks, along with the output as the first + argument of the callback. + + - `JobSpawn(cmd string, cmdArgs []string, onStdout, onStderr, + onExit func(string, []interface{}), userargs ...interface{}) + *exec.Cmd`: + same as `JobStart`, except doesn't run the command through the shell + and instead takes as inputs the list of arguments. + + - `JobStop(cmd *exec.Cmd)`: kills a job. + - `JobSend(cmd *exec.Cmd, data string)`: sends some data to a job's stdin. + + - `RunTermEmulator(h *BufPane, input string, wait bool, getOutput bool, + callback func(out string, userargs []interface{}), + userargs []interface{}) error`: + starts a terminal emulator from a given BufPane with the input command. + If `wait` is true it will wait for the user to exit by pressing enter + once the executable has terminated and if `getOutput` is true it will + redirect the stdout of the process to a pipe which will be passed to + the callback which is a function that takes a string and a list of + optional user arguments. This function returns an error on systems + where the terminal emulator is not supported. + + - `TermEmuSupported`: true on systems where the terminal emulator is + supported and false otherwise. Supported systems: + * Linux + * MacOS + * Dragonfly + * OpenBSD + * FreeBSD + * `micro/buffer` - - `NewMessage` - - `NewMessageAtLine` - - `MTInfo` - - `MTWarning` - - `MTError` - - `Loc` - - `BTDefault` - - `BTLog` - - `BTRaw` - - `BTInfo` - - `NewBufferFromFile` - - `ByteOffset` - - `Log` - - `LogBuf` -* `micro/util` - - `RuneAt` - - `GetLeadingWhitespace` - - `IsWordChar` + - `NewMessage(owner string, msg string, start, end, Loc, kind MsgType) + *Message`: + creates a new message with an owner over a range given by the start + and end locations. + + - `NewMessageAtLine(owner string, msg string, line int, kindMsgType) + *Message`: + creates a new message with owner, type and message at a given line. + + - `MTInfo`: info message. + - `MTWarning`: warning message. + - `MTError` error message. + + - `Loc(x, y int) Loc`: creates a new location struct. + - `BTDefault`: default buffer type. + - `BTLog`: log buffer type. + - `BTRaw`: raw buffer type. + - `BTInfo`: info buffer type. + + - `NewBuffer(text, path string) *Buffer`: creates a new buffer with the + given text at a certain path. + + - `NewBufferFromFile(path string) (*Buffer, error)`: creates a new + buffer by reading from disk at the given path. + + - `ByteOffset(pos Loc, buf *Buffer) int`: returns the byte index of the + given position in a buffer. + + - `Log(s string)`: writes a string to the log buffer. + - `LogBuf() *Buffer`: returns the log buffer. +* `micro/util` + - `RuneAt(str string, idx int) string`: returns the utf8 rune at a + given index within a string. + - `GetLeadingWhitespace(s string) string`: returns the leading + whitespace of a string. + - `IsWordChar(s string) bool`: returns true if the first rune in a + string is a word character. + - `String(b []byte) string`: converts a byte array to a string. + - `RuneStr(r rune) string`: converts a rune to a string. + - `Unzip(src, dest string) error`: unzips a file to given folder. This may seem like a small list of available functions but some of the objects returned by the functions have many methods. The Lua plugin may access any -public methods of an object returned by any of the functions above. Unfortunately -it is not possible to list all the available functions on this page. Please -go to the internal documentation at https://godoc.org/github.com/zyedidia/micro -to see the full list of available methods. Note that only methods of types that -are available to plugins via the functions above can be called from a plugin. -For an even more detailed reference see the source code on Github. +public methods of an object returned by any of the functions above. +Unfortunately it is not possible to list all the available functions on this +page. Please go to the internal documentation at +https://godoc.org/github.com/zyedidia/micro to see the full list of available +methods. Note that only methods of types that are available to plugins via +the functions above can be called from a plugin. For an even more detailed +reference see the source code on Github. -For example, with a BufPane object called `bp`, you could call the `Save` function -in Lua with `bp:Save()`. +For example, with a BufPane object called `bp`, you could call the `Save` +function in Lua with `bp:Save()`. -Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax. +Note that Lua uses the `:` syntax to call a function rather than Go's `.` +syntax. ```go micro.InfoBar().Message() @@ -256,6 +359,8 @@ strings regexp errors time +archive/zip +net/http ``` For documentation for each of these functions, see the Go standard @@ -263,9 +368,16 @@ library documentation at https://golang.org/pkg/ (for the packages exposed to micro plugins). The Lua standard library is also available to plugins though it is rather small. +The following functions are also available from the go-humanize package: + +The `humanize` package exposes: +* `Bytes` +* `Ordinal` + ## Adding help files, syntax files, or colorschemes in your plugin -You can use the `AddRuntimeFile(name string, type config.RTFiletype, path string)` +You can use the `AddRuntimeFile(name string, type config.RTFiletype, + path string)` function to add various kinds of files to your plugin. For example, if you'd like to add a help topic to your plugin called `test`, you would create a `test.md` file, and call the function: @@ -294,6 +406,12 @@ There are 6 default plugins that come pre-installed with micro. These are programming tool. * `status`: provides some extensions to the status line (integration with Git and more). +* `diff`: integrates the `diffgutter` option with Git. If you are in a Git + directory, the diff gutter will show changes with respect to the most + recent Git commit rather than the diff since opening the file. + +See `> help linter`, `> help comment`, and `> help status` for additional +documentation specific to those plugins. These are good examples for many use-cases if you are looking to write your own plugins. @@ -303,7 +421,7 @@ your own plugins. Micro also has a built in plugin manager which you can invoke with the `> plugin ...` command, or in the shell with `micro -plugin ...`. -For the valid commands you can use, see the `command` help topic. +For the valid commands you can use, see the `commands` help topic. The manager fetches plugins from the channels (which is simply a list of plugin metadata) which it knows about. By default, micro only knows about the official @@ -320,7 +438,7 @@ This file will contain the metadata for your plugin. Here is an example: [{ "Name": "pluginname", "Description": "Here is a nice concise description of my plugin", - "Website": "https://github.com/user/plugin" + "Website": "https://github.com/user/plugin", "Tags": ["python", "linting"], "Versions": [ { @@ -334,8 +452,8 @@ This file will contain the metadata for your plugin. Here is an example: }] ``` -Then open a pull request at github.com/micro-editor/plugin-channel adding a link -to the raw `repo.json` that is in your plugin repository. +Then open a pull request at github.com/micro-editor/plugin-channel adding a +link to the raw `repo.json` that is in your plugin repository. 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"`)