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",
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
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`
- `BTInfo`
- `NewBufferFromFile`
- `ByteOffset`
+ - `Log`
+ - `LogBuf`
* `micro/util`
- `RuneAt`
- `GetLeadingWhitespace`
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.
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
[{
"Name": "pluginname",
"Description": "Here is a nice concise description of my plugin",
+ "Website": "https://github.com/user/plugin"
"Tags": ["python", "linting"],
"Versions": [
{
```
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.
projects / micro.git / blobdiff