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

More plugin docs and improve doc formatting

Browse Source
This commit is contained in:
Zachary Yedidia
2020-02-08 18:31:06 -05:00
parent 6514b77e0d
commit 57c34e2248
12 changed files with 404 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
internal/action/infocomplete.go
View File

@@ -197,7 +197,7 @@ func OptionValueComplete(b *buffer.Buffer) ([]string, []string) {
return completions, suggestions return completions, suggestions
} }
// OptionComplete autocompletes options // PluginCmdComplete autocompletes the plugin command
func PluginCmdComplete(b *buffer.Buffer) ([]string, []string) { func PluginCmdComplete(b *buffer.Buffer) ([]string, []string) {
c := b.GetActiveCursor() c := b.GetActiveCursor()
input, argstart := buffer.GetArg(b) input, argstart := buffer.GetArg(b)
@@ -253,51 +253,28 @@ func PluginComplete(b *buffer.Buffer) ([]string, []string) {
return completions, suggestions return completions, suggestions
} }
// // MakeCompletion registers a function from a plugin for autocomplete commands // PluginNameComplete completes with the names of loaded plugins
// func MakeCompletion(function string) Completion { // func PluginNameComplete(b *buffer.Buffer) ([]string, []string) {
// pluginCompletions = append(pluginCompletions, LuaFunctionComplete(function)) // c := b.GetActiveCursor()
// return Completion(-len(pluginCompletions)) // input, argstart := buffer.GetArg(b)
// }
// //
// // PluginComplete autocompletes from plugin function // var suggestions []string
// func PluginComplete(complete Completion, input string) (chosen string, suggestions []string) { // for _, pp := range config.GetAllPluginPackages(nil) {
// idx := int(-complete) - 1
//
// if len(pluginCompletions) <= idx {
// return "", nil
// }
// suggestions = pluginCompletions[idx](input)
//
// if len(suggestions) == 1 {
// chosen = suggestions[0]
// }
// return
// }
//
// // PluginCmdComplete completes with possible choices for the `> plugin` command
// func PluginCmdComplete(input string) (chosen string, suggestions []string) {
// for _, cmd := range []string{"install", "remove", "search", "update", "list"} {
// if strings.HasPrefix(cmd, input) {
// suggestions = append(suggestions, cmd)
// }
// }
//
// if len(suggestions) == 1 {
// chosen = suggestions[0]
// }
// return chosen, suggestions
// }
//
// // PluginnameComplete completes with the names of loaded plugins
// func PluginNameComplete(input string) (chosen string, suggestions []string) {
// for _, pp := range GetAllPluginPackages() {
// if strings.HasPrefix(pp.Name, input) { // if strings.HasPrefix(pp.Name, input) {
// suggestions = append(suggestions, pp.Name) // suggestions = append(suggestions, pp.Name)
// } // }
// } // }
// //
// if len(suggestions) == 1 { // sort.Strings(suggestions)
// chosen = suggestions[0] // completions := make([]string, len(suggestions))
// for i := range suggestions {
// completions[i] = util.SliceEndStr(suggestions[i], c.X-argstart)
// } // }
// return chosen, suggestions // return completions, suggestions
// }
// // MakeCompletion registers a function from a plugin for autocomplete commands
// func MakeCompletion(function string) Completion {
// pluginCompletions = append(pluginCompletions, LuaFunctionComplete(function))
// return Completion(-len(pluginCompletions))
// } // }

13
internal/buffer/message.go
View File

@@ -13,13 +13,19 @@ const (
MTError MTError
) )
// Message represents the information for a gutter message
type Message struct { type Message struct {
Msg string // The Msg iteslf
Msg string
// Start and End locations for the message
Start, End Loc Start, End Loc
Kind MsgType // The Kind stores the message type
Owner string Kind MsgType
// The Owner of the message
Owner string
} }
// NewMessage creates a new gutter message
func NewMessage(owner string, msg string, start, end Loc, kind MsgType) *Message { func NewMessage(owner string, msg string, start, end Loc, kind MsgType) *Message {
return &Message{ return &Message{
Msg: msg, Msg: msg,
@@ -30,6 +36,7 @@ func NewMessage(owner string, msg string, start, end Loc, kind MsgType) *Message
} }
} }
// NewMessageAtLine creates a new gutter message at a given line
func NewMessageAtLine(owner string, msg string, line int, kind MsgType) *Message { func NewMessageAtLine(owner string, msg string, line int, kind MsgType) *Message {
start := Loc{-1, line - 1} start := Loc{-1, line - 1}
end := start end := start

1
internal/config/rtfiles.go
View File

@@ -42,6 +42,7 @@ func init() {
realFiles = make([][]RuntimeFile, NumTypes) realFiles = make([][]RuntimeFile, NumTypes)
} }
// NewRTFiletype creates a new RTFiletype
func NewRTFiletype() int { func NewRTFiletype() int {
NumTypes++ NumTypes++
allFiles = append(allFiles, []RuntimeFile{}) allFiles = append(allFiles, []RuntimeFile{})

4
internal/util/lua.go
View File

@@ -4,6 +4,8 @@ import (
"unicode/utf8" "unicode/utf8"
) )
// LuaRuneAt is a helper function for lua plugins to return the rune
// at an index within a string
func LuaRuneAt(str string, runeidx int) string { func LuaRuneAt(str string, runeidx int) string {
i := 0 i := 0
for len(str) > 0 { for len(str) > 0 {
@@ -20,6 +22,7 @@ func LuaRuneAt(str string, runeidx int) string {
return "" return ""
} }
// LuaGetLeadingWhitespace returns the leading whitespace of a string (used by lua plugins)
func LuaGetLeadingWhitespace(s string) string { func LuaGetLeadingWhitespace(s string) string {
ws := []byte{} ws := []byte{}
for len(s) > 0 { for len(s) > 0 {
@@ -35,6 +38,7 @@ func LuaGetLeadingWhitespace(s string) string {
return string(ws) return string(ws)
} }
// LuaIsWordChar returns true if the first rune in a string is a word character
func LuaIsWordChar(s string) bool { func LuaIsWordChar(s string) bool {
r, _ := utf8.DecodeRuneInString(s) r, _ := utf8.DecodeRuneInString(s)
return IsWordChar(r) return IsWordChar(r)

1
internal/util/util.go
View File

@@ -418,6 +418,7 @@ func ParseSpecial(s string) string {
return strings.Replace(s, "\\t", "\t", -1) return strings.Replace(s, "\\t", "\t", -1)
} }
// String converts a byte array to a string (for lua plugins)
func String(s []byte) string { func String(s []byte) string {
return string(s) return string(s)
} }

99
runtime/help/colors.md
View File

@@ -3,7 +3,8 @@
This help page aims to cover two aspects of micro's syntax highlighting engine: This help page aims to cover two aspects of micro's syntax highlighting engine:
* How to create colorschemes and use them. * How to create colorschemes and use them.
* How to create syntax files to add to the list of languages micro can highlight. * How to create syntax files to add to the list of languages micro can
highlight.
## Colorschemes ## Colorschemes
@@ -24,32 +25,34 @@ colors can often be configured in the terminal preferences), and additional
color support comes in three flavors. color support comes in three flavors.
* 16-color: A colorscheme that uses the 16 default colors will always work but * 16-color: A colorscheme that uses the 16 default colors will always work but
will only look good if the 16 default colors have been configured to the user's will only look good if the 16 default colors have been configured to the
liking. Using a colorscheme that only uses the 16 colors from the terminal palette user's liking. Using a colorscheme that only uses the 16 colors from the
will also preserve the terminal's theme from other applications since the terminal terminal palette will also preserve the terminal's theme from other
will often use those same colors for other applications. Default colorschemes applications since the terminal will often use those same colors for other
of this type include `simple` and `solarized`. applications. Default colorschemes of this type include `simple` and
`solarized`.
* 256-color: Almost all terminals support displaying an additional 240 colors on * 256-color: Almost all terminals support displaying an additional 240 colors
top of the 16 user-configurable colors (creating 256 colors total). Colorschemes on top of the 16 user-configurable colors (creating 256 colors total).
which use 256-color are portable because they will look the same regardless of Colorschemes which use 256-color are portable because they will look the
the configured 16-color palette. However, the color range is fairly limited same regardless of the configured 16-color palette. However, the color
due to the small number of colors available. Default 256-color colorschemes range is fairly limited due to the small number of colors available.
include `monokai`, `twilight`, `zenburn`, `darcula` and more. Default 256-color colorschemes include `monokai`, `twilight`, `zenburn`,
`darcula` and more.
* true-color: Some terminals support displaying "true color" with 16 million * true-color: Some terminals support displaying "true color" with 16 million
colors using standard RGB values. This mode will be able to support displaying colors using standard RGB values. This mode will be able to support
any colorscheme, but it should be noted that the user-configured 16-color palette displaying any colorscheme, but it should be noted that the user-configured
is ignored when using true-color mode (this means the colors while using the 16-color palette is ignored when using true-color mode (this means the
terminal emulator will be slightly off). Not all terminals support true color colors while using the terminal emulator will be slightly off). Not all
but at this point most do. True color support in micro is off by default but terminals support true color but at this point most do. True color
can be enabled by setting the environment variable `MICRO_TRUECOLOR` to 1. support in micro is off by default but can be enabled by setting the
In addition your terminal must support it (usually indicated by setting `$COLORTERM` environment variable `MICRO_TRUECOLOR` to 1. In addition your terminal
to `truecolor`). must support it (usually indicated by setting `$COLORTERM` to `truecolor`).
True-color colorschemes in micro typically end with `-tc`, such as `solarized-tc`, True-color colorschemes in micro typically end with `-tc`, such as
`atom-dark-tc`, `material-tc`, etc... If true color is not enabled but a true `solarized-tc`, `atom-dark-tc`, `material-tc`, etc... If true color is not
color colorscheme is used, micro will do its best to approximate the colors enabled but a true color colorscheme is used, micro will do its best to
to the available 256 colors. approximate the colors to the available 256 colors.
Here is the list of colorschemes: Here is the list of colorschemes:
@@ -71,16 +74,18 @@ themes the most.
These may vary widely based on the 16 colors selected for your terminal. These may vary widely based on the 16 colors selected for your terminal.
* `simple` * `simple`
* `solarized` (must have the solarized color palette in your terminal to use this colorscheme properly) * `solarized` (must have the solarized color palette in your terminal to use
this colorscheme properly)
* `cmc-16` * `cmc-16`
* `cmc-paper` * `cmc-paper`
* `geany` * `geany`
### True color ### True color
True color requires your terminal to support it. This means that the environment variable True color requires your terminal to support it. This means that the
`COLORTERM` should have the value `truecolor`, `24bit`, or `24-bit`. In addition, to enable environment variable `COLORTERM` should have the value `truecolor`, `24bit`,
true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1. or `24-bit`. In addition, to enable true color in micro, the environment
variable `MICRO_TRUECOLOR` must be set to 1.
* `solarized-tc`: this is the solarized colorscheme for true color. * `solarized-tc`: this is the solarized colorscheme for true color.
* `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme. * `atom-dark-tc`: this colorscheme is based off of Atom's "dark" colorscheme.
@@ -92,9 +97,11 @@ true color in micro, the environment variable `MICRO_TRUECOLOR` must be set to 1
## Creating a Colorscheme ## Creating a Colorscheme
Micro's colorschemes are also extremely simple to create. The default ones can Micro's colorschemes are also extremely simple to create. The default ones can
be found [here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes). be found
[here](https://github.com/zyedidia/micro/tree/master/runtime/colorschemes).
Custom colorschemes should be placed in the `~/.config/micro/colorschemes` directory. Custom colorschemes should be placed in the `~/.config/micro/colorschemes`
directory.
A number of custom directives are placed in a `.micro` file. Colorschemes are A number of custom directives are placed in a `.micro` file. Colorschemes are
typically only 18-30 lines in total. typically only 18-30 lines in total.
@@ -193,9 +200,9 @@ safe and recommended to use subgroups in your custom syntax files.
For example if `constant.string` is found in your colorscheme, micro will us For example if `constant.string` is found in your colorscheme, micro will us
that for highlighting strings. If it's not found, it will use constant instead. that for highlighting strings. If it's not found, it will use constant instead.
Micro tries to match the largest set of groups it can find in the colorscheme Micro tries to match the largest set of groups it can find in the colorscheme
definitions, so if, for examle `constant.bool.true` is found then micro will use definitions, so if, for examle `constant.bool.true` is found then micro will
that. If `constant.bool.true` is not found but `constant.bool` is found micro use that. If `constant.bool.true` is not found but `constant.bool` is found
will use `constant.bool`. If not, it uses `constant`. micro will use `constant.bool`. If not, it uses `constant`.
Here's a list of subgroups used in micro's built-in syntax files. Here's a list of subgroups used in micro's built-in syntax files.
@@ -228,9 +235,9 @@ languages.
Micro's builtin syntax highlighting tries very hard to be sane, sensible and Micro's builtin syntax highlighting tries very hard to be sane, sensible and
provide ample coverage of the meaningful elements of a language. Micro has provide ample coverage of the meaningful elements of a language. Micro has
syntax files built in for over 100 languages now! However, there may be syntax files built in for over 100 languages now! However, there may be
situations where you find Micro's highlighting to be insufficient or not to your situations where you find Micro's highlighting to be insufficient or not to
liking. The good news is that you can create your own syntax files, and place them your liking. The good news is that you can create your own syntax files, and
in `~/.config/micro/syntax` and Micro will use those instead. place them in `~/.config/micro/syntax` and Micro will use those instead.
### Filetype definition ### Filetype definition
@@ -249,9 +256,9 @@ detect:
filename: "\\.go$" filename: "\\.go$"
``` ```
Micro will match this regex against a given filename to detect the filetype. You Micro will match this regex against a given filename to detect the filetype.
may also provide an optional `header` regex that will check the first line of You may also provide an optional `header` regex that will check the first line
the file. For example: of the file. For example:
``` ```
detect: detect:
@@ -262,8 +269,8 @@ detect:
### Syntax rules ### Syntax rules
Next you must provide the syntax highlighting rules. There are two types of Next you must provide the syntax highlighting rules. There are two types of
rules: patterns and regions. A pattern is matched on a single line and usually a rules: patterns and regions. A pattern is matched on a single line and usually
single word as well. A region highlights between two patterns over multiple a single word as well. A region highlights between two patterns over multiple
lines and may have rules of its own inside the region. lines and may have rules of its own inside the region.
Here are some example patterns in Go: Here are some example patterns in Go:
@@ -346,8 +353,8 @@ worry about them.
Syntax file headers are files that contain only the filetype and the detection Syntax file headers are files that contain only the filetype and the detection
regular expressions for a given syntax file. They have a `.hdr` suffix and are regular expressions for a given syntax file. They have a `.hdr` suffix and are
used by default only for the pre-installed syntax files. Header files allow micro used by default only for the pre-installed syntax files. Header files allow
to parse the syntax files much faster when checking the filetype of a certain micro to parse the syntax files much faster when checking the filetype of a
file. Custom syntax files may provide header files in `~/.config/micro/syntax` as certain file. Custom syntax files may provide header files in
well but it is not necessary (only do this if you have many (100+) custom syntax `~/.config/micro/syntax` as well but it is not necessary (only do this if you
files and want to improve performance). have many (100+) custom syntax files and want to improve performance).

37
runtime/help/commands.md
View File

@@ -12,8 +12,8 @@ does not look up environment variables.
# Commands # Commands
Micro provides the following commands that can be executed at the command-bar by Micro provides the following commands that can be executed at the command-bar
pressing `CtrlE` and entering the command. Arguments are placed in single by pressing `CtrlE` and entering the command. Arguments are placed in single
quotes here but these are not necessary when entering the command in micro. quotes here but these are not necessary when entering the command in micro.
* `bind 'key' 'action'`: creates a keybinding from key to action. See the * `bind 'key' 'action'`: creates a keybinding from key to action. See the
@@ -42,33 +42,33 @@ quotes here but these are not necessary when entering the command in micro.
See `replace` command for more information. See `replace` command for more information.
* `set 'option' 'value'`: sets the option to value. See the `options` help topic for * `set 'option' 'value'`: sets the option to value. See the `options` help
a list of options you can set. This will modify your `settings.json` with the topic for a list of options you can set. This will modify your
new value. `settings.json` with the new value.
* `setlocal 'option' 'value'`: sets the option to value locally (only in the current * `setlocal 'option' 'value'`: sets the option to value locally (only in the
buffer). This will *not* modify `settings.json`. current buffer). This will *not* modify `settings.json`.
* `show 'option'`: shows the current value of the given option. * `show 'option'`: shows the current value of the given option.
* `run 'sh-command'`: runs the given shell command in the background. The * `run 'sh-command'`: runs the given shell command in the background. The
command's output will be displayed in one line when it finishes running. command's output will be displayed in one line when it finishes running.
* `vsplit 'filename'`: opens a vertical split with `filename`. If no filename is * `vsplit 'filename'`: opens a vertical split with `filename`. If no filename
provided, a vertical split is opened with an empty buffer. is provided, a vertical split is opened with an empty buffer.
* `hsplit 'filename'`: same as `vsplit` but opens a horizontal split instead of a * `hsplit 'filename'`: same as `vsplit` but opens a horizontal split instead
vertical split. of a vertical split.
* `tab 'filename'`: opens the given file in a new tab. * `tab 'filename'`: opens the given file in a new tab.
* `tabswitch 'tab'`: This command will switch to the specified tab. The `tab` can * `tabswitch 'tab'`: This command will switch to the specified tab. The `tab`
either be a tab number, or a name of a tab. can either be a tab number, or a name of a tab.
* `textfilter 'sh-command'`: filters the current selection through a shell command * `textfilter 'sh-command'`: filters the current selection through a shell
as standard input and replaces the selection with the stdout of the shell command. command as standard input and replaces the selection with the stdout of
For example, to sort a list of numbers, first select them, and then execute the shell command. For example, to sort a list of numbers, first select
`> textfilter sort -n`. them, and then execute `> textfilter sort -n`.
* `log`: opens a log of all messages and debug statements. * `log`: opens a log of all messages and debug statements.
@@ -107,7 +107,8 @@ quotes here but these are not necessary when entering the command in micro.
running `> showkey CtrlC` will display `Copy`. running `> showkey CtrlC` will display `Copy`.
* `term exec?`: Open a terminal emulator running the given executable. If no * `term exec?`: Open a terminal emulator running the given executable. If no
executable is given, this will open the default shell in the terminal emulator. executable is given, this will open the default shell in the terminal
emulator.
--- ---

30
runtime/help/help.md
View File

@@ -1,29 +1,31 @@
# Micro help text # Micro help text
Micro is a terminal-based text editor that aims to be easy to use and intuitive, Micro is a terminal-based text editor that aims to be easy to use and
while also taking advantage of the full capabilities of modern terminals. intuitive, while also taking advantage of the full capabilities of modern
terminals.
To open the command bar, press CtrlE. This enables a `>` prompt for typing To open the command bar, press CtrlE. This enables a `>` prompt for typing
commands. From now on when the documentation says to run a command such as commands. From now on when the documentation says to run a command such as `>
`> help`, this means press CtrlE and type `help` (and press enter to execute help`, this means press CtrlE and type `help` (and press enter to execute the
the command). command).
For a list of the default keybindings run `> help defaultkeys`. For a list of the default keybindings run `> help defaultkeys`.
For more information on keybindings see `> help keybindings`. For more information on keybindings see `> help keybindings`.
## Quick-start ## Quick-start
Press Ctrl-q to quit, and Ctrl-s to save. Press CtrlE to start typing commands and Press Ctrl-q to quit, and Ctrl-s to save. Press CtrlE to start typing commands
you can see which commands are available by pressing tab, or by viewing the help and you can see which commands are available by pressing tab, or by viewing the
topic `> help commands`. help topic `> help commands`.
Move the cursor around with the mouse or the arrow keys. Run Move the cursor around with the mouse or the arrow keys. Run
`> help defaultkeys` to get a quick, easy overview of the default hotkeys and `> help defaultkeys` to get a quick, easy overview of the default hotkeys and
what they do. For more info on rebinding keys, see type `> help keybindings`. what they do. For more info on rebinding keys, see type `> help keybindings`.
If the colorscheme doesn't look good, you can change it with If the colorscheme doesn't look good, you can change it with
`> set colorscheme ...`. You can press tab to see the available colorschemes, or `> set colorscheme ...`. You can press tab to see the available colorschemes,
see more information about colorschemes and syntax highlighting with `> help colors`. or see more information about colorschemes and syntax highlighting with `> help
colors`.
Press Ctrl-w to move between splits, and type `> vsplit filename` or Press Ctrl-w to move between splits, and type `> vsplit filename` or
`> hsplit filename` to open a new split. `> hsplit filename` to open a new split.
@@ -41,14 +43,14 @@ Here are the possible help topics that you can read:
topics topics
* keybindings: Gives a full list of the default keybindings as well as how to * keybindings: Gives a full list of the default keybindings as well as how to
rebind them rebind them
* defaultkeys: Gives a more straight-forward list of the hotkey commands and what * defaultkeys: Gives a more straight-forward list of the hotkey commands and
they do. what they do.
* commands: Gives a list of all the commands and what they do * commands: Gives a list of all the commands and what they do
* options: Gives a list of all the options you can customize * options: Gives a list of all the options you can customize
* plugins: Explains how micro's plugin system works and how to create your own * plugins: Explains how micro's plugin system works and how to create your own
plugins plugins
* colors: Explains micro's colorscheme and syntax highlighting engine and how to * colors: Explains micro's colorscheme and syntax highlighting engine and how
create your own colorschemes or add new languages to the engine to create your own colorschemes or add new languages to the engine
For example, to open the help page on plugins you would run `> help plugins`. For example, to open the help page on plugins you would run `> help plugins`.

47
runtime/help/keybindings.md
View File

@@ -14,16 +14,16 @@ at the end of this document).
If `~/.config/micro/bindings.json` does not exist, you can simply create it. If `~/.config/micro/bindings.json` does not exist, you can simply create it.
Micro will know what to do with it. Micro will know what to do with it.
You can use the alt keys + arrows to move word by word. Ctrl left and right move You can use the alt keys + arrows to move word by word. Ctrl left and right
the cursor to the start and end of the line, and ctrl up and down move the move the cursor to the start and end of the line, and ctrl up and down move the
cursor the start and end of the buffer. cursor the start and end of the buffer.
You can hold shift with all of these movement actions to select while moving. You can hold shift with all of these movement actions to select while moving.
## Rebinding keys ## Rebinding keys
The bindings may be rebound using the `~/.config/micro/bindings.json` file. Each The bindings may be rebound using the `~/.config/micro/bindings.json` file.
key is bound to an action. Each key is bound to an action.
For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the
following in the `bindings.json` file. following in the `bindings.json` file.
@@ -58,9 +58,9 @@ bindings, tab is bound as
"Tab": "Autocomplete|IndentSelection|InsertTab" "Tab": "Autocomplete|IndentSelection|InsertTab"
``` ```
This means that if the `Autocomplete` action is successful, the chain will abort. This means that if the `Autocomplete` action is successful, the chain will
Otherwise, it will try `IndentSelection`, and if that fails too, it will abort. Otherwise, it will try `IndentSelection`, and if that fails too, it
execute `InsertTab`. will execute `InsertTab`.
## Binding commands ## Binding commands
@@ -87,8 +87,9 @@ you could rebind `CtrlG` to `> help`:
} }
``` ```
Now when you press `CtrlG`, `help` will appear in the command bar and your cursor will Now when you press `CtrlG`, `help` will appear in the command bar and your
be placed after it (note the space in the json that controls the cursor placement). cursor will be placed after it (note the space in the json that controls the
cursor placement).
## Binding raw escape sequences ## Binding raw escape sequences
@@ -103,15 +104,15 @@ starting with `0x1b`.
For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the For example, if micro reads `\x1b[1;5D`, on most terminals this will mean the
user pressed CtrlLeft. user pressed CtrlLeft.
For many key chords though, the terminal won't send any escape code or will send For many key chords though, the terminal won't send any escape code or will
an escape code already in use. For example for `CtrlBackspace`, my terminal send an escape code already in use. For example for `CtrlBackspace`, my
sends `\u007f` (note this doesn't start with `0x1b`), which it also sends for terminal sends `\u007f` (note this doesn't start with `0x1b`), which it also
`Backspace` meaning micro can't bind `CtrlBackspace`. sends for `Backspace` meaning micro can't bind `CtrlBackspace`.
However, some terminals do allow you to bind keys to send specific escape However, some terminals do allow you to bind keys to send specific escape
sequences you define. Then from micro you can directly bind those escape sequences you define. Then from micro you can directly bind those escape
sequences to actions. For example, to bind `CtrlBackspace` you can instruct your sequences to actions. For example, to bind `CtrlBackspace` you can instruct
terminal to send `\x1bctrlback` and then bind it in `bindings.json`: your terminal to send `\x1bctrlback` and then bind it in `bindings.json`:
```json ```json
{ {
@@ -123,9 +124,9 @@ Here are some instructions for sending raw escapes in different terminals
### iTerm2 ### iTerm2
In iTerm2, you can do this in `Preferences->Profiles->Keys` then click the `+`, In iTerm2, you can do this in `Preferences->Profiles->Keys` then click the
input your keybinding, and for the `Action` select `Send Escape Sequence`. For `+`, input your keybinding, and for the `Action` select `Send Escape Sequence`.
the above example your would type `ctrlback` into the box (the `\x1b`) is For the above example your would type `ctrlback` into the box (the `\x1b`) is
automatically sent by iTerm2. automatically sent by iTerm2.
### Linux using loadkeys ### Linux using loadkeys
@@ -516,8 +517,8 @@ Additionally, alt keys can be bound by using `Alt-key`. For example `Alt-a` or
This is why in the default keybindings you can see `AltShiftLeft` instead of This is why in the default keybindings you can see `AltShiftLeft` instead of
`Alt-ShiftLeft` (they are equivalent). `Alt-ShiftLeft` (they are equivalent).
Please note that terminal emulators are strange applications and micro only receives Please note that terminal emulators are strange applications and micro only
key events that the terminal decides to send. Some terminal emulators may not receives key events that the terminal decides to send. Some terminal emulators
send certain events even if this document says micro can receive the event. To see may not send certain events even if this document says micro can receive the
exactly what micro receives from the terminal when you press a key, run the `> raw` event. To see exactly what micro receives from the terminal when you press a
command. key, run the `> raw` command.

81
runtime/help/options.md
View File

@@ -2,12 +2,12 @@
Micro stores all of the user configuration in its configuration directory. Micro stores all of the user configuration in its configuration directory.
Micro uses `$MICRO_CONFIG_HOME` as the configuration directory. If this environment Micro uses `$MICRO_CONFIG_HOME` as the configuration directory. If this
variable is not set, it uses `$XDG_CONFIG_HOME/micro` instead. If that environment variable is not set, it uses `$XDG_CONFIG_HOME/micro` instead. If
environment variable is not set, it uses `~/.config/micro` as the configuration that environment variable is not set, it uses `~/.config/micro` as the
directory. In the documentation, we use `~/.config/micro` to refer to the configuration directory. In the documentation, we use `~/.config/micro` to
configuration directory (even if it may in fact be somewhere else if you have refer to the configuration directory (even if it may in fact be somewhere else
set either of the above environment variables). if you have set either of the above environment variables).
Here are the available options: Here are the available options:
@@ -19,11 +19,12 @@ Here are the available options:
* `backup`: micro will automatically keep backups of all open buffers. Backups * `backup`: micro will automatically keep backups of all open buffers. Backups
are stored in `~/.config/micro/backups` and are removed when the buffer is are stored in `~/.config/micro/backups` and are removed when the buffer is
closed cleanly. In the case of a system crash or a micro crash, the contents closed cleanly. In the case of a system crash or a micro crash, the contents
of the buffer can be recovered automatically by opening the file that of the buffer can be recovered automatically by opening the file that was
was being edited before the crash, or manually by searching for the backup being edited before the crash, or manually by searching for the backup in
in the backup directory. Backups are made in the background when a buffer is the backup directory. Backups are made in the background when a buffer is
modified and the latest backup is more than 8 seconds old, or when micro modified and the latest backup is more than 8 seconds old, or when micro
detects a crash. It is highly recommended that you leave this feature enabled. detects a crash. It is highly recommended that you leave this feature
enabled.
default value: `true` default value: `true`
@@ -43,8 +44,9 @@ Here are the available options:
default value: `default` default value: `default`
Note that the default colorschemes (default, solarized, and solarized-tc) Note that the default colorschemes (default, solarized, and solarized-tc)
are not located in configDir, because they are embedded in the micro binary. are not located in configDir, because they are embedded in the micro
binary.
The colorscheme can be selected from all the files in the The colorscheme can be selected from all the files in the
~/.config/micro/colorschemes/ directory. Micro comes by default with three ~/.config/micro/colorschemes/ directory. Micro comes by default with three
@@ -67,29 +69,29 @@ Here are the available options:
default value: `false` default value: `false`
* `fastdirty`: this determines what kind of algorithm micro uses to determine if * `fastdirty`: this determines what kind of algorithm micro uses to determine
a buffer is modified or not. When `fastdirty` is on, micro just uses a if a buffer is modified or not. When `fastdirty` is on, micro just uses a
boolean `modified` that is set to `true` as soon as the user makes an edit. boolean `modified` that is set to `true` as soon as the user makes an edit.
This is fast, but can be inaccurate. If `fastdirty` is off, then micro will This is fast, but can be inaccurate. If `fastdirty` is off, then micro will
hash the current buffer against a hash of the original file (created when the hash the current buffer against a hash of the original file (created when
buffer was loaded). This is more accurate but obviously more resource the buffer was loaded). This is more accurate but obviously more resource
intensive. This option is only for people who really care about having intensive. This option is only for people who really care about having
accurate modified status. accurate modified status.
default value: `true` default value: `true`
* `fileformat`: this determines what kind of line endings micro will use for the * `fileformat`: this determines what kind of line endings micro will use for
file. UNIX line endings are just `\n` (linefeed) whereas dos line endings are the file. UNIX line endings are just `\n` (linefeed) whereas dos line
`\r\n` (carriage return + linefeed). The two possible values for this option endings are `\r\n` (carriage return + linefeed). The two possible values for
are `unix` and `dos`. The fileformat will be automatically detected (when you this option are `unix` and `dos`. The fileformat will be automatically
open an existing file) and displayed on the statusline, but this option is detected (when you open an existing file) and displayed on the statusline,
useful if you would like to change the line endings or if you are starting a but this option is useful if you would like to change the line endings or if
new file. you are starting a new file.
default value: `unix` default value: `unix`
* `filetype`: sets the filetype for the current buffer. Set this option to `off` * `filetype`: sets the filetype for the current buffer. Set this option to
to completely disable filetype detection. `off` to completely disable filetype detection.
default value: `unknown`. This will be automatically overridden depending default value: `unknown`. This will be automatically overridden depending
on the file you open. on the file you open.
@@ -109,8 +111,9 @@ Here are the available options:
* `keepautoindent`: when using autoindent, whitespace is added for you. This * `keepautoindent`: when using autoindent, whitespace is added for you. This
option determines if when you move to the next line without any insertions option determines if when you move to the next line without any insertions
the whitespace that was added should be deleted to remove trailing whitespace. the whitespace that was added should be deleted to remove trailing
By default, the autoindent whitespace is deleted if the line was left empty. whitespace. By default, the autoindent whitespace is deleted if the line
was left empty.
default value: `false` default value: `false`
@@ -125,9 +128,9 @@ Here are the available options:
default value: `true` default value: `true`
* `mkparents`: if a file is opened on a path that does not exist, the file cannot * `mkparents`: if a file is opened on a path that does not exist, the file
be saved because the parent directories don't exist. This option lets micro cannot be saved because the parent directories don't exist. This option lets
automatically create the parent directories in such a situation. micro automatically create the parent directories in such a situation.
default value: `false` default value: `false`
@@ -141,10 +144,10 @@ Here are the available options:
* `paste`: Treat characters sent from the terminal in a single chunk as a paste * `paste`: Treat characters sent from the terminal in a single chunk as a paste
event rather than a series of manual key presses. If you are pasting using event rather than a series of manual key presses. If you are pasting using
the terminal keybinding (not Ctrl-v, which is micro's default paste keybinding) the terminal keybinding (not Ctrl-v, which is micro's default paste
then it is a good idea to enable this option during the paste and disable keybinding) then it is a good idea to enable this option during the paste
once the paste is over. See `> help copypaste` for details about copying and disable once the paste is over. See `> help copypaste` for details about
and pasting in a terminal environment. copying and pasting in a terminal environment.
default value: `false` default value: `false`
@@ -262,8 +265,8 @@ Here are the available options:
--- ---
Plugin options: all plugins come with a special option to enable or disable them. The option Plugin options: all plugins come with a special option to enable or disable
is a boolean with the same name as the plugin itself. them. The option is a boolean with the same name as the plugin itself.
Any option you set in the editor will be saved to the file Any option you set in the editor will be saved to the file
~/.config/micro/settings.json so, in effect, your configuration file will be ~/.config/micro/settings.json so, in effect, your configuration file will be
@@ -281,9 +284,9 @@ locally rather than globally.
The `colorscheme` option is global only, and the `filetype` option is local The `colorscheme` option is global only, and the `filetype` option is local
only. To set an option locally, use `setlocal` instead of `set`. only. To set an option locally, use `setlocal` instead of `set`.
In the `settings.json` file you can also put set options locally by specifying either In the `settings.json` file you can also put set options locally by specifying
a glob or a filetype. Here is an example which has `tabstospaces` on for all files except Go either a glob or a filetype. Here is an example which has `tabstospaces` on for
files, and `tabsize` 4 for all files except Ruby files: all files except Go files, and `tabsize` 4 for all files except Ruby files:
```json ```json
{ {

272
runtime/help/plugins.md
View File

@@ -97,8 +97,8 @@ function onSave(bp)
end end
``` ```
The `bp` variable is a reference to the bufpane the action is being executed within. The `bp` variable is a reference to the bufpane the action is being executed
This is almost always the current bufpane. within. This is almost always the current bufpane.
All available actions are listed in the keybindings section of the help. All available actions are listed in the keybindings section of the help.
@@ -112,8 +112,8 @@ function onMousePress(view, event)
end end
``` ```
These functions should also return a boolean specifying whether the bufpane should These functions should also return a boolean specifying whether the bufpane
be relocated to the cursor or not after the action is complete. should be relocated to the cursor or not after the action is complete.
## Accessing micro functions ## Accessing micro functions
@@ -129,76 +129,205 @@ micro.Log("Hello")
The packages and functions are listed below (in Go type signatures): The packages and functions are listed below (in Go type signatures):
* `micro` * `micro`
- `TermMessage(msg interface{}...)` - `TermMessage(msg interface{}...)`: temporarily close micro and print a
- `TermError()` message
- `InfoBar()`
- `Log(msg interface{}...)`
- `SetStatusInfoFn(fn string)`
* `micro/config`
- `MakeCommand`
- `FileComplete`
- `HelpComplete`
- `OptionComplete`
- `OptionValueComplete`
- `NoComplete`
- `TryBindKey`
- `Reload`
- `AddRuntimeFilesFromDirectory`
- `AddRuntimeFileFromMemory`
- `AddRuntimeFile`
- `ListRuntimeFiles`
- `ReadRuntimeFile`
- `RTColorscheme`
- `RTSyntax`
- `RTHelp`
- `RTPlugin`
- `RegisterCommonOption`
- `RegisterGlobalOption`
* `micro/shell`
- `ExecCommand`
- `RunCommand`
- `RunBackgroundShell`
- `RunInteractiveShell`
- `JobStart`
- `JobSpawn`
- `JobStop`
- `JobStop`
- `RunTermEmulator`
- `TermEmuSupported`
* `micro/buffer`
- `NewMessage`
- `NewMessageAtLine`
- `MTInfo`
- `MTWarning`
- `MTError`
- `Loc`
- `BTDefault`
- `BTLog`
- `BTRaw`
- `BTInfo`
- `NewBufferFromFile`
- `ByteOffset`
- `Log`
- `LogBuf`
* `micro/util`
- `RuneAt`
- `GetLeadingWhitespace`
- `IsWordChar`
- `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(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(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(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 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 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 public methods of an object returned by any of the functions above.
it is not possible to list all the available functions on this page. Please Unfortunately it is not possible to list all the available functions on this
go to the internal documentation at https://godoc.org/github.com/zyedidia/micro page. Please go to the internal documentation at
to see the full list of available methods. Note that only methods of types that https://godoc.org/github.com/zyedidia/micro to see the full list of available
are available to plugins via the functions above can be called from a plugin. methods. Note that only methods of types that are available to plugins via
For an even more detailed reference see the source code on Github. 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 For example, with a BufPane object called `bp`, you could call the `Save`
in Lua with `bp: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 ```go
micro.InfoBar().Message() micro.InfoBar().Message()
@@ -265,7 +394,8 @@ to plugins though it is rather small.
## Adding help files, syntax files, or colorschemes in your plugin ## 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 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 like to add a help topic to your plugin called `test`, you would create a
`test.md` file, and call the function: `test.md` file, and call the function:
@@ -337,8 +467,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 Then open a pull request at github.com/micro-editor/plugin-channel adding a
to the raw `repo.json` that is in your plugin repository. 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 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"`) should contain the version of the plugin. (Like this: `VERSION = "1.0.0"`)

29
runtime/help/tutorial.md
View File

@@ -1,8 +1,8 @@
# Tutorial # Tutorial
This is a brief intro to micro's configuration system that will give some simple This is a brief intro to micro's configuration system that will give some
examples showing how to configure settings, rebind keys, and use `init.lua` to simple examples showing how to configure settings, rebind keys, and use
configure micro to your liking. `init.lua` to configure micro to your liking.
Hopefully you'll find this useful. Hopefully you'll find this useful.
@@ -21,8 +21,8 @@ future, I will use `> set option value` to indicate pressing CtrlE). The change
will take effect immediately and will also be saved to the `settings.json` file will take effect immediately and will also be saved to the `settings.json` file
so that the setting will stick even after you close micro. so that the setting will stick even after you close micro.
You can also set options locally which means that the setting will only have the You can also set options locally which means that the setting will only have
value you give it in the buffer you set it in. For example, if you have two the value you give it in the buffer you set it in. For example, if you have two
splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in splits open, and you type `> setlocal tabsize 2`, the tabsize will only be 2 in
the current buffer. Also micro will not save this local change to the the current buffer. Also micro will not save this local change to the
`settings.json` file. However, you can still set options locally in the `settings.json` file. However, you can still set options locally in the
@@ -60,20 +60,21 @@ following in `bindings.json`:
Very simple. Very simple.
You can also bind keys while in micro by using the `> bind key action` command, You can also bind keys while in micro by using the `> bind key action` command,
but the bindings you make with the command won't be saved to the `bindings.json` but the bindings you make with the command won't be saved to the
file. `bindings.json` file.
For more information about keybindings, like which keys can be bound, and For more information about keybindings, like which keys can be bound, and what
what actions are available, see the `keybindings` help topic (`> help keybindings`). actions are available, see the `keybindings` help topic (`> help keybindings`).
### Configuration with Lua ### Configuration with Lua
If you need more power than the json files provide, you can use the `init.lua` If you need more power than the json files provide, you can use the `init.lua`
file. Create it in `~/.config/micro`. This file is a lua file that is run when file. Create it in `~/.config/micro`. This file is a lua file that is run when
micro starts and is essentially a one-file plugin. The plugin name is `initlua`. micro starts and is essentially a one-file plugin. The plugin name is
`initlua`.
This example will show you how to use the `init.lua` file by creating This example will show you how to use the `init.lua` file by creating a binding
a binding to `CtrlR` which will execute the bash command `go run` on the current file, to `CtrlR` which will execute the bash command `go run` on the current file,
given that the current file is a Go file. given that the current file is a Go file.
You can do that by putting the following in `init.lua`: You can do that by putting the following in `init.lua`:
@@ -98,8 +99,8 @@ function gorun(bp)
end end
``` ```
Alternatively, you could get rid of the `TryBindKey` line, and put this line in the Alternatively, you could get rid of the `TryBindKey` line, and put this line in
`bindings.json` file: the `bindings.json` file:
```json ```json
{ {