X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fplugins.md;h=6c431068542fd888fb18b127d6230e1b440cb949;hb=d965e8de4f44c190ad27b343bebc0c7dae414837;hp=4c6e15fde4048976c3ff2f2e19986e59f52af50d;hpb=604d78de0f4e79221d022f9e4b01ab6044946ca5;p=micro.git diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 4c6e15fd..6c431068 100644 --- a/runtime/help/plugins.md +++ b/runtime/help/plugins.md @@ -9,12 +9,36 @@ 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 + help/ + go-plugin.md ``` -info.json: +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. + +# Info file + +The `info.json` for the Go plugin is the following: + ``` { "name": "go", @@ -35,6 +59,10 @@ 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 @@ -98,14 +126,14 @@ 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` + - `SetStatusInfoFn(fn string)` * `micro/config` - `MakeCommand` - `FileComplete` @@ -150,6 +178,8 @@ The packages and functions are listed below: - `BTInfo` - `NewBufferFromFile` - `ByteOffset` + - `Log` + - `LogBuf` * `micro/util` - `RuneAt` - `GetLeadingWhitespace` @@ -158,9 +188,15 @@ The packages and functions are listed below: 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. + +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. @@ -222,99 +258,54 @@ errors time ``` -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. ## 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 - -function foo(arg) - messenger:Message(arg) -end +## Default plugins -MakeCommand("foo", "example.foo", MakeCompletion("example.complete")) -``` +There are 6 default plugins that come pre-installed with micro. These are -## Default plugins +* `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). -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. - -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 -channel which is located at github.com/micro-editor/plugin-channel but you can -add your own third-party channels using the `pluginchannels` option and you can -directly link third-party plugins to allow installation through the plugin -manager with the `pluginrepos` option. - -If you'd like to publish a plugin you've made as an official plugin, you should -upload your plugin online (to Github preferably) and add a `repo.json` file. -This file will contain the metadata for your plugin. Here is an example: - -```json -[{ - "Name": "pluginname", - "Description": "Here is a nice concise description of my plugin", - "Tags": ["python", "linting"], - "Versions": [ - { - "Version": "1.0.0", - "Url": "https://github.com/user/plugin/archive/v1.0.0.zip", - "Require": { - "micro": ">=1.0.3" - } - } - ] -}] -``` - -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. +Micro's plugin manager is you! Ultimately the plugins that are created +for micro are quite simple and don't require a complex automated tool +to manage them. They should be "git cloned" or somehow placed in the +`~/.config/micro/plug` directory, and that is all that's necessary +for installation. In the rare case that a more complex installation +process is needed (such as dependencies, or additional setup) the +plugin creator should provide the additional instructions on their +website and point to the link using the `install` field in the `info.json` +file.