github/zyedidia.micro
2
0
Fork 0
mirror of https://github.com/zyedidia/micro.git synced 2026-03-18 14:57:18 +09:00
Code Issues Packages Projects Releases Wiki Activity

More doc updates

Browse Source
This commit is contained in:
Zachary Yedidia
2020-01-06 00:01:49 -05:00
parent f2a1e2337f
commit f3e8413e77
2 changed files with 78 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
runtime/help/options.md
View File

@@ -276,7 +276,8 @@ machine, simply copy the settings.json to the other machine.
You can set these settings either globally or locally. Locally means that the
setting won't be saved to `~/.config/micro/settings.json` and that it will only
be set in the current buffer. Setting an option globally is the default, and
will set the option in all buffers.
will set the option in all buffers. Use the `setlocal` command to set an option
locally rather than globally.
The `colorscheme` option is global only, and the `filetype` option is local
only. To set an option locally, use `setlocal` instead of `set`.

163
runtime/help/plugins.md
View File

@@ -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`
@@ -158,9 +186,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 +256,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`
```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
MakeCommand("foo", "example.foo", MakeCompletion("example.complete"))
```
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.
## 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).
There are 6 default plugins that come pre-installed with micro. These are
* `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).
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.