X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=runtime%2Fhelp%2Fplugins.md;h=4290260570c86d36a5b9bb977850297142755ae1;hb=24a684cff25cd9f189a943d1dc2a98d3aa6c796f;hp=4c6e15fde4048976c3ff2f2e19986e59f52af50d;hpb=60eec0eccd0d1bd9b8aaebcd17b02d6bfbc7b20a;p=micro.git diff --git a/runtime/help/plugins.md b/runtime/help/plugins.md index 4c6e15fd..42902605 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,68 +258,55 @@ 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 +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. -See this example to learn how to use `MakeCompletion` and `MakeCommand` - -```lua -local function StartsWith(String,Start) - String = String:upper() - Start = Start:upper() - return string.sub(String,1,string.len(Start))==Start -end +## Default plugins -function complete(input) - local allCompletions = {"Hello", "World", "Foo", "Bar"} - local result = {} +There are 6 default plugins that come pre-installed with micro. These are - for i,v in pairs(allCompletions) do - if StartsWith(v, input) then - table.insert(result, v) - end - end - return result -end +* `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). -function foo(arg) - messenger:Message(arg) -end +See `> help linter`, `> help comment`, and `> help status` for additional +documentation specific to those plugins. -MakeCommand("foo", "example.foo", MakeCompletion("example.complete")) -``` - -## Default 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. +For the valid commands you can use, see the `command` 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 @@ -300,6 +323,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": [ { @@ -314,7 +338,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. 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. +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.