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`
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
-
-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.
projects / micro.git / blobdiff