X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fplugins.md;h=1818b96bddd4d11f677f4b4439c6556f2d214830;hb=54c23cae72d7237bc898a59f79aad0acffdf0ffe;hp=4c6e15fde4048976c3ff2f2e19986e59f52af50d;hpb=60eec0eccd0d1bd9b8aaebcd17b02d6bfbc7b20a;p=micro.git diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 4c6e15fd..1818b96b 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -9,31 +9,31 @@ plugin's website, dependencies, etc... Here is an example info file from the go plugin, which has the following file structure: ``` -~/.config/micro/plug/go-plugin +~/.config/micro/plug/go-plugin/ go.lua - info.json + repo.json + help/ + go-plugin.md ``` -info.json: -``` -{ - "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. +The `go.lua` file contains the main code for the plugin, though the +code may be distributed across multiple Lua files. The `info.json` +file contains information about the plugin such as the website, +description, version, and any requirements. Plugins may also +have additional files which can be added to micro's runtime files, +of which there are 5 types: + +* Colorschemes +* Syntax files +* Help files +* Plugin files +* Syntax header files + +In most cases, a plugin will want to add help files, but in certain +cases a plugin may also want to add colorschemes or syntax files. It +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. ## Lua callbacks @@ -43,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. @@ -69,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 @@ -98,71 +94,214 @@ local micro = import("micro") micro.Log("Hello") ``` -The packages and functions are listed below: +The packages and functions are listed below (in Go type signatures): * `micro` - - `TermMessage(msg interface{}...)` - - `TermError()` - - `InfoBar()` - - `Log(msg interface{}...)` - - `SetStatusInfoFn` + - `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` -* `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. For example, -with a BufPane object called `bp`, you could called the `Save` function in Lua -with `bp:Save()`. +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. -Note that Lua uses the `:` syntax to call a function rather than Go's `.` syntax. +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. ```go micro.InfoBar().Message() @@ -220,68 +359,67 @@ strings regexp errors time +archive/zip +net/http ``` -For documentation for each of these functions, you can simply look -through the Go standard library documentation. +For documentation for each of these functions, see the Go standard +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, type, 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: +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: ```lua -AddRuntimeFile("test", "help", "test.md") +config = import("micro/config") +config.AddRuntimeFile("test", config.RTHelp, "test.md") ``` Use `AddRuntimeFilesFromDirectory(name, type, dir, pattern)` to add a number of files to the runtime. To read the content of a runtime file use `ReadRuntimeFile(fileType, name string)` or `ListRuntimeFiles(fileType string)` -for all runtime files. - -## Autocomplete command arguments - -See this example to learn how to use `MakeCompletion` and `MakeCommand` +for all runtime files. In addition, there is `AddRuntimeFileFromMemory` which +adds a runtime file based on a string that may have been constructed at +runtime. -```lua -local function StartsWith(String,Start) - String = String:upper() - Start = Start:upper() - return string.sub(String,1,string.len(Start))==Start -end - -function complete(input) - local allCompletions = {"Hello", "World", "Foo", "Bar"} - local result = {} - - for i,v in pairs(allCompletions) do - if StartsWith(v, input) then - table.insert(result, v) - end - end - return result -end +## Default plugins -function foo(arg) - messenger:Message(arg) -end +There are 6 default plugins that come pre-installed with micro. These are -MakeCommand("foo", "example.foo", MakeCompletion("example.complete")) -``` +* `autoclose`: automatically closes brackets, quotes, etc... +* `comment`: provides automatic commenting for a number of languages +* `ftoptions`: alters some default options depending on the filetype +* `linter`: provides extensible linting for many languages +* `literate`: provides advanced syntax highlighting for the Literate + 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. -## Default plugins +See `> help linter`, `> help comment`, and `> help status` for additional +documentation specific to those plugins. -For examples of plugins, see the default `autoclose` and `linter` plugins -(stored in the normal micro core repo under `runtime/plugins`) as well as any -plugins that are stored in the official channel -[here](https://github.com/micro-editor/plugin-channel). +These are good examples for many use-cases if you are looking to write +your own plugins. ## Plugin Manager Micro also has a built in plugin manager which you can invoke with the -`> plugin ...` command. +`> plugin ...` command, or in the shell with `micro -plugin ...`. For the valid commands you can use, see the `commands` help topic. @@ -300,6 +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", "Tags": ["python", "linting"], "Versions": [ { @@ -313,8 +452,9 @@ 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. 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"`) Please make sure to use -[semver](http://semver.org/) for versioning. +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"`) +Please make sure to use [semver](http://semver.org/) for versioning.