```
~/.config/micro/plug/go-plugin/
go.lua
- info.json
+ repo.json
help/
go-plugin.md
```
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",
- "description": "Go formatting and tool support",
- "website": "https://github.com/micro-editor/go-plugin",
- "install": "https://github.com/micro-editor/go-plugin",
- "version": "1.0.0",
- "require": [
- "micro >= 2.0.0"
- ]
-}
-```
-
-All fields are simply interpreted as strings, so the version does not
-need to be a semantic version, and the dependencies are also only
-meant to be parsed by humans. The name should be an identifier, and
-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
end
```
-The `bp` variable is a reference to the bufpane the action is being executed within.
-This is almost always the current bufpane.
+The `bp` variable is a reference to the bufpane the action is being executed
+within. This is almost always the current bufpane.
All available actions are listed in the keybindings section of the help.
end
```
-These functions should also return a boolean specifying whether the bufpane should
-be relocated to the cursor or not after the action is complete.
+These functions should also return a boolean specifying whether the bufpane
+should be relocated to the cursor or not after the action is complete.
## Accessing micro functions
The packages and functions are listed below (in Go type signatures):
* `micro`
- - `TermMessage(msg interface{}...)`
- - `TermError()`
- - `InfoBar()`
- - `Log(msg interface{}...)`
- - `SetStatusInfoFn(fn string)`
+ - `TermMessage(msg interface{}...)`: temporarily close micro and print a
+ message
+
+ - `TermError(filename string, lineNum int, err string)`: temporarily close
+ micro and print an error formatted as `filename, lineNum: err`.
+
+ - `InfoBar()`: return the infobar BufPane object.
+
+ - `Log(msg interface{}...)`: write a message to `log.txt` (requires
+ `-debug` flag, or binary built with `build-dbg`).
+
+ - `SetStatusInfoFn(fn string)`: register the given lua function as
+ accessible from the statusline formatting options
* `micro/config`
- - `MakeCommand`
- - `FileComplete`
- - `HelpComplete`
- - `OptionComplete`
- - `OptionValueComplete`
- - `NoComplete`
- - `TryBindKey`
- - `Reload`
- - `AddRuntimeFilesFromDirectory`
- - `AddRuntimeFileFromMemory`
- - `AddRuntimeFile`
- - `ListRuntimeFiles`
- - `ReadRuntimeFile`
- - `RTColorscheme`
- - `RTSyntax`
- - `RTHelp`
- - `RTPlugin`
- - `RegisterCommonOption`
- - `RegisterGlobalOption`
+ - `MakeCommand(name string, action func(bp *BufPane, args[]string),
+ completer buffer.Completer)`:
+ create a command with the given name, and lua callback function when
+ the command is run. A completer may also be given to specify how
+ autocompletion should work with the custom command.
+
+ - `FileComplete`: autocomplete using files in the current directory
+ - `HelpComplete`: autocomplete using names of help documents
+ - `OptionComplete`: autocomplete using names of options
+ - `OptionValueComplete`: autocomplete using names of options, and valid
+ values afterwards
+ - `NoComplete`: no autocompletion suggestions
+
+ - `TryBindKey(k, v string, overwrite bool) (bool, error)`: bind the key
+ `k` to the string `v` in the `bindings.json` file. If `overwrite` is
+ true, this will overwrite any existing binding to key `k`. Returns true
+ if the binding was made, and a possible error (for example writing to
+ `bindings.json` can cause an error).
+
+ - `Reload()`: reload configuration files.
+
+ - `AddRuntimeFileFromMemory(filetype RTFiletype, filename, data string)`:
+ add a runtime file to the `filetype` runtime filetype, with name
+ `filename` and data `data`.
+
+ - `AddRuntimeFilesFromDirectory(plugin string, filetype RTFiletype,
+ directory, pattern string)`:
+ add runtime files for the given plugin with the given RTFiletype from
+ a directory within the plugin root. Only adds files that match the
+ pattern using Go's `filepath.Match`
+
+ - `AddRuntimeFile(plugin string, filetype RTFiletype, filepath string)`:
+ add a given file inside the plugin root directory as a runtime file
+ to the given RTFiletype category.
+
+ - `ListRuntimeFiles(fileType RTFiletype) []string`: returns a list of
+ names of runtime files of the given type.
+
+ - `ReadRuntimeFile(fileType RTFiletype, name string) string`: returns the
+ contents of a given runtime file.
+
+ - `NewRTFiletype() int`: creates a new RTFiletype, and returns its value.
+
+ - `RTColorscheme`: runtime files for colorschemes.
+ - `RTSyntax`: runtime files for syntax files.
+ - `RTHelp`: runtime files for help documents.
+ - `RTPlugin`: runtime files for plugin source code.
+
+ - `RegisterCommonOption(pl string, name string, defaultvalue interface{})`:
+ registers a new option with for the given plugin. The name of the
+ option will be `pl.name`, and will have the given default value. Since
+ this registers a common option, the option will be modifiable on a
+ per-buffer basis, while also having a global value (in the
+ GlobalSettings map).
+
+ - `RegisterGlobalOption(pl string, name string, defaultvalue interface{})`:
+ same as `RegisterCommonOption` but the option cannot be modified
+ locally to each buffer.
+
+ - `GetGlobalOption(name string) interface{}`: returns the value of a
+ given plugin in the `GlobalSettings` map.
+
+ - `SetGlobalOption(option, value string) error`: sets an option to a
+ given value. Same as using the `> set` command. This will parse the
+ value to the actual value type.
+
+ - `SetGlobalOptionNative(option string, value interface{}) error`: sets
+ an option to a given value, where the type of value is the actual
+ type of the value internally.
* `micro/shell`
- - `ExecCommand`
- - `RunCommand`
- - `RunBackgroundShell`
- - `RunInteractiveShell`
- - `JobStart`
- - `JobSpawn`
- - `JobStop`
- - `JobStop`
- - `RunTermEmulator`
- - `TermEmuSupported`
+ - `ExecCommand(name string, arg ...string) (string, error)`: runs an
+ executable with the given arguments, and pipes the output (stderr
+ and stdout) of the executable to an internal buffer, which is
+ returned as a string, along with a possible error.
+
+ - `RunCommand(input string) (string, error)`: same as `ExecCommand`,
+ except this uses micro's argument parser to parse the arguments from
+ the input. For example `cat 'hello world.txt' file.txt`, will pass
+ two arguments in the `ExecCommand` argument list (quoting arguments
+ will preserve spaces).
+
+ - `RunBackgroundShell(input string) (func() string, error)`: returns a
+ function that will run the given shell command and return its output.
+
+ - `RunInteractiveShell(input string, wait bool, getOutput bool)
+ (string, error)`:
+ temporarily closes micro and runs the given command in the terminal.
+ If `wait` is true, micro will wait for the user to press enter before
+ returning to text editing. If `getOutput` is true, micro redirect
+ stdout from the command to the returned string.
+
+ - `JobStart(cmd string, onStdout, onStderr,
+ onExit func(string, []interface{}), userargs ...interface{})
+ *exec.Cmd`:
+ Starts a background job by running the shell on the given command
+ (using `sh -c`). Three callbacks can be provided which will be called
+ when the command generates stdout, stderr, or exits. The userargs will
+ be passed to the callbacks, along with the output as the first
+ argument of the callback.
+
+ - `JobSpawn(cmd string, cmdArgs []string, onStdout, onStderr,
+ onExit func(string, []interface{}), userargs ...interface{})
+ *exec.Cmd`:
+ same as `JobStart`, except doesn't run the command through the shell
+ and instead takes as inputs the list of arguments.
+
+ - `JobStop(cmd *exec.Cmd)`: kills a job.
+ - `JobSend(cmd *exec.Cmd, data string)`: sends some data to a job's stdin.
+
+ - `RunTermEmulator(h *BufPane, input string, wait bool, getOutput bool,
+ callback func(out string, userargs []interface{}),
+ userargs []interface{}) error`:
+ starts a terminal emulator from a given BufPane with the input command.
+ If `wait` is true it will wait for the user to exit by pressing enter
+ once the executable has terminated and if `getOutput` is true it will
+ redirect the stdout of the process to a pipe which will be passed to
+ the callback which is a function that takes a string and a list of
+ optional user arguments. This function returns an error on systems
+ where the terminal emulator is not supported.
+
+ - `TermEmuSupported`: true on systems where the terminal emulator is
+ supported and false otherwise. Supported systems:
+ * Linux
+ * MacOS
+ * Dragonfly
+ * OpenBSD
+ * FreeBSD
+
* `micro/buffer`
- - `NewMessage`
- - `NewMessageAtLine`
- - `MTInfo`
- - `MTWarning`
- - `MTError`
- - `Loc`
- - `BTDefault`
- - `BTLog`
- - `BTRaw`
- - `BTInfo`
- - `NewBufferFromFile`
- - `ByteOffset`
- - `Log`
- - `LogBuf`
-* `micro/util`
- - `RuneAt`
- - `GetLeadingWhitespace`
- - `IsWordChar`
+ - `NewMessage(owner string, msg string, start, end, Loc, kind MsgType)
+ *Message`:
+ creates a new message with an owner over a range given by the start
+ and end locations.
+
+ - `NewMessageAtLine(owner string, msg string, line int, kindMsgType)
+ *Message`:
+ creates a new message with owner, type and message at a given line.
+
+ - `MTInfo`: info message.
+ - `MTWarning`: warning message.
+ - `MTError` error message.
+
+ - `Loc(x, y int) Loc`: creates a new location struct.
+ - `BTDefault`: default buffer type.
+ - `BTLog`: log buffer type.
+ - `BTRaw`: raw buffer type.
+ - `BTInfo`: info buffer type.
+
+ - `NewBuffer(text, path string) *Buffer`: creates a new buffer with the
+ given text at a certain path.
+
+ - `NewBufferFromFile(path string) (*Buffer, error)`: creates a new
+ buffer by reading from disk at the given path.
+
+ - `ByteOffset(pos Loc, buf *Buffer) int`: returns the byte index of the
+ given position in a buffer.
+
+ - `Log(s string)`: writes a string to the log buffer.
+ - `LogBuf() *Buffer`: returns the log buffer.
+* `micro/util`
+ - `RuneAt(str string, idx int) string`: returns the utf8 rune at a
+ given index within a string.
+ - `GetLeadingWhitespace(s string) string`: returns the leading
+ whitespace of a string.
+ - `IsWordChar(s string) bool`: returns true if the first rune in a
+ string is a word character.
+ - `String(b []byte) string`: converts a byte array to a string.
+ - `RuneStr(r rune) string`: converts a rune to a string.
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. 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.
+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()`.
+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.
+Note that Lua uses the `:` syntax to call a function rather than Go's `.`
+syntax.
```go
micro.InfoBar().Message()
## Adding help files, syntax files, or colorschemes in your plugin
-You can use the `AddRuntimeFile(name string, type config.RTFiletype, path string)`
+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:
[{
"Name": "pluginname",
"Description": "Here is a nice concise description of my plugin",
- "Website": "https://github.com/user/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.
+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"`)
projects / micro.git / blobdiff